Copilot instructions

1<!-- PR generation instructions initial created from https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions#creating-repository-wide-custom-instructions -->
2 
3# Copilot Cloud Agent Instructions for `keycloak/keycloak`
4 
5## Repository at a glance
6- Monorepo with a Maven multi-module Java codebase plus JavaScript/TypeScript UIs.
7- Main server/runtime work is centered around `quarkus/`, `services/`, `server-spi*`, `model/`, and `tests/`.
8- Frontend code lives in `js/` (PNPM workspace with apps/libs).
9 
10## Required toolchain
11- Use Maven Wrapper, not system Maven: `./mvnw`.
12- JDK: 17, 21, or 25 (CI uses 25 for most jobs, with some workflows pinned to 21; the Maven compiler release is 17).
13- Node.js: 24+ for UI work (`js/apps/admin-ui/CONTRIBUTING.md`).
14- PNPM workspace is managed from `js/`.
15 
16## How to work efficiently
171. Scope your change first (avoid broad refactors; keep unrelated files untouched).
182. Prefer targeted Maven module builds/tests over full-repo runs (full runs can take hours).
193. Mirror CI commands/profiles when possible to avoid local-vs-CI drift.
204. For Java formatting checks, run Spotless from repo root.
21 
22## High-value commands
23 
24### Formatting / lint checks
25- `./mvnw -Pdocs,distribution,operator spotless:check`
26- `./mvnw -Pdocs,distribution,operator spotless:apply` (only when you intentionally want automatic formatting changes)
27 
28### Fast focused Maven build/test pattern
29- Build a focused module with required profile(s):
30  - `./mvnw install -Pdistribution -DskipTests -DskipExamples -DskipTestsuite -DskipAdapters -DskipDocs -pl <module> -am`
31- Run tests for the same focused module:
32  - `./mvnw test -Pdistribution -DskipExamples -DskipTestsuite -DskipAdapters -DskipDocs -pl <module> -am`
33 
34### Common full/large build references
35- Build without tests: `./mvnw clean install -DskipTests`
36- Build and test everything: `./mvnw clean install` (very slow)
37- Build server distribution only: `./mvnw -pl quarkus/deployment,quarkus/dist -am -DskipTests clean install`
38 
39### UI workflow (when changing `js/`)
40- From `js/`: `pnpm install`
41- Lint a specific package (example Admin UI): `pnpm -C apps/admin-ui lint`
42- Build the full workspace: `pnpm build`
43 
44## Testing strategy guidance
45- Start with tests closest to changed modules.
46- Use root CI helper for unit-test module selection when needed:
47  - `.github/scripts/find-modules-with-unit-tests.sh`
48- See `docs/tests-development.md` and `docs/tests.md` for running `testsuite/integration-arquillian` tests. Note `testsuite/DEPRECATED.md` - do not create new tests under `testsuite`.
49- If integration tests are needed, they belong under `tests`; see `tests/docs/README.md`
50 
51## Repository-specific expectations
52- Every PR should map to a GitHub issue and keep a focused scope (`CONTRIBUTING.md`).
53- Include docs/tests when behavior changes.
54- Do not introduce new test frameworks or broad formatting/refactoring unrelated to the task.
55 
56<!-- Review instructions from https://docs.github.com/en/copilot/tutorials/customize-code-review
57     and https://dev.to/techgirl1908/how-i-taught-github-copilot-code-review-to-think-like-a-maintainer-3l2c
58     It seems like the initial complaint is that it's overly verbose and hallucinates, rather than
59     misses problems, so the instructions are to keep it concise and confident, rather than calling
60     out specific things to check -->
61 
62# General Code Review Standards
63 
64## Review Philosophy
65 
66* Only comment when you have HIGH CONFIDENCE (>85%) that an issue exists
67* Be concise: one or two sentences per comment when possible
68* The code should follow the Testing strategy guidance and other relevant parts of the preceding Copilot Cloud Agent Instructions
69* Focus on actionable feedback, not observations
70* When reviewing text, only comment on clarity issues if the text is genuinely confusing or could lead to errors.
71 
72## Skip Low Value Feedback
73 
74Do not comment on:
75 
76* Formatting
77* Minor naming suggestions
78* Multiple issues in one comment
79