Skip to content
9 changes: 8 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

## [1.5.0] - 2026-11-21

### Added

- With `approve` on and the new `approver-private-key` input, the approval is submitted as the NCode Review Approver, an app installed with Contents: write on the repositories that approve, with a token minted after the agents exit that can only write pull requests, so the approval meets a ruleset's required approval; the NCode Review app's own earlier approvals are dismissed, and without the key NCode Review approves as its own app, which meets no required approval. `approver-client-id` names the app. `tools/Enable-CodeReview.ps1 -ApproverPrivateKeyPath` stores the key in each repository's `code-review` environment and adds the repository to the approver's installation ([#232](https://github.com/NCodeGroup/code-review/issues/232), [ADR-1011](docs/decisions/1011-the-approval-is-submitted-by-an-approver-app-that-can-write.md)).

### Changed

- The template's `node_lint` answer is on, matching the project's Biome lint: template updates render CI with its `npm run lint` step instead of treating it as the project's own, VS Code recommends the Biome extension, and `docs/best-practices-criteria.md` counts `coding_standards_enforced`, `warnings` and `warnings_fixed` as met ([#219](https://github.com/NCodeGroup/code-review/issues/219)).
Expand Down Expand Up @@ -287,7 +293,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

- The first release: a GitHub composite action that reviews a pull request with reviewers on the Claude Agent SDK and posts the findings as the "Code review" check run, a summary comment and inline threads.

[unreleased]: https://github.com/NCodeGroup/code-review/compare/v1.4.2...HEAD
[unreleased]: https://github.com/NCodeGroup/code-review/compare/v1.5.0...HEAD
[1.5.0]: https://github.com/NCodeGroup/code-review/compare/v1.4.2...v1.5.0
[1.4.2]: https://github.com/NCodeGroup/code-review/compare/v1.4.1...v1.4.2
[1.4.1]: https://github.com/NCodeGroup/code-review/compare/v1.4.0...v1.4.1
[1.4.0]: https://github.com/NCodeGroup/code-review/compare/v1.3.1...v1.4.0
Expand Down
21 changes: 17 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,8 @@ before 1.0.0 changed it in minor releases; their changelog sections say how.
| `service-account-id` | no | `svac_012yav3w3rfhH5i9bAgoWLHe` | The Anthropic service account the federation rule maps to. |
| `workspace-id` | no | `wrkspc_019f5RLk5SG4XWE8XKwWFHZh` | The Anthropic workspace that pays for the review. |
| `approve` | no | `false` | Submits a review whose verdict is Approve as an approving review, so a ruleset can require one approval; every other review stays a comment and dismisses the bot's earlier approval. |
| `approver-private-key` | no | | The NCode Review Approver app's private key, from the repository's code-review environment; with `approve` on, the approval is submitted as the approver, which meets a required approval. |
| `approver-client-id` | no | `Iv23liDPFX1K6NjGIr9i` | The NCode Review Approver app's client ID. |

The action has no outputs. A caller needs:

Expand Down Expand Up @@ -363,13 +365,24 @@ old approval standing. Drafts are approved like any pull request; fork pull requ
The summary comment has an `Approval:` line that says "Approved" or "Not approved" with the reason. When GitHub refuses
an approval, the run warns, dismisses the earlier approval too, and the summary says the approval couldn't be submitted.

GitHub counts an approval toward a ruleset's required approval only from a reviewer that can write to the repository,
whatever its `author_association`. The NCode Review app can't, so its approval counts for Scorecard's Code-Review check
and meets no required approval. With `approver-private-key`, the NCode Review Approver submits the approval instead: an
app with Contents: write and Pull requests: write, installed only on the repositories that approve, whose token is
minted after the agents exit with Pull requests: write alone, so it can't push. The NCode Review app's own earlier
approvals are dismissed, so the pull request carries one approval from NCode Review.
`tools/Enable-CodeReview.ps1 -ApproverPrivateKeyPath` stores the key in each repository's `code-review` environment,
which only the default branch can deploy to, so a pull request's workflow never reads it.

A push removes the approval when the ruleset dismisses stale reviews and requires approval of the last push, and
`/review` approves again. `/run-feedback` and `/run-issues` comment it after each push; after a hand push, comment
`/review` yourself, because NCode Review doesn't review on `synchronize`. Require one approval in the ruleset.
`/review` yourself, because NCode Review doesn't review on `synchronize`. With the approver, require one approval, of
the last push, in the ruleset; without it, require none where one person can write.

The trade-offs: Scorecard's Code-Review check describes human review, so the app's approval may not score as a
person's does, and an NCode Review outage or budget stop blocks merges until it is fixed or the ruleset changes. See
[ADR-1009](docs/decisions/1009-a-clean-review-approves-the-pull-request.md).
The trade-offs: an NCode Review outage or budget stop blocks merges where the approval is required until it is fixed or
the ruleset changes, and a leaked approver key can mint a Contents: write token for the repositories the approver is
installed on. See [ADR-1009](docs/decisions/1009-a-clean-review-approves-the-pull-request.md) and
[ADR-1011](docs/decisions/1011-the-approval-is-submitted-by-an-approver-app-that-can-write.md).

### Outcomes

Expand Down
29 changes: 29 additions & 0 deletions action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,17 @@ inputs:
comment.
required: false
default: 'false'
approver-private-key:
description: >-
The NCode Review Approver app's private key (the NCODE_REVIEW_APPROVER_PRIVATE_KEY secret of the repository's
code-review environment). With approve on, the approval is submitted as the approver, whose approval meets a
ruleset's required approval; without it, NCode Review approves as its own app, whose approval doesn't.
required: false
default: ''
approver-client-id:
description: The NCode Review Approver app's client ID.
required: false
default: Iv23liDPFX1K6NjGIr9i

runs:
using: composite
Expand Down Expand Up @@ -215,6 +226,21 @@ runs:
repositories: ${{ steps.review.outputs.guidance-repository }}
permission-issues: write

# The approver's token, minted after the agents exit, for this repository only and able to write only pull requests:
# the publish step uses it to approve and to dismiss the approver's own approvals. The approver app's write access
# to the repository is what makes GitHub count its approval toward a required approval, while this token can't push.
# It may fail: the publish step then warns and approves with the NCode Review app.
- name: Get the approver's token
id: approver-token
if: steps.review.outputs.reviewed == 'true' && inputs.approve == 'true' && inputs.approver-private-key != ''
continue-on-error: true
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
client-id: ${{ inputs.approver-client-id }}
private-key: ${{ inputs.approver-private-key }}
repositories: ${{ github.event.repository.name }}
permission-pull-requests: write

- name: Publish
id: publish
if: >-
Expand All @@ -229,6 +255,9 @@ runs:
CODE_REVIEW_CHECK_RUN_ID: ${{ steps.ack.outputs.check-run-id }}
CODE_REVIEW_CHECK_RUN_SHA: ${{ steps.ack.outputs.head-sha }}
CODE_REVIEW_APPROVE: ${{ inputs.approve }}
CODE_REVIEW_APPROVER: ${{ inputs.approver-private-key != '' }}
CODE_REVIEW_APPROVER_TOKEN: ${{ steps.approver-token.outputs.token }}
CODE_REVIEW_APPROVER_LOGIN: ${{ steps.approver-token.outputs.app-slug && format('{0}[bot]', steps.approver-token.outputs.app-slug) || '' }}
run: node "$GITHUB_ACTION_PATH/src/publish.ts"

# Completes the check run when the publish step didn't, so it never stays in progress: neutral "Review budget used
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 1009. A clean review approves the pull request

- **Status:** Accepted
- **Status:** Accepted (amended by [1011](1011-the-approval-is-submitted-by-an-approver-app-that-can-write.md))
- **Date:** 2026-11-15
- **Deciders:** Marcin Polewski

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# 1011. The approval is submitted by an approver app that can write

- **Status:** Accepted
- **Date:** 2026-11-21
- **Deciders:** Marcin Polewski
- **Amends:** 1009

## Context

GitHub counts an approval toward a ruleset's required approval only from a reviewer that can write to the repository,
whatever its `author_association`. The NCode Review app can't write to a repository, so its approval counts for
Scorecard's Code-Review check and meets no required approval
([#232](https://github.com/NCodeGroup/code-review/issues/232)).

[NCodeGroup/project-template#460](https://github.com/NCodeGroup/project-template/issues/460) tested five legs:

- An app with no Contents access: its approval isn't counted.
- An app installed with Contents: write: its approval is counted, even when the token that submitted it has Pull
requests: write alone and can't create a branch.
- GitHub checks write access when the review is read, not when it is submitted.
- The `author_association` of an app's review is `NONE` throughout, so it doesn't decide the count.
- While "Allow GitHub Actions to create and approve pull requests" is on, an approval by the workflow's `GITHUB_TOKEN`
with Pull requests: write counts too, and a pull request that adds such a workflow approves itself.

## Decision

The action takes a second app, the NCode Review Approver, which has Contents: write and Pull requests: write and is
installed only on the repositories that approve.

- Its token is minted in a step after the review step, for this repository only, with `permission-pull-requests: write`
alone, so no token it is given can push. The token reaches only the Publish step, which uses it to approve and to
dismiss its own approvals.
- Its key is a secret of each repository's `code-review` environment, which only the default branch can deploy to,
never an organization secret: an organization secret reaches a workflow on any branch, whose author could then
approve their own pull request.
- Without the key, the NCode Review app approves as it does without an approver. With the key but a token step that
failed, the publish step warns and approves with the NCode Review app.
- When the approver approves, the NCode Review app's own earlier approvals are dismissed too, so the pull request
carries one approval from NCode Review. A review that doesn't approve dismisses both apps' approvals.
- The approver's login comes from the token step's `app-slug` output as `<slug>[bot]`, so no input names it.
- `approver-client-id` defaults to the NCode Review Approver's client ID.

## Options considered

1. Give the NCode Review app Contents: write. Rejected: the review app is installed wherever NCode Review runs.
2. The workflow's `GITHUB_TOKEN`. Rejected: it needs "Allow GitHub Actions to create and approve pull requests", which
lets any writer's workflow approve its own pull request.
3. An organization secret for the approver's key. Rejected: any branch's workflow can read it.
4. A dedicated approver app. Chosen: it is installed only on repositories that approve, and its key is used in one step.

## Consequences

- A leaked approver key can mint a Contents: write token for the repositories it is installed on.
- An NCode Review outage or budget stop blocks merges where the approval is required, until it is fixed or the ruleset
changes.
- A repository that approves installs the approver and stores its key with `tools/Enable-CodeReview.ps1
-ApproverPrivateKeyPath`.

## References

- `src/comments.ts` (`applyApproval`, `dismissApprovals`)
- `src/publish.ts`
- `action.yml`
- `tools/Enable-CodeReview.ps1`
- [#232](https://github.com/NCodeGroup/code-review/issues/232)
- [NCodeGroup/project-template#460](https://github.com/NCodeGroup/project-template/issues/460)
3 changes: 2 additions & 1 deletion docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,5 +74,6 @@ records are indexed in [project-template/](project-template/README.md).
| [1006](1006-a-plan-that-reaches-consumers-releases-when-its-pull-request-merges.md) | A plan that reaches consumers releases when its pull request merges, and this repository's own pin is exempt from the Dependabot cooldown | Accepted |
| [1007](1007-a-re-review-larger-than-one-part-is-a-full-review.md) | A re-review whose changed hunks are more than one part of a first review holds is a full review, in parts and under the run's cost ceiling | Accepted |
| [1008](1008-one-problem-gets-one-thread.md) | One problem gets one thread: synthesis merges it across files with an "Also at" list, and a re-review lists a finding its reviewer says repeats an earlier one as already raised | Accepted |
| [1009](1009-a-clean-review-approves-the-pull-request.md) | A clean review approves the pull request when the caller sets `approve: true`, and any other review dismisses the bot's approval | Accepted |
| [1009](1009-a-clean-review-approves-the-pull-request.md) | A clean review approves the pull request when the caller sets `approve: true`, and any other review dismisses the bot's approval | Amended by 1011 |
| [1010](1010-biome-formats-and-lints-the-typescript.md) | Biome formats and lints the TypeScript as biome.json sets, and CI's npm run lint fails on any difference | Accepted |
| [1011](1011-the-approval-is-submitted-by-an-approver-app-that-can-write.md) | With an approver key, the approval is submitted by the NCode Review Approver, an app that can write, with a token that can only write pull requests, so it meets a required approval; amends 1009 | Accepted |
52 changes: 45 additions & 7 deletions src/comments.ts
Original file line number Diff line number Diff line change
Expand Up @@ -172,12 +172,13 @@ export async function submitApproval(
}
}

// Dismisses the bot's own approving reviews of the pull request, so an approval of an earlier head doesn't stand after a
// review that doesn't approve. A failure only warns.
// Dismisses the approving reviews of the pull request that `login` (the NCode Review app by default) submitted, so an
// approval of an earlier head doesn't stand after a review that doesn't approve. A failure only warns.
export async function dismissApprovals(
api: Api,
results: Pick<Results, 'repository' | 'pullRequest' | 'headSha'>,
log: (line: string) => void = writeLog,
login: string = botLogin,
): Promise<void> {
const reviews = `/repos/${results.repository}/pulls/${results.pullRequest}/reviews`;
type ListedReview = { id: number; state?: string; user?: { login?: string } };
Expand All @@ -195,7 +196,7 @@ export async function dismissApprovals(
return;
}
for (const review of listed) {
if (review.user?.login !== botLogin || review.state !== 'APPROVED') continue;
if (review.user?.login !== login || review.state !== 'APPROVED') continue;
try {
await api('PUT', `${reviews}/${review.id}/dismissals`, {
message: `Dismissed: the review at ${results.headSha.slice(0, 7)} doesn't approve.`,
Expand All @@ -207,21 +208,58 @@ export async function dismissApprovals(
}
}

// The approver app's API client and its login, which approves and dismisses its own approvals in place of the NCode
// Review app.
export interface Approver {
api: Api;
login: string;
}

// The approver the publish step's env names: its API and login when the token step minted a token, so the approval
// meets a required approval, and the token, a secret wherever the app's is. `missing` says the caller gave the
// approver's key (CODE_REVIEW_APPROVER is 'true') but no approver came, so NCode Review approves as its own app.
export function approverFromEnv(
env: NodeJS.ProcessEnv,
makeApi: (token: string) => Api,
): { approver?: Approver; token?: string; missing: boolean } {
const token = env['CODE_REVIEW_APPROVER_TOKEN'] || undefined;
const login = env['CODE_REVIEW_APPROVER_LOGIN'] || undefined;
const approver = token && login ? { api: makeApi(token), login } : undefined;
return {
...(approver ? { approver } : {}),
...(token ? { token } : {}),
missing: env['CODE_REVIEW_APPROVER'] === 'true' && !approver,
};
}

// The warning for a run whose caller gave the approver's key but got no approver.
export const approverMissingWarning =
"::warning::The approver's token couldn't be minted, so NCode Review approves with its own app, whose approval meets no required approval.";

// Approves when the review qualifies; otherwise, and when the approval is refused, dismisses the bot's earlier approval,
// so a review that doesn't approve never leaves an old approval standing.
// so a review that doesn't approve never leaves an old approval standing. With an approver, it submits and dismisses
// the approver's approvals, and dismisses the NCode Review app's own too, so one approval from NCode Review stands.
export async function applyApproval(
api: Api,
results: Pick<Results, 'repository' | 'pullRequest' | 'headSha'>,
approve: boolean,
secrets: Iterable<string>,
log: (line: string) => void = writeLog,
approver?: Approver,
): Promise<'approved' | 'not-approved' | 'refused'> {
if (!approve) {
const dismissAll = async () => {
await dismissApprovals(api, results, log);
if (approver) await dismissApprovals(approver.api, results, log, approver.login);
};
if (!approve) {
await dismissAll();
return 'not-approved';
}
if (await submitApproval(api, results, secrets, log)) return 'approved';
await dismissApprovals(api, results, log);
if (await submitApproval(approver?.api ?? api, results, secrets, log)) {
if (approver) await dismissApprovals(api, results, log);
return 'approved';
}
await dismissAll();
return 'refused';
}

Expand Down
Loading