Docs: secrets for agent runs and per-job secrets, agent review token budget (#81)
Covers #77 and #71 beyond their own pages. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL
Canberk Demirci authored · GitHub committed signed1 parent 293e7aecommit 2b53f632f04244789a0ac8748bda77c8c74bcb27Browse files
8 files changed+12−7
Files (8)
- apps/diffinery/docs/accounts/invitations.md+1−1
- apps/diffinery/docs/actions/secrets-and-variables.md+1−1
- apps/diffinery/docs/actions/workflow-permissions.md+1−0
- apps/diffinery/docs/agents/overview.md+1−0
- apps/diffinery/docs/reference/limits.md+3−2
- apps/diffinery/docs/security/audit-log.md+1−1
- apps/diffinery/docs/security/overview.md+2−1
- apps/diffinery/src/docs/api-meta.ts+2−1
modifiedapps/diffinery/docs/accounts/invitations.md+1−1View file
| @@ -261,5 +261,5 @@ | ||
| 261 | 261 | |
| 262 | 262 | - On GitHub anyone can create an account. On Diffinery the only ways in are an invite, an approved access request, or being listed as a bootstrap administrator of the instance. |
| 263 | 263 | - GitHub organization and repository invitations go to existing GitHub users. Diffinery invites go to an email address, and the same link creates the account. |
| 264 | -- **Add people** takes a username or an email address, as on GitHub, but someone who already has an account is added immediately, with no invitation to accept. | |
| 264 | +- **Add people** takes a username or an email address, as on GitHub, but someone added by username joins immediately, with no invitation to accept. An email address always gets an invitation, whether or not it has an account. | |
| 265 | 265 | - Pending invitations of every kind can be revoked, in the web UI, the API or over MCP; otherwise they expire after 14 days. |
modifiedapps/diffinery/docs/actions/secrets-and-variables.md+1−1View file
| @@ -392,7 +392,7 @@ | ||
| 392 | 392 | - Agents can't create, change or delete environments or their branch policies (`403 only repository admins (people, not agents) can manage environments` for an agent with the admin role). |
| 393 | 393 | - Listing repository secret names and environment secret names needs the admin role; listing and reading variables needs the write role, so an agent with write access can read the repository's variable values (organization variables are readable only by organization owners and admins). An agent has the write role unless a person gave it more (its **Maximum role**, or an explicit admin role on the repository). |
| 394 | 394 | |
| 395 | -Agents can still push branches and open pull requests, and the workflows that run for them receive repository and organization secrets (see [Which runs receive secrets](#which-runs-receive-secrets)). Treat write access for an agent as access to those secrets. Environment secrets are different: runs whose code came from an agent only get them from environments set to protected branches only, and never on pull request refs. In those runs the job token also acts as an agent, so it can't push to protected or default branches. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions#runs-whose-code-came-from-an-agent) and [Agents](/docs/agents/overview). | |
| 395 | +Agents can still push branches and open pull requests. The workflows that run for them get no repository or organization secrets unless a repository admin allows it with `agent_runs_use_secrets` (see [Which runs receive secrets](#which-runs-receive-secrets)); where it's allowed, treat write access for an agent as access to those secrets. Environment secrets are different: runs whose code came from an agent only get them from environments set to protected branches only, and never on pull request refs. In those runs the job token also acts as an agent, so it can't push to protected or default branches. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions#runs-whose-code-came-from-an-agent) and [Agents](/docs/agents/overview). | |
| 396 | 396 | |
| 397 | 397 | ## Audit log |
| 398 | 398 |
modifiedapps/diffinery/docs/actions/workflow-permissions.md+1−0View file
| @@ -317,6 +317,7 @@ | ||
| 317 | 317 | - Merges into those branches are blocked with `agents may not merge into this branch; a human must merge`, unless the rule has **Allow agents to merge pull requests** on. The token can still turn on [auto-merge](/docs/collaboration/pull-requests#auto-merge) where the rule has **Allow agents to land pull requests through auto-merge** and a required check; that rule holds for every job token on those branches, agent code or not. |
| 318 | 318 | - A pull request the job opens counts as agent-authored, so it needs at least one approval from a person. |
| 319 | 319 | - A deployment the job records counts as the agent's, so [environment secret rules for agents](/docs/actions/environments#who-receives-environment-secrets) apply. |
| 320 | +- The jobs get no repository or organization secrets, only the job token, unless a repository admin who is a person turns on `agent_runs_use_secrets` (see [Which runs receive secrets](/docs/actions/secrets-and-variables#which-runs-receive-secrets)). | |
| 320 | 321 | |
| 321 | 322 | ## Runs started by the token |
| 322 | 323 |
modifiedapps/diffinery/docs/agents/overview.md+1−0View file
| @@ -131,6 +131,7 @@ | ||
| 131 | 131 | | No environment changes | Creating, changing or deleting an environment or its deployment branch policies fails with `only repository admins (people, not agents) can manage environments`. | None. | |
| 132 | 132 | | Agent reports never satisfy required checks | Commit statuses and check runs an agent reports are shown on the commit, but never count toward a required status check, and aren't counted when a deployment checks the commit's statuses. A failure reported by the real source still fails. | None. Report required checks from workflows or from a person's token. | |
| 133 | 133 | | Workflow runs of agent code act as the agent | A run counts as coming from an agent when an agent triggered it, an agent pushed the branch it runs on last, or (for pull request events) an agent opened the pull request or last pushed its head branch. Re-runs of such a run keep this, whoever starts them, and so do `workflow_run` runs that follow it, since they act on what it produced. The run's jobs act as an agent: their `GITHUB_TOKEN` gets the guardrails in this table, so it can't push or merge to the default or protected branches even with `permissions: contents: write`, and their deployments count as an agent's. Agent-written code can't reach a protected branch through a workflow. | The same per-branch settings, **Allow agents to push directly** and **Allow agents to merge pull requests**. | |
| 134 | +| No repository or organization secrets for agent runs | A run whose code came from an agent (see the row above) gets no repository or organization secrets, only its job token, so an agent can't push a workflow that sends them elsewhere. | A repository admin who is a person ticks **Give runs of agent code the repository's and organization's secrets** under **Settings → Actions** (`agent_runs_use_secrets`). See [Which runs receive secrets](/docs/actions/secrets-and-variables#which-runs-receive-secrets). | | |
| 134 | 135 | | No environment secrets for agent runs on open environments | A job with `environment:` in a run whose code came from an agent (see the row above) gets the environment's secrets only when the environment is limited to protected branches. Pull request runs never get environment secrets. | Limit the environment to **protected branches**. | |
| 135 | 136 | | Agent tags don't match environment tag rules | A tag last pushed or moved by an agent never matches an environment's tag pattern, so it can't deploy to that environment. | Have a person push the tag. | |
| 136 | 137 | | No review dismissal | Dismissing a review fails with `agents can't dismiss reviews`, whatever the agent's role. | None. | |
modifiedapps/diffinery/docs/reference/limits.md+3−2View file
| @@ -241,13 +241,14 @@ | ||
| 241 | 241 | | --- | --- | --- | |
| 242 | 242 | | Review length | 30 minutes | The review stops and its **Agent review** check fails with "The review didn't finish". | |
| 243 | 243 | | Model requests per review | 200 | The model proxy answers `429` to the next request and stops the review; its check fails. | |
| 244 | +| Tokens per review | 2,000,000 by default, settable from 100,000 to 50,000,000 (`tokens_per_review`) | Counted by the model proxy from the provider's usage (cache reads as a tenth). A request whose booked estimate could pass the budget is refused, and the review stops. | | |
| 244 | 245 | | Automatic reviews per pull request | 10 in 24 hours | Later pushes get an action-required check; people with write access can still ask. | |
| 245 | 246 | | Reviews per pull request | 20 in 24 hours, asked for or automatic | The check asks for action, and asking returns `429`. | |
| 246 | -| Reviews per repository | 50 in 24 hours by default, settable from 1 to 1000 (`daily_limit`) | The check asks for action, asking returns `429`, and the admin whose key reviews use gets a `review_limit_reached` email at most once a day. | | |
| 247 | +| Reviews per repository | 50 reviews and autofix runs in 24 hours by default, settable from 1 to 1000 (`daily_limit`) | The check asks for action, asking returns `429`, autofix waits, and the admin whose key reviews use gets a `review_limit_reached` email at most once a day. | | |
| 247 | 248 | | Inline findings per review | 25 | Findings outside the changed lines go in the review's summary. | |
| 248 | 249 | | Changed files in the prompt | 300 | The rest are summed up as `… and N more`. | |
| 249 | 250 | | Review rules in the prompt | 48 KiB | Of the base branch's `REVIEW.md` and `.cursor/BUGBOT.md` files. | |
| 250 | -| Autofix tasks per pull request | 3 | Only for pull requests whose author has write access. | | |
| 251 | +| Autofix tasks per pull request | 3 | Only for pull requests whose author has write access. Autofix runs count toward the repository's daily limit. | | |
| 251 | 252 | |
| 252 | 253 | See [Agent review](/docs/agents/review). |
| 253 | 254 |
modifiedapps/diffinery/docs/security/audit-log.md+1−1View file
| @@ -115,7 +115,7 @@ | ||
| 115 | 115 | | `repo.secret.set`, `repo.secret.delete` | An Actions secret is saved or deleted on **Secrets and variables**, or with `PUT`/`DELETE /api/v3/repos/{owner}/{repo}/actions/secrets/{name}` | `name` (never the value) | |
| 116 | 116 | | `repo.variable.set`, `repo.variable.delete` | An Actions variable is saved or deleted on **Secrets and variables**, or created, updated, renamed or deleted through `/api/v3/repos/{owner}/{repo}/actions/variables` | `name`, and `renamed_from` when a `PATCH` renamed it | |
| 117 | 117 | | `repo.webhook.create`, `repo.webhook.delete` | A webhook is added or deleted on **Webhooks**, or with `POST /api/v3/repos/{owner}/{repo}/hooks` or `DELETE /api/v3/repos/{owner}/{repo}/hooks/{id}` | Web: `url` and `events`, or `id`. API: `id` and `url`, or `id` | |
| 118 | -| `repo.actions_workflow_settings` | An admin changes the repository's workflow permissions on the **Actions** settings tab or with `PUT /api/v3/repos/{owner}/{repo}/actions/permissions/workflow` (see [Workflow permissions](/docs/actions/workflow-permissions)) | the new settings: `defaultPermissions` (`read` or `write`) and `canApprovePullRequests`, plus `via: "api"` when the change came through the API | | |
| 118 | +| `repo.actions_workflow_settings` | An admin changes the repository's workflow permissions on the **Actions** settings tab or with `PUT /api/v3/repos/{owner}/{repo}/actions/permissions/workflow` (see [Workflow permissions](/docs/actions/workflow-permissions)) | the new settings: `defaultPermissions` (`read` or `write`), `canApprovePullRequests` and `agentRunSecrets`, plus `via: "api"` when the change came through the API | | |
| 119 | 119 | | `actions.cache.delete` | Actions caches are deleted with `DELETE /api/v3/repos/{owner}/{repo}/actions/caches?key=...` or `DELETE /api/v3/repos/{owner}/{repo}/actions/caches/{id}` | `key`, `ids`, `via: "api"` | |
| 120 | 120 | | `actions.artifact.delete` | A workflow artifact is deleted with `DELETE /api/v3/repos/{owner}/{repo}/actions/artifacts/{id}` | `id`, `name`, `via: "api"` | |
| 121 | 121 |
modifiedapps/diffinery/docs/security/overview.md+2−1View file
| @@ -155,7 +155,7 @@ | ||
| 155 | 155 | - Agents cannot create, change or delete [environments](/docs/actions/environments) or their deployment branch policies, and cannot set or delete environment secrets (`only repository admins (people, not agents) can manage environments`). |
| 156 | 156 | - Agents cannot dismiss pull request reviews (`agents can't dismiss reviews`). |
| 157 | 157 | - Commit statuses and check runs that agents report are shown, but never satisfy a required check in branch protection or in a merge queue. A deployment created without `required_contexts` also ignores contexts reported by agents. See [Checks and statuses](/docs/collaboration/checks-and-statuses). |
| 158 | -- Workflow runs started by agents receive an environment's secrets only when the environment is limited to protected branches. Tags created or moved by agents never match an environment's tag patterns. | |
| 158 | +- Runs of code an agent wrote get no repository or organization secrets unless a repository admin who is a person allows it (`agent_runs_use_secrets`). Workflow runs started by agents receive an environment's secrets only when the environment is limited to protected branches. Tags created or moved by agents never match an environment's tag patterns. | |
| 159 | 159 | - A workflow run whose code came from an agent (an agent triggered it, pushed the branch last, or opened the pull request, every re-run of such a run, whoever starts it, and every `workflow_run` run that follows it) acts as an agent: its job token is held to these same rules, so it can't push or merge agent-written code into the default branch or a protected branch. |
| 160 | 160 | - Commits that agents create through the API or MCP (including commits made with the git data API and the merge commit of `update-branch`) carry a `diffinery-agent` header naming the agent and who it acts for. |
| 161 | 161 | - The audit log records who an agent acted for, and security emails about an agent (blocked pushes, new tokens) go to its owner. |
| @@ -217,6 +217,7 @@ | ||
| 217 | 217 | |
| 218 | 218 | The runner replaces every secret value with `***` in job logs, step names, job summaries and failure messages: |
| 219 | 219 | |
| 220 | +- A job's runner receives only the secrets the job names (`secrets.NAME`), as on GitHub, so a compromised step can't read the others. | |
| 220 | 221 | - All secrets the job receives are masked, including the job's `GITHUB_TOKEN`. |
| 221 | 222 | - A multi-line secret is also masked line by line. |
| 222 | 223 | - Values shorter than 3 characters are not masked, to keep logs readable. |
modifiedapps/diffinery/src/docs/api-meta.ts+2−1View file
| @@ -1170,7 +1170,7 @@ | ||
| 1170 | 1170 | "GET /repos/{owner}/{repo}/actions/permissions/workflow": { |
| 1171 | 1171 | summary: "Get workflow token permissions", |
| 1172 | 1172 | description: |
| 1173 | - "The defaults for the `GITHUB_TOKEN` of the repository's workflows (GitHub's \"Workflow permissions\" setting). `default_workflow_permissions` is what a job without `permissions:` gets: `read` (contents and packages read, nothing else) or `write` (read and write on every scope except `id-token`). `can_approve_pull_request_reviews` says whether job tokens may open pull requests and approve or request changes. New repositories start with `read` and `false`; repositories created before the setting existed have `write` and `false`. See [Workflow permissions](/docs/actions/workflow-permissions).", | |
| 1173 | + "The defaults for the `GITHUB_TOKEN` of the repository's workflows (GitHub's \"Workflow permissions\" setting). `default_workflow_permissions` is what a job without `permissions:` gets: `read` (contents and packages read, nothing else) or `write` (read and write on every scope except `id-token`). `can_approve_pull_request_reviews` says whether job tokens may open pull requests and approve or request changes. `agent_runs_use_secrets` (a Diffinery addition, `false` by default) says whether runs of code an agent wrote get the repository's and organization's secrets. New repositories start with `read` and `false`; repositories created before the setting existed have `write` and `false`. See [Workflow permissions](/docs/actions/workflow-permissions).", | |
| 1174 | 1174 | access: "admin", |
| 1175 | 1175 | }, |
| 1176 | 1176 | "PUT /repos/{owner}/{repo}/actions/permissions/workflow": { |
| @@ -1182,6 +1182,7 @@ | ||
| 1182 | 1182 | body: { |
| 1183 | 1183 | default_workflow_permissions: ["string", "`read` or `write`."], |
| 1184 | 1184 | can_approve_pull_request_reviews: ["boolean", "Allow workflows' `GITHUB_TOKEN` to open pull requests and to approve or request changes."], |
| 1185 | + agent_runs_use_secrets: ["boolean", "Give runs of code an agent wrote (an agent triggered the run, pushed its branch last, or opened or pushed to its pull request) the repository's and organization's secrets. Default `false`."], | |
| 1185 | 1186 | }, |
| 1186 | 1187 | }, |
| 1187 | 1188 | "GET /repos/{owner}/{repo}/actions/secrets": { summary: "List repository secrets", description: "Names and update times only; values are never returned.", access: "admin" }, |