Skip to content

adding an initial copilot-instructions for pr generation and review #50090

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
shawkins wants to merge 4 commits into
base: main
Choose a base branch
from
+78 −0
Draft

adding an initial copilot-instructions for pr generation and review #50090

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7ec4592
adding an initial copilot-instructions for pr generation and review
shawkins Jun 17, 2026
d996e9f
Apply suggestions from code review
shawkins Jun 17, 2026
f55fc1f
refining the testing instructions
shawkins Jun 17, 2026
dfc6467
Apply suggestions from code review
shawkins Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 78 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
<!-- 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 -->

# Copilot Cloud Agent Instructions for `keycloak/keycloak`

## Repository at a glance
- Monorepo with a Maven multi-module Java codebase plus JavaScript/TypeScript UIs.
- Main server/runtime work is centered around `quarkus/`, `services/`, `server-spi*`, `model/`, and `tests/`.
- Frontend code lives in `js/` (PNPM workspace with apps/libs).

## Required toolchain
- Use Maven Wrapper, not system Maven: `./mvnw`.
- JDK: 17, 21, or 25 (CI uses 25 for most jobs, with some workflows pinned to 21; the Maven compiler release is 17).
- Node.js: 24+ for UI work (`js/apps/admin-ui/CONTRIBUTING.md`).
- PNPM workspace is managed from `js/`.

## How to work efficiently
1. Scope your change first (avoid broad refactors; keep unrelated files untouched).
2. Prefer targeted Maven module builds/tests over full-repo runs (full runs can take hours).
3. Mirror CI commands/profiles when possible to avoid local-vs-CI drift.
4. For Java formatting checks, run Spotless from repo root.

## High-value commands

### Formatting / lint checks
- `./mvnw -Pdocs,distribution,operator spotless:check`
- `./mvnw -Pdocs,distribution,operator spotless:apply` (only when you intentionally want automatic formatting changes)

### Fast focused Maven build/test pattern
- Build a focused module with required profile(s):
- `./mvnw install -Pdistribution -DskipTests -DskipExamples -DskipTestsuite -DskipAdapters -DskipDocs -pl <module> -am`
- Run tests for the same focused module:
- `./mvnw test -Pdistribution -DskipExamples -DskipTestsuite -DskipAdapters -DskipDocs -pl <module> -am`

### Common full/large build references
- Build without tests: `./mvnw clean install -DskipTests`
- Build and test everything: `./mvnw clean install` (very slow)
- Build server distribution only: `./mvnw -pl quarkus/deployment,quarkus/dist -am -DskipTests clean install`

### UI workflow (when changing `js/`)
- From `js/`: `pnpm install`
- Lint a specific package (example Admin UI): `pnpm -C apps/admin-ui lint`
- Build the full workspace: `pnpm build`

## Testing strategy guidance
- Start with tests closest to changed modules.
- Use root CI helper for unit-test module selection when needed:
- `.github/scripts/find-modules-with-unit-tests.sh`
- 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`.
- If integration tests are needed, they belong under `tests`; see `tests/docs/README.md`

## Repository-specific expectations
- Every PR should map to a GitHub issue and keep a focused scope (`CONTRIBUTING.md`).
- Include docs/tests when behavior changes.
- Do not introduce new test frameworks or broad formatting/refactoring unrelated to the task.

<!-- Review instructions from https://docs.github.com/en/copilot/tutorials/customize-code-review
and https://dev.to/techgirl1908/how-i-taught-github-copilot-code-review-to-think-like-a-maintainer-3l2c
It seems like the initial complaint is that it's overly verbose and hallucinates, rather than
misses problems, so the instructions are to keep it concise and confident, rather than calling
out specific things to check -->

# General Code Review Standards

## Review Philosophy

* Only comment when you have HIGH CONFIDENCE (>85%) that an issue exists
* Be concise: one or two sentences per comment when possible
* The code should follow the Testing strategy guidance and other relevant parts of the preceding Copilot Cloud Agent Instructions
* Focus on actionable feedback, not observations
* When reviewing text, only comment on clarity issues if the text is genuinely confusing or could lead to errors.

## Skip Low Value Feedback

Do not comment on:

* Formatting
* Minor naming suggestions
* Multiple issues in one comment