Docs: GitHub importer, GITHUB_TOKEN permissions, auto-merge and everything shipped since #32 (#45)

Covers #28, #29, #31, #36, #37, #42, #43 and #44. Every REST route has hand-written notes; no token can create tokens or agents (browser session only).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL

Canberk Demirci authored 13 days ago· GitHub committed 13 days agosigned1 parent 1e5d220commit 4ac92f20539c991989f65d0d55e9e70709a3c802Browse files

51 files changed+4021−1106

Files (51)

apps/diffinery/docs/accounts/invitations.md+8−3
apps/diffinery/docs/accounts/notifications.md+4−2
apps/diffinery/docs/accounts/organizations.md+190−23
apps/diffinery/docs/accounts/permissions.md+43−19
apps/diffinery/docs/accounts/profile-and-preferences.md+45−11
apps/diffinery/docs/accounts/tokens.md+15−10
apps/diffinery/docs/actions/caching-and-artifacts.md+299−149
apps/diffinery/docs/actions/compatibility.md+148−118
apps/diffinery/docs/actions/docker.md+19−4
apps/diffinery/docs/actions/environments.md+48−22
apps/diffinery/docs/actions/events.md+48−22
apps/diffinery/docs/actions/expressions.md+42−19
apps/diffinery/docs/actions/oidc.md+21−6
apps/diffinery/docs/actions/overview.md+46−16
apps/diffinery/docs/actions/reusable-workflows.md+25−7
apps/diffinery/docs/actions/runners.md+25−5
apps/diffinery/docs/actions/secrets-and-variables.md+133−35
apps/diffinery/docs/actions/workflow-permissions.md+343−0
apps/diffinery/docs/actions/workflow-syntax.md+80−30
apps/diffinery/docs/admin/site-administration.md+25−5
apps/diffinery/docs/agents/mcp.md+57−7
apps/diffinery/docs/agents/overview.md+46−17
apps/diffinery/docs/agents/sandboxes.md+2−1
apps/diffinery/docs/collaboration/checks-and-statuses.md+27−5
apps/diffinery/docs/collaboration/issues.md+87−6
apps/diffinery/docs/collaboration/merge-queue.md+17−6
apps/diffinery/docs/collaboration/pull-requests.md+260−24
apps/diffinery/docs/collaboration/releases.md+9−6
apps/diffinery/docs/concepts.md+24−16
apps/diffinery/docs/index.md+2−2
apps/diffinery/docs/migrate-from-github.md+678−153
apps/diffinery/docs/nav.json+1−0
apps/diffinery/docs/packages/container-registry.md+6−4
apps/diffinery/docs/quickstart.md+13−3
apps/diffinery/docs/reference/limits.md+48−9
apps/diffinery/docs/reference/rest-api.md+121−27
apps/diffinery/docs/reference/webhook-events.md+118−42
apps/diffinery/docs/repositories/branch-protection.md+26−12
apps/diffinery/docs/repositories/browsing-code.md+5−1
apps/diffinery/docs/repositories/git-lfs.md+15−10
apps/diffinery/docs/repositories/git.md+30−7
apps/diffinery/docs/repositories/overview.md+137−29
apps/diffinery/docs/repositories/webhooks.md+9−7
apps/diffinery/docs/security/audit-log.md+48−24
apps/diffinery/docs/security/overview.md+26−18
apps/diffinery/docs/security/push-protection.md+85−21
apps/diffinery/docs/self-hosting/architecture.md+96−34
apps/diffinery/docs/self-hosting/configuration.md+58−11
apps/diffinery/docs/self-hosting/deploy.md+29−41
apps/diffinery/src/docs/api-meta.ts+314−50
apps/diffinery/src/docs/reference.ts+20−7

modifiedapps/diffinery/docs/accounts/invitations.md+8−3View file

modifiedapps/diffinery/docs/accounts/notifications.md+4−2View file

modifiedapps/diffinery/docs/accounts/organizations.md+190−23View file

modifiedapps/diffinery/docs/accounts/permissions.md+43−19View file

modifiedapps/diffinery/docs/accounts/profile-and-preferences.md+45−11View file

modifiedapps/diffinery/docs/accounts/tokens.md+15−10View file

modifiedapps/diffinery/docs/actions/caching-and-artifacts.md+299−149View file

modifiedapps/diffinery/docs/actions/compatibility.md+148−118View file

modifiedapps/diffinery/docs/actions/docker.md+19−4View file

modifiedapps/diffinery/docs/actions/environments.md+48−22View file

modifiedapps/diffinery/docs/actions/events.md+48−22View file

modifiedapps/diffinery/docs/actions/expressions.md+42−19View file

modifiedapps/diffinery/docs/actions/oidc.md+21−6View file

modifiedapps/diffinery/docs/actions/overview.md+46−16View file

modifiedapps/diffinery/docs/actions/reusable-workflows.md+25−7View file

modifiedapps/diffinery/docs/actions/runners.md+25−5View file

modifiedapps/diffinery/docs/actions/secrets-and-variables.md+133−35View file

addedapps/diffinery/docs/actions/workflow-permissions.md+343−0View file

modifiedapps/diffinery/docs/actions/workflow-syntax.md+80−30View file

modifiedapps/diffinery/docs/admin/site-administration.md+25−5View file

modifiedapps/diffinery/docs/agents/mcp.md+57−7View file

modifiedapps/diffinery/docs/agents/overview.md+46−17View file

modifiedapps/diffinery/docs/agents/sandboxes.md+2−1View file

modifiedapps/diffinery/docs/collaboration/checks-and-statuses.md+27−5View file

modifiedapps/diffinery/docs/collaboration/issues.md+87−6View file

modifiedapps/diffinery/docs/collaboration/merge-queue.md+17−6View file

modifiedapps/diffinery/docs/collaboration/pull-requests.md+260−24View file

modifiedapps/diffinery/docs/collaboration/releases.md+9−6View file

modifiedapps/diffinery/docs/concepts.md+24−16View file

modifiedapps/diffinery/docs/index.md+2−2View file

modifiedapps/diffinery/docs/migrate-from-github.md+678−153View file

modifiedapps/diffinery/docs/nav.json+1−0View file

modifiedapps/diffinery/docs/packages/container-registry.md+6−4View file

modifiedapps/diffinery/docs/quickstart.md+13−3View file

modifiedapps/diffinery/docs/reference/limits.md+48−9View file

modifiedapps/diffinery/docs/reference/rest-api.md+121−27View file

modifiedapps/diffinery/docs/reference/webhook-events.md+118−42View file

modifiedapps/diffinery/docs/repositories/branch-protection.md+26−12View file

modifiedapps/diffinery/docs/repositories/browsing-code.md+5−1View file

modifiedapps/diffinery/docs/repositories/git-lfs.md+15−10View file

modifiedapps/diffinery/docs/repositories/git.md+30−7View file

modifiedapps/diffinery/docs/repositories/overview.md+137−29View file

modifiedapps/diffinery/docs/repositories/webhooks.md+9−7View file

modifiedapps/diffinery/docs/security/audit-log.md+48−24View file

modifiedapps/diffinery/docs/security/overview.md+26−18View file

modifiedapps/diffinery/docs/security/push-protection.md+85−21View file

modifiedapps/diffinery/docs/self-hosting/architecture.md+96−34View file

modifiedapps/diffinery/docs/self-hosting/configuration.md+58−11View file

modifiedapps/diffinery/docs/self-hosting/deploy.md+29−41View file

modifiedapps/diffinery/src/docs/api-meta.ts+314−50View file

modifiedapps/diffinery/src/docs/reference.ts+20−7View file

		@@ -38,6 +38,8 @@
38	38
39	39	The page shows "Invite created for <email>" with the link and a copy button: "We emailed it to <email>; you can also send it yourself. It expires in 14 days and works once: they pick a username and create a passkey."
40	40
	41	+An address can have only one pending instance invitation at a time (letter case doesn't matter). A second one is refused with "friend@example.com already has a pending invitation; revoke it first to send a new one"; instance invitations can't be revoked, so send the person the first link again, or wait until it expires after 14 days.
	42	+
41	43	### Add people to an organization
42	44
43	45	Organization owners and admins, and site administrators. The Add people form on the organization's People tab takes a username or an email address.
		@@ -54,7 +56,7 @@
54	56
55	57	The invitation then appears under Pending invitations on the same tab, with who sent it, when, the expiry date and the role. See [Organizations](/docs/accounts/organizations#add-people) for every message the form can show.
56	58
57		-You can send only one pending invitation per email address and organization from this form. To send a new one, revoke the old one first ("friend@example.com already has a pending invitation; revoke it first to send a new one").
	59	+An email address can have only one pending invitation per organization, whether it came from this form, the CLI or the API. Letter case doesn't matter: `Friend@Example.com` and `friend@example.com` are the same address. To send a new one, revoke the old one first ("friend@example.com already has a pending invitation; revoke it first to send a new one").
58	60
59	61	### Revoke an invitation
60	62
		@@ -85,6 +87,7 @@
85	87	\| "acme is an organization; add its people instead" \| Organizations can't be collaborators. \|
86	88	\| "diffy's account is disabled" \| A site administrator disabled the account. \|
87	89	\| "enter a valid email address" \| The text has an `@` but isn't a complete address. \|
	90	+\| "friend@example.com already has a pending invitation; revoke it first to send a new one" \| The address already has an open invitation to this repository (letter case doesn't matter). Repository invitations can't be revoked, so send the person the first link again, or wait until it is used or expires after 14 days. \|
88	91
89	92	The repository's Settings → Collaborators page doesn't list pending invitations. See [Permissions](/docs/accounts/permissions) for what each role allows.
90	93
		@@ -116,7 +119,7 @@
116	119	\| `-r, --role ROLE` \| `member` (default), `admin` or `owner`. Needs `--org`. \|
117	120	\| `--json` \| Print the API response (`id` and `url`) as JSON. \|
118	121
119		-The command prints the invite link and reminds you that it is valid for 14 days. Unlike the web form, `diffinery invite` always creates an invitation, even when the address already has an account (they accept it with Accept invite; see [Accept an invite with an existing account](#accept-an-invite-with-an-existing-account)). The CLI can't create repository invites; use the repository's Settings → Collaborators page. See [CLI reference](/docs/reference/cli) for every command.
	122	+The command prints the invite link and reminds you that it is valid for 14 days. Unlike the web form, `diffinery invite` always creates an invitation, even when the address already has an account (they accept it with Accept invite; see [Accept an invite with an existing account](#accept-an-invite-with-an-existing-account)). It refuses an address that already has a pending invitation to the organization, and an address whose account is already a member of it (see [API errors](#api-errors)). The CLI can't create repository invites; use the repository's Settings → Collaborators page. See [CLI reference](/docs/reference/cli) for every command.
120	123
121	124	## Invite with the API
122	125
		@@ -144,7 +147,7 @@
144	147	{ "id": "3f1c0e8a9b7d4c2e8f6a5b4c3d2e1f0a", "url": "https://diffinery.com/invite/..." }
145	148	```
146	149
147		-The caller must be an owner or admin of the organization, or a site administrator. Only owners (and site administrators) can invite with the `owner` role. Like the CLI, this endpoint always creates an invitation; it doesn't add existing accounts directly.
	150	+The caller must be an owner or admin of the organization, or a site administrator. Only owners (and site administrators) can invite with the `owner` role. Like the CLI, this endpoint always creates an invitation; it doesn't add existing accounts directly. It refuses an address that already has a pending invitation to the organization (compared without regard to letter case) and the address of an account that is already a member.
148	151
149	152	### Instance invite
150	153
		@@ -173,6 +176,8 @@
173	176	\| 404 \| `not found` \| The organization doesn't exist, or the name is not an organization. \|
174	177	\| 422 \| `a valid email is required` \| The `email` field is missing or isn't an email address. \|
175	178	\| 422 \| `role must be member, admin or owner` \| `role` has another value. \|
	179	+\| 422 \| `friend@example.com already has a pending invitation; revoke it first to send a new one` \| The address already has an open invitation to this organization (or, for `POST /api/v3/invitations`, an open instance invitation). Letter case doesn't matter. Revoke the organization invitation on the People tab first. \|
	180	+\| 422 \| `diffy is already a member of this organization` \| The address belongs to an account that is already a member. Change their role on the People tab instead. \|
176	181
177	182	Error bodies are JSON: `{"message": "...", "documentation_url": "..."}`.
178	183

		@@ -144,6 +144,8 @@
144	144	-H "Authorization: Bearer dfy_..."
145	145	```
146	146
	147	+Watching, ignoring and subscribing to issues also work on archived repositories, which otherwise refuse every change.
	148	+
147	149	`GET /api/v3/repos/{owner}/{repo}/subscription` returns `{"subscribed": true\|false, "ignored": true\|false, ...}`, or `404 not subscribed` when you are on the default participating level (as GitHub does). `PUT` with `{"subscribed": false}` also returns you to participating. Changing the level needs a `write` or `admin` token.
148	150
149	151	## Subscribe to or mute an issue or pull request
		@@ -231,8 +233,8 @@
231	233	\| `token_created` \| `[Diffinery] A personal access token was added to your account` (or `A token was created for the agent review-bot`) \| Security \| `security_alert` \| A token was created for you or your agent, from the web UI, CLI or API \|
232	234	\| `token_expiring` \| `[Diffinery] Your token "ci-deploy" expires on <date>` \| Security \| `security_alert` \| About 7 days before a token expires (once per token, for tokens that last more than 8 days) \|
233	235	\| `agent_created` \| `[Diffinery] A new agent was added: review-bot` \| Security \| `security_alert` \| You created an agent \|
234		-\| `push_blocked` \| `[acme/website] Your push was blocked: possible secrets` \| Security \| `security_alert` \| Push protection rejected your push (for an agent's push, its owner is told) \|
235		-\| `push_bypassed` \| `[acme/website] Push protection was bypassed` \| Security \| `security_alert` \| A repository admin pushed past push protection; sent to the pusher and the repository's admins \|
	236	+\| `push_blocked` \| `[acme/website] Your push was blocked: possible secrets` \| Security \| `security_alert` \| Push protection rejected your `git push` (for an agent's push, its owner is told). Commits refused in the web editor, the REST API or MCP are shown as an error and send no email. \|
	237	+\| `push_bypassed` \| `[acme/website] Push protection was bypassed` \| Security \| `security_alert` \| A repository admin pushed past push protection, or committed a flagged file through the commits API with `allow_secrets`; sent to that admin and the repository's admins \|
236	238	\| `account_status` \| `[Diffinery] Your account was disabled` or `Your account was enabled` \| Security \| `account` \| A site administrator disabled your account, or enabled it again \|
237	239	\| `invite` \| `@diffy invited you to join the acme organization on Diffinery` \| Account \| `invitation` \| Someone invited your email address (organization, repository or instance) \|
238	240	\| `welcome` \| `Welcome to Diffinery, @diffy` \| Account \| `account` \| You created your account from an invite \|

		@@ -30,7 +30,7 @@
30	30	\| See published releases, download release assets and source archives (zip and tar) \| Yes \| Yes \| Yes \| Yes \| Yes \|
31	31	\| See commit statuses, check runs, deployments and environments \| Yes \| Yes \| Yes \| Yes \| Yes \|
32	32	\| Watch the repository and subscribe to threads \| Yes \| Yes \| Yes \| Yes \| Yes \|
33		-\| Create, apply and delete labels; set assignees \| No \| Yes \| Yes \| Yes \| Yes \|
	33	+\| Create, apply and delete labels; set assignees (labels and assignees sent by someone below triage, when opening or editing an issue or pull request, are dropped) \| No \| Yes \| Yes \| Yes \| Yes \|
34	34	\| Edit, close or reopen anyone's issue or pull request \| No \| Yes \| Yes \| Yes \| Yes \|
35	35	\| Request reviewers on anyone's pull request \| No \| Yes \| Yes \| Yes \| Yes \|
36	36	\| Lock and unlock conversations; comment and react on locked ones \| No \| Yes \| Yes \| Yes \| Yes \|
		@@ -38,7 +38,7 @@
38	38	\| Create, update and delete branches and refs through the API; commit files in the web editor or API \| No \| No \| Yes \| Yes \| Yes \|
39	39	\| Open pull requests \| No \| No \| Yes \| Yes \| Yes \|
40	40	\| Approve or request changes on a pull request (not your own) \| No \| No \| Yes \| Yes \| Yes \|
41		-\| Merge pull requests, add them to or remove them from a merge queue \| No \| No \| Yes \| Yes \| Yes \|
	41	+\| Merge pull requests, add them to or remove them from a merge queue, turn [auto-merge](/docs/collaboration/pull-requests#auto-merge) on or off \| No \| No \| Yes \| Yes \| Yes \|
42	42	\| Resolve review threads \| No \| No \| Yes \| Yes \| Yes \|
43	43	\| Run, cancel and re-run workflows \| No \| No \| Yes \| Yes \| Yes \|
44	44	\| Report check runs and commit statuses (`POST /repos/{owner}/{repo}/check-runs`, `POST /repos/{owner}/{repo}/statuses/{sha}`) \| No \| No \| Yes \| Yes \| Yes \|
		@@ -54,23 +54,25 @@
54	54	\| Dismiss a review on someone else's pull request (people only) \| No \| No \| No \| Yes \| Yes \|
55	55	\| Change settings: name, description, visibility, default branch \| No \| No \| No \| No \| Yes \|
56	56	\| Archive, unarchive and delete the repository \| No \| No \| No \| No \| Yes \|
	57	+\| Transfer the repository to your own account or an organization you own or administer (people only; a personal repository only by its owner) \| No \| No \| No \| No \| Yes \|
57	58	\| Add, change and remove collaborators; invite by email \| No \| No \| No \| No \| Yes \|
58	59	\| Manage branch protection rules \| No \| No \| No \| No \| Yes \|
59	60	\| List, set and delete Actions secrets; set and delete variables \| No \| No \| No \| No \| Yes \|
60	61	\| Create, change and delete environments, their deployment branch policies and secrets (people only) \| No \| No \| No \| No \| Yes \|
61	62	\| Set and delete environment variables \| No \| No \| No \| No \| Yes \|
62	63	\| Set repository topics \| No \| No \| No \| No \| Yes \|
	64	+\| Change the repository's workflow permissions setting: the default `GITHUB_TOKEN` permissions and whether workflows may create and approve pull requests (people only) \| No \| No \| No \| No \| Yes \|
63	65	\| Delete other people's reactions \| No \| No \| No \| No \| Yes \|
64	66	\| Manage webhooks \| No \| No \| No \| No \| Yes \|
65	67	\| Run self-hosted runners for the repository (`diffinery runner`) \| No \| No \| No \| No \| Yes \|
66		-\| Bypass branch protection: push past it, or merge past unmet rules by asking to (`"bypass_rules": true`), unless the rule turns on Do not allow administrators to bypass these rules (people only for merges) \| No \| No \| No \| No \| Yes \|
67		-\| Push past push protection with `git push -o allow-secrets=<reason>` (people only) \| No \| No \| No \| No \| Yes \|
	68	+\| Bypass branch protection: push past it, merge past unmet rules by asking to (`"bypass_rules": true`), or merge without the merge queue by asking to (`"bypass_merge_queue": true`), unless the rule turns on Do not allow administrators to bypass these rules (people only for merges) \| No \| No \| No \| No \| Yes \|
	69	+\| Commit past push protection with `git push -o allow-secrets=<reason>`, or with `allow_secrets` on `POST /repos/{owner}/{repo}/diffinery/commits` (people only) \| No \| No \| No \| No \| Yes \|
68	70
69	71	Some actions have extra conditions on top of the role:
70	72
71		-- Branch protection can block pushes and merges for every role below admin, and for admins too when the rule enforces administrators. An admin's merge only skips unmet rules when they ask for it explicitly (Merge without waiting for requirements (bypass) in the web UI, `"bypass_rules": true` in the API, `diffinery pr merge --admin`), and the bypass is written to the audit log as `pull_request.merge_bypassed`. See [Branch protection](/docs/repositories/branch-protection).
	73	+- Branch protection can block pushes and merges for every role below admin, and for admins too when the rule enforces administrators. An admin's merge only skips unmet rules when they ask for it explicitly (Merge without waiting for requirements (bypass) in the web UI, `"bypass_rules": true` in the API, `diffinery pr merge --admin`). Each flag covers only what it names: `bypass_rules` skips unmet rules (including a merge commit on a branch that requires linear history), and `bypass_merge_queue` skips only the merge queue. Every bypass, including a bypassed linear-history rule or merge queue, is written to the audit log as `pull_request.merge_bypassed`. See [Branch protection](/docs/repositories/branch-protection).
72	74	- The `read` role's actions that change something (opening issues, commenting, reacting, comment-only reviews, watching) need a signed-in account. Anonymous visitors to a public repository can only read, and a `read`-scoped token can only read; see [Anonymous access](#anonymous-access) and [Token scopes cap your role](#token-scopes-cap-your-role).
73		-- An archived repository refuses pushes and most changes with "repository is archived (read-only)", for every role. Unarchiving, the admin settings (collaborators, branch protection, webhooks, secrets and variables) and, for now, opening and editing issues, comments, reviews and review requests through the REST API and MCP still work. See [Archive a repository](/docs/repositories/overview#archive-a-repository).
	75	+- An archived repository refuses every write with `403 repository is archived (read-only)`, for every role and from the web UI, Git, the REST API and MCP alike: pushes, issues, comments, reviews, settings, collaborators, branch protection, secrets, variables and webhooks. Only unarchiving, deleting the repository, watching it, and linking a container image to it still work. See [Archive a repository](/docs/repositories/overview#archive-a-repository).
74	76	- You can't approve or request changes on your own pull request, and you can't dismiss reviews on it.
75	77	- Pull requests opened by agents always need at least one approval from a person.
76	78
		@@ -84,12 +86,13 @@
84	86	\| --- \| --- \|
85	87	\| You own the repository (a personal repository) \| admin \|
86	88	\| You are an owner or admin of the organization that owns it \| admin \|
87		-\| You are a member of the organization that owns it \| the organization's base permission: `read` by default, or `none`, `write` or `admin` as its owners set it \|
	89	+\| You are a member of the organization that owns it \| the organization's base permission: `none`, `read`, `write` or `admin` (`read` for new organizations) \|
	90	+\| You created it in an organization as a member \| admin (you are added as an `admin` collaborator) \|
88	91	\| You were added as a collaborator on the repository (Settings → Collaborators, an accepted repository invite, or `PUT /repos/{owner}/{repo}/collaborators/{username}`) \| the role you were given \|
89	92	\| The repository is public \| read \|
90	93	\| You are a site administrator \| admin on every repository \|
91	94
92		-Because the highest role wins, a collaborator entry can raise an organization member's access but can't lower it. Accounts that are pending or disabled have no role anywhere.
	95	+Because the highest role wins, a collaborator entry can raise an organization member's access above the base permission but can't lower it. Accounts that are pending or disabled have no role anywhere.
93	96
94	97	### Collaborators
95	98
		@@ -116,15 +119,15 @@
116	119
117	120	## Organization roles
118	121
119		-Organizations have their own three roles, which map onto repository roles for every repository the organization owns:
	122	+Organizations have their own three roles, which map onto repository roles for every repository the organization owns. Members get the organization's base permission, which owners choose:
120	123
121	124	\| Organization role \| Role on organization repositories \| Can also \|
122	125	\| --- \| --- \| --- \|
123		-\| member \| the base permission (`read` by default) \| Create repositories (which they administer) and container images in the organization \|
	126	+\| member \| The base permission: `none`, `read`, `write` or `admin` \| Create repositories (and get `admin` on the ones they create) and container images in the organization \|
124	127	\| admin \| admin \| Manage members (except owners), invites, agents and organization secrets \|
125		-\| owner \| admin \| Everything an admin can, plus manage owners and the organization's Settings tab (name, display name, picture) \|
	128	+\| owner \| admin \| Everything an admin can, plus manage owners and the organization's Settings tab (name, display name, base permission, picture) \|
126	129
127		-See [Organizations](/docs/accounts/organizations) for details.
	130	+New organizations start with a base permission of `read`; organizations that existed before the setting was added use `write`. Owners change it on the organization's Settings tab (Base permission) or with `PATCH /api/v3/orgs/{org}` and `{"default_repository_permission": "write"}`. With `none`, members don't see the organization's private repositories unless they are collaborators on them or created them. See [Base permission](/docs/accounts/organizations#base-permission) for details.
128	131
129	132	## Site administrators
130	133
		@@ -166,10 +169,11 @@
166	169	\| Create a repository (`POST /api/v3/user/repos`, `POST /api/v3/orgs/{org}/repos`) \| a `write` or `admin` token that isn't restricted to repositories, or a browser session \|
167	170	\| Mark notifications read, change notification settings, send a test email \| a `write` or `admin` token that isn't restricted to repositories, or a browser session \|
168	171	\| Watch or unwatch a repository \| a `write` or `admin` token, or a browser session \|
169		-\| Upload or remove your profile picture or an organization's (`PUT`/`DELETE /api/v3/user/avatar`, `/api/v3/orgs/{org}/avatar`) \| a `write` or `admin` token that isn't restricted to repositories, or a browser session \|
	172	+\| Upload or remove your profile picture or an organization's (`PUT`/`DELETE /api/v3/user/avatar`, `/api/v3/orgs/{org}/avatar`; organization owners only) \| a `write` or `admin` token that isn't restricted to repositories, or a browser session \|
170	173	\| Create a token (`POST /api/v3/diffinery/tokens`, `diffinery token create`) \| an `admin` token or a browser session \|
171	174	\| Revoke a token, create an organization, invite people, manage organization secrets, create agents and agent tokens, disable agents \| an `admin` token that isn't restricted to repositories, or a browser session \|
172	175	\| Send every email template (site administrators) \| an `admin` token that isn't restricted to repositories, or a browser session \|
	176	+\| Change an organization's display name or base permission (`PATCH /api/v3/orgs/{org}`, owners only) \| an `admin` token that isn't restricted to repositories, or a browser session \|
173	177	\| Change your username, display name or appearance \| a browser session; there is no API \|
174	178	\| Add or remove passkeys, sign out other browsers \| a browser session; tokens can't do this \|
175	179
		@@ -193,7 +197,7 @@
193	197
194	198	- Agents can't push to the default branch or any protected branch, unless a protection rule turns on Allow agents to push directly (`agentsMayPush`). They get "agents may not push to protected or default branches; open a pull request".
195	199	- Agents can't merge into the default branch or a protected branch, unless the rule turns on Allow agents to merge pull requests (`agentsMayMerge`).
196		-- A pull request opened by an agent needs at least one approving review from a person, and approvals from agents never count toward required approvals.
	200	+- A pull request opened by an agent needs at least one approving review from a person. Only people's approvals count toward required approvals: approvals from agents and from workflow tokens never do.
197	201	- Agents can never bypass push protection, and the merge-protection bypass for admins (`"bypass_rules": true`) applies only to people.
198	202	- Check runs and commit statuses reported by agents never satisfy a required status check.
199	203	- Agents can't dismiss reviews.
		@@ -209,16 +213,36 @@
209	213
210	214	\| Token \| Prefix \| Where it comes from \| What it can do on the repository \|
211	215	\| --- \| --- \| --- \| --- \|
212		-\| Job token \| `djt_` \| Each workflow job gets one as `GITHUB_TOKEN` (also `DIFFINERY_TOKEN`) \| Act as `diffinery-actions[bot]` with `read` on the repository the job runs in. Container images follow the job's `permissions: packages`: it pulls its owner's images and pushes only to images linked to its own repository (creating them, linked, on first push) \|
213		-\| Sandbox token \| `dst_` \| Each agent sandbox gets one \| Act as the person or agent that started the sandbox, capped at `write`, on that repository only \|
	216	+\| Job token \| `djt_` \| Each workflow job gets one as `GITHUB_TOKEN` (also `DIFFINERY_TOKEN`) \| Act as `diffinery-actions[bot]` with what the workflow's `permissions:` grant (see below). Container images follow the job's `permissions: packages`: it pulls its owner's images and pushes only to images linked to its own repository (creating them, linked, on first push) \|
	217	+\| Sandbox token \| `dst_` \| Each agent sandbox gets one \| Act as the person or agent that started the sandbox, capped at `write`, on that repository \|
214	218
215		-Both work only for the repository they were issued for, and stop working when the job completes or the sandbox closes. See [Secrets and variables](/docs/actions/secrets-and-variables) and [Sandboxes](/docs/agents/sandboxes).
	219	+Both can also read other public repositories (as anyone can), but no other private repository. They stop working when the job completes or the sandbox closes. See [Secrets and variables](/docs/actions/secrets-and-variables) and [Sandboxes](/docs/agents/sandboxes).
216	220
	221	+### What a job token may do
	222	+
	223	+A job token follows GitHub's `permissions:` model. Its permissions come from the job's `permissions:`, else the workflow's, else the repository's default:
	224	+
	225	+\| Repository default \| Permissions without `permissions:` \|
	226	+\| --- \| --- \|
	227	+\| Read (the default for new repositories) \| `contents` and `packages` read, nothing else \|
	228	+\| Read and write (repositories created before the setting existed) \| Write on every permission except `id-token`, which stays off \|
	229	+
	230	+An admin changes the default, and whether workflows may create and approve pull requests (off by default), on the repository's Settings → Actions tab or with `PUT /api/v3/repos/{owner}/{repo}/actions/permissions/workflow`. See [Workflow permissions](/docs/actions/workflow-permissions) for the details.
	231	+
	232	+On top of its permissions:
	233	+
	234	+- Each endpoint needs its permission (`issues`, `pull-requests`, `contents`, `statuses`, `checks`, `deployments`, `actions` and so on). A request without it gets `403 Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: <scope>: <read or write>)`. Reads of a public repository are always allowed.
	235	+- The token's role is at most `write`, so branch protection always applies to it. Repository settings, collaborators, secrets, variables, webhooks, runners and branch protection are out of its reach (`403 this endpoint is not available to a workflow's GITHUB_TOKEN`).
	236	+- It never creates, changes or deletes files under `.github/workflows/` or `.diffinery/workflows/`, by push, API commit or merge. The refusal reads: refusing to allow a GitHub App to create or update workflow `<path>` without `workflows` permission.
	237	+- It can't open, approve or request changes on pull requests unless the repository allows it, and even then its approvals don't count toward required approvals.
	238	+- A reusable workflow never gets more than its caller.
	239	+- A run whose code came from an agent (an agent triggered it, pushed the branch last, or opened the pull request, and any re-run of such a run, whoever starts it, or `workflow_run` run that follows it) acts as an agent, so the agent guardrails apply: its token can't push or merge to the default branch or a protected branch.
	240	+
217	241	## How permissions differ from GitHub
218	242
219	243	- The five repository roles match GitHub's names. Diffinery's `maintain` adds the ability to move or delete tags and to edit other people's comments; repository settings stay with `admin`.
220	244	- Opening a pull request needs `write`: its head branch must be a branch in the same repository.
221		-- Organization members get the organization's base permission on every organization repository (`read` unless its owners change it), and organization admins get `admin`. There are no teams or custom roles.
	245	+- Organization members get the organization's base permission on every organization repository, as on GitHub, with the same values (`none`, `read`, `write`, `admin`) and the same default for new organizations (`read`). Organization owners and admins get `admin`. There are no teams or custom roles.
222	246	- Personal access tokens have three scopes (`read`, `write`, `admin`) instead of GitHub's fine-grained permissions; the scope caps your role.
223		-- `GITHUB_TOKEN` in a workflow can read the repository and use the container registry; it can't push commits or call write endpoints.
	247	+- `GITHUB_TOKEN` in a workflow follows GitHub's `permissions:` model, but new repositories default to read-only tokens, the token never administers the repository or edits workflow files, and code that came from an agent runs under the agent rules.
224	248	- Agents are a separate account type with their own caps and guardrails.

		@@ -1,9 +1,9 @@
1	1	---
2	2	title: Profile and preferences
3		-description: Change your username and display name, upload or remove a profile picture for yourself or an organization, and choose light, dark or system appearance.
	3	+description: Change your username, display name and profile picture, choose light, dark or system appearance, and link your GitHub account for imports.
4	4	---
5	5
6		-Your profile is how other people see you on Diffinery: your username, display name and profile picture. This page also covers the Appearance setting (light, dark or following your system) and points to every other per-user setting under Settings.
	6	+Your profile is how other people see you on Diffinery: your username, display name and profile picture. This page also covers the Appearance setting (light, dark or following your system), Linked accounts (your GitHub account, for imports) and points to every other per-user setting under Settings.
7	7
8	8	## Where your settings are
9	9
		@@ -18,6 +18,8 @@
18	18	\| Agents \| `/settings/agents` \| Agent accounts you or your organizations own. See [Agents](/docs/agents/overview). \|
19	19	\| Organizations \| `/settings/orgs` \| Organizations you belong to, and creating new ones. See [Organizations](/docs/accounts/organizations). \|
20	20	\| Notifications \| `/settings/notifications` \| What you hear about in the notifications list and by email. See [Notifications](/docs/accounts/notifications). \|
	21	+\| Linked accounts \| `/settings/linked-accounts` \| GitHub accounts linked to yours, so imported work is credited to you. See [Linked accounts](#linked-accounts). \|
	22	+\| Imports \| `/imports` \| The GitHub imports you started, and Import from GitHub. See [Migrate from GitHub](/docs/migrate-from-github). \|
21	23
22	24	Site administrators also see a Site administration group with People and invitations, Email and Audit log (see [Site administration](/docs/admin/site-administration)).
23	25
		@@ -30,7 +32,7 @@
30	32	\| Field \| Editable \| Notes \|
31	33	\| --- \| --- \| --- \|
32	34	\| Username \| Yes \| Your login, the owner part of your repository URLs (`https://diffinery.com/diffy/...`) and your `@mention` handle \|
33		-\| Display name \| Yes \| Optional. Shown on your profile page and in the settings sidebar, with your username under it, and returned as `name` by the API. \|
	35	+\| Display name \| Yes \| Optional. Shown on your profile page and in the settings sidebar, with your username under it, and returned as `name` by the API. If you leave it blank (or enter only spaces), Diffinery shows your username in its place and the API returns `"name": null`. \|
34	36	\| Email \| No \| Your account's email address. Notification emails go here. It can't be changed in Settings. \|
35	37	\| Account type \| No \| `user` for a person \|
36	38	\| Joined \| No \| When the account was created \|
		@@ -42,19 +44,19 @@
42	44
43	45	### Change your username
44	46
45		-A username starts with a letter or digit, then uses letters, digits, `-` and `_`. Dots aren't allowed, and the name can't be reserved (for example `api`, `settings`, `login`, `admin`, `docs`) or already used by a person, organization or agent.
	47	+A username starts with a letter or digit, then uses letters, digits, `-` and `_`, up to 100 characters. Dots aren't allowed, and the name can't be reserved (for example `api`, `settings`, `login`, `admin`, `docs`) or already used by a person, organization or agent. The Username field checks the characters in your browser before you save, with the same rules as the server; the organization and agent name fields work the same way.
46	48
47		-Renaming changes the URL of every repository you own. The old URLs keep working (see [Transfer a repository](/docs/repositories/overview#transfer-a-repository) for how redirects behave), but update existing clones:
	49	+Renaming changes the URL of every repository you own. The old URLs keep working (see [Old URLs after a transfer or rename](/docs/repositories/overview#old-urls-after-a-transfer-or-rename) for how each kind behaves), but update existing clones:
48	50
49	51	```sh
50	52	git remote set-url origin https://diffinery.com/new-name/website.git
51	53	```
52	54
53		-After a rename, `https://diffinery.com/old-name` and your repositories' old web, API and Git URLs redirect to the new name, until someone else takes the old name, which is free for them to take. Your picture moves with you: Diffinery forgets cached copies of the picture under the old name.
	55	+After a rename, `https://diffinery.com/old-name` and your repositories' old web and API URLs redirect to the new name, and Git and container images keep being served under the old name, until someone else takes the old name, which is free for them to take. Your picture moves with you: Diffinery forgets cached copies of the picture under the old name.
54	56
55	57	\| Message \| What to do \|
56	58	\| --- \| --- \|
57		-\| "invalid or reserved login" \| The name breaks the rules above (for example it contains a dot) or is reserved. Pick another. \|
	59	+\| "invalid or reserved login" \| The name is reserved, or breaks the rules above. Pick another. \|
58	60	\| "login already taken" \| Another person, organization or agent uses it. Pick another. \|
59	61
60	62	There is no API for changing your username or display name; use the web UI. `GET /api/v3/user` returns them as `login` and `name`.
		@@ -113,7 +115,7 @@
113	115	2. Under Upload a new picture, choose a file and click Save picture. You see "Organization picture updated."
114	116	3. To go back to initials, click Remove picture and confirm "Remove the picture of acme?". You see "Organization picture removed."
115	117
116		-Through the API, organization owners and admins (and site administrators) can change the picture; see the next section.
	118	+Through the API, organization owners (and site administrators) can change the picture; see the next section. Organization admins and members can't change it.
117	119
118	120	### Agent pictures
119	121
		@@ -127,8 +129,8 @@
127	129	\| --- \| --- \| --- \|
128	130	\| `PUT /api/v3/user/avatar` \| You (the token's account) \| `200` with `{"avatar_url": "..."}` \|
129	131	\| `DELETE /api/v3/user/avatar` \| You \| `200` with `{"avatar_url": "..."}` (the initials URL) \|
130		-\| `PUT /api/v3/orgs/{org}/avatar` \| Owners and admins of the organization, site administrators \| `200` with `{"avatar_url": "..."}` \|
131		-\| `DELETE /api/v3/orgs/{org}/avatar` \| Owners and admins of the organization, site administrators \| `200` with `{"avatar_url": "..."}` \|
	132	+\| `PUT /api/v3/orgs/{org}/avatar` \| Owners of the organization, site administrators \| `200` with `{"avatar_url": "..."}` \|
	133	+\| `DELETE /api/v3/orgs/{org}/avatar` \| Owners of the organization, site administrators \| `200` with `{"avatar_url": "..."}` \|
132	134
133	135	The token needs the `write` or `admin` scope and must not be restricted to repositories. A browser session works too.
134	136
		@@ -170,7 +172,7 @@
170	172	\| --- \| --- \| --- \|
171	173	\| 401 \| `sign in required` \| No token was sent \|
172	174	\| 403 \| `changing a profile picture needs a write or admin token that is not limited to repositories` \| The token has only the `read` scope, or is restricted to repositories \|
173		-\| 403 \| `only organization owners and admins can change its picture` \| You are a member of the organization, but not an owner or admin \|
	175	+\| 403 \| `only organization owners can change its picture` \| You are an admin or member of the organization, but not an owner \|
174	176	\| 404 \| `not found` \| The organization doesn't exist, or you aren't a member \|
175	177	\| 413 \| `That picture is larger than 5 MB. Use a smaller file.` \| The body is over 5 MB \|
176	178	\| 422 \| `Send the picture as the request body.` \| The request had no body \|
		@@ -240,6 +242,38 @@
240	242
241	243	There is no API or CLI command for the appearance setting.
242	244
	245	+## Linked accounts
	246	+
	247	+Settings → Linked accounts (`/settings/linked-accounts`) is the Linked GitHub accounts page. When someone [imports from GitHub](/docs/migrate-from-github), issues, pull requests, comments and reviews written by a linked GitHub account are credited to your Diffinery account instead of a placeholder ("mannequin") for the GitHub user. Link your account before the import runs: work that was already imported stays with the mannequin.
	248	+
	249	+### Link with a public gist
	250	+
	251	+No GitHub token is needed:
	252	+
	253	+1. Under Step 1 · get a code, leave GitHub Enterprise API URL blank for github.com, or enter your GitHub Enterprise API URL (for example `https://ghe.example.com/api/v3`), and click Get my code.
	254	+2. Copy the code (it starts with `diffinery-link-`). On GitHub, create a public gist whose description or one of whose files contains it.
	255	+3. Under Step 2 · verify your gist, enter Your GitHub username on github.com (or on your Enterprise host) and click Verify and link. You see "GitHub account linked."
	256	+
	257	+Diffinery reads your public profile and gists without a token, from that one GitHub host, and stores GitHub's numeric user id with the link, so a later rename of your GitHub account doesn't break it. You can delete the gist afterwards.
	258	+
	259	+### Link with GitHub OAuth
	260	+
	261	+If the site administrator configured a GitHub OAuth app, the page also has Link with GitHub: click Continue to GitHub, approve read-only access to your profile, and you come back with the account linked. OAuth links github.com accounts only; use a gist for GitHub Enterprise.
	262	+
	263	+### Manage your links
	264	+
	265	+- Each link shows the GitHub login, the host (`on github.com`) and when it was linked. Click Unlink and confirm "Unlink diffy?" to remove it; you see "Account unlinked."
	266	+- You can link several GitHub accounts (for example one on github.com and one on an Enterprise host). A GitHub account can be linked to only one Diffinery account.
	267	+- Only people can link accounts; agents can't.
	268	+- Linking, unlinking and a site administrator clearing a link are recorded in the audit log (`account.link_github`, `account.unlink_github`, `account.link_cleared`).
	269	+- The same actions are available in the REST API under `/api/v3/diffinery/user/linked-accounts` with a personal token that has the `admin` scope and isn't restricted to repositories. See [Link your GitHub account](/docs/migrate-from-github#link-your-github-account).
	270	+
	271	+\| Message \| What to do \|
	272	+\| --- \| --- \|
	273	+\| "create a PUBLIC gist whose description or a file contains diffinery-link-..., then try again" \| Make sure the gist is public (not secret) and contains the exact code, then click Verify and link again. \|
	274	+\| "GitHub user diffy was not found" \| Check the username and, for Enterprise, the API URL. \|
	275	+\| "GitHub user diffy is linked to another Diffinery account" \| Unlink it from that account first, or ask a site administrator to clear the link. \|
	276	+
243	277	## Notification preferences
244	278
245	279	Your notification preferences (which groups you hear about in the notifications list and by email, watching new repositories, emails about your own activity) are on Settings → Notifications, and can also be read and changed with `GET` and `PUT /api/v3/diffinery/notification-settings`. See [Notifications](/docs/accounts/notifications#notification-settings).

		@@ -27,7 +27,7 @@
27	27	\| --- \| --- \| --- \|
28	28	\| `read` \| read \| Clone and fetch, download Git LFS objects, read the API, CI that only downloads \|
29	29	\| `write` \| maintain \| Push, issues, pull requests, merging, running workflows; the right choice for most Git and CLI use \|
30		-\| `admin` \| admin \| Everything you can do, including repository settings, collaborators, branch protection, secrets, webhooks, self-hosted runners and creating more tokens \|
	30	+\| `admin` \| admin \| Everything you can do, including repository settings, collaborators, branch protection, secrets, webhooks, self-hosted runners and revoking tokens. No token can create tokens or agents \|
31	31
32	32	The web form describes them as: "read: clone and view · write: push, issues, pull requests, runs (up to maintain) · admin: everything you can do, including settings."
33	33
		@@ -35,7 +35,7 @@
35	35
36	36	A `read` token only reads. Every request that changes something in a repository (any method other than `GET` or `HEAD`) is refused with `403 this token needs the write scope`, even actions the `read` role itself allows, such as opening an issue, commenting, reacting or leaving a comment-only review. Two Git operations use `POST` but only read, and keep working with a `read` token: `git fetch` and `git clone` (`git-upload-pack`) and Git LFS downloads (an LFS batch request for `download`). Pushing and LFS uploads need `write`.
37	37
38		-The scope is checked before your role on the repository. Use a `write` token for anything that opens, comments, pushes or merges, and an `admin` token for repository settings.
	38	+The scope is checked after Diffinery has found a repository you can see, and before your role on it. So a `read` token that tries to change a private repository you can't see gets `404 repository not found`, the same answer as any other request for it, rather than a scope error that would reveal the repository exists. Use a `write` token for anything that opens, comments, pushes or merges, and an `admin` token for repository settings.
39	39
40	40	### Account-level actions
41	41
		@@ -47,6 +47,7 @@
47	47	\| Mark notifications read (`PUT /api/v3/notifications`), change notification settings, send yourself a test email \| `write` or `admin` \| Refused \|
48	48	\| Watch or unwatch a repository (`PUT`/`DELETE /api/v3/repos/{owner}/{repo}/subscription`) \| `write` or `admin` \| Allowed for the listed repositories \|
49	49	\| Upload or remove a profile picture (`/api/v3/user/avatar`, `/api/v3/orgs/{org}/avatar`) \| `write` or `admin` \| Refused \|
	50	+\| Change an organization's display name or base permission (`PATCH /api/v3/orgs/{org}`, owners only) \| `admin` \| Refused \|
50	51	\| Create a token (`POST /api/v3/diffinery/tokens`, `diffinery token create`) \| No token can: a browser session only \| Refused \|
51	52	\| Revoke a token (`DELETE /api/v3/diffinery/tokens/{id}`, `diffinery token revoke`) \| `admin` \| Refused \|
52	53	\| Create an organization (`POST /api/v3/user/orgs`) \| `admin` \| Refused \|
		@@ -118,7 +119,7 @@
118	119	\| --- \| --- \| --- \|
119	120	\| `name` \| string \| Token name \|
120	121	\| `scopes` \| array of strings \| One or more of `read`, `write`, `admin`. Omit it (or send `null`) for the default `["write"]`. An empty list, a value that isn't a list, or an unknown name returns `422 scopes must be a non-empty list of: read, write, admin`. Repeated names are stored once. \|
121		-\| `repositories` \| array of strings \| `owner/name` of each repository to restrict to. Omit for every repository. An unknown repository returns `422 unknown repository <name>`. \|
	122	+\| `repositories` \| array of strings \| `owner/name` of each repository to restrict to. Omit for every repository. You can only list repositories your account can see: a repository that doesn't exist, or a private one you have no access to, returns `422 unknown repository <name>` (the same message for both, so the answer doesn't reveal private repositories). \|
122	123	\| `expires_in_days` \| number \| 1 to 366 (values outside are clamped). Default 90. \|
123	124
124	125	Response (`201 Created`):
		@@ -131,7 +132,7 @@
131	132
132	133	## Restrict a token to repositories
133	134
134		-A restricted token only works on the repositories you picked. Any other repository answers `404 repository not found`, as if it didn't exist, even if you could normally read it. Inside the listed repositories the usual role and scope cap apply. Account-level reads (such as `GET /api/v3/user`, listing your tokens or reading your notifications) still work, but account-level changes don't: creating repositories or organizations, inviting people, managing agents, organization secrets, notification settings and profile pictures, and revoking tokens all answer `403 this token is limited to repositories and can't change account settings` (profile pictures have their own message). See [Account-level actions](#account-level-actions).
	135	+A restricted token only works on the repositories you picked. Any other repository answers `404 repository not found`, as if it didn't exist, even if you could normally read it. Inside the listed repositories the usual role and scope cap apply. Account-level reads (such as `GET /api/v3/user`, listing your tokens or reading your notifications) still work, but account-level changes don't: creating repositories or organizations, inviting people, managing agents, organization secrets, notification settings and profile pictures, and creating or revoking tokens all answer `403 this token is limited to repositories and can't change account settings` (profile pictures have their own message). See [Account-level actions](#account-level-actions).
135	136
136	137	Restrict tokens you hand to CI systems, agents and third-party tools to the repositories they need.
137	138
		@@ -200,8 +201,10 @@
200	201	\| Token (GitHub style) \| `Authorization: token dfy_...` \|
201	202	\| Basic \| `Authorization: Basic base64(username:dfy_...)`. The password is used; the username can be anything. If the password is empty, the username is used as the token. \|
202	203
203		-Git uses Basic authentication; the CLI, MCP clients and most scripts use Bearer. They are equivalent.
	204	+Git uses Basic authentication; the CLI, MCP clients and most scripts use Bearer. They are equivalent. A `Basic` value that isn't valid base64 is refused with `401 malformed basic credentials`.
204	205
	206	+If a request carries the `Authorization` header twice (Git LFS does this when you set `http.extraHeader` and it also sends its own header), Diffinery uses the first one.
	207	+
205	208	### The CLI
206	209
207	210	`diffinery login` saves the server URL and token in `~/.config/diffinery/config.json` (or under `$XDG_CONFIG_HOME`). The environment variables `DIFFINERY_TOKEN` and `DIFFINERY_URL` override the saved values, which is handy in CI:
		@@ -231,8 +234,8 @@
231	234
232	235	Two other kinds of token exist. You don't create them yourself:
233	236
234		-- Job tokens (`djt_`) are given to each workflow job as `GITHUB_TOKEN` and `DIFFINERY_TOKEN`. They act as `diffinery-actions[bot]` with read access to the repository the job runs in, plus container registry access according to the job's `permissions: packages` (it pulls its owner's packages and pushes only to packages linked to its own repository), and stop working when the job finishes. See [Secrets and variables](/docs/actions/secrets-and-variables).
235		-- Sandbox tokens (`dst_`) are given to each agent sandbox. They act as whoever started the sandbox, capped at write, on that repository only, and stop working when the sandbox closes. See [Sandboxes](/docs/agents/sandboxes).
	237	+- Job tokens (`djt_`) are given to each workflow job as `GITHUB_TOKEN` and `DIFFINERY_TOKEN`. They act as `diffinery-actions[bot]` on the repository the job runs in, with what the workflow's `permissions:` grant, as on GitHub: each API endpoint needs its permission (`contents`, `issues`, `pull-requests`, `statuses`, `checks` and so on), and a request without it gets `403 Resource not accessible by integration`. Without `permissions:` a job gets the repository's default, which is read-only (`contents` and `packages` read) for new repositories; an admin changes it with the repository's workflow permissions setting (`PUT /api/v3/repos/{owner}/{repo}/actions/permissions/workflow`). A job token's role never goes above write, so branch protection applies to it, and it never changes repository settings, secrets, variables, webhooks, runners or branch protection, or creates or changes workflow files. A run whose code came from an agent acts as an agent, so it can't push or merge to the default or protected branches. The token also reads other public repositories (not other private ones), uses the container registry according to `permissions: packages`, and stops working when the job finishes. See [Workflow permissions](/docs/actions/workflow-permissions) and [Secrets and variables](/docs/actions/secrets-and-variables).
	238	+- Sandbox tokens (`dst_`) are given to each agent sandbox. They act as whoever started the sandbox, capped at write, on that repository, can also read other public repositories, and stop working when the sandbox closes. See [Sandboxes](/docs/agents/sandboxes).
236	239
237	240	## Security emails about tokens
238	241
		@@ -248,7 +251,7 @@
248	251
249	252	- Diffinery has one kind of personal token with three scopes, plus an optional repository list. GitHub has classic tokens with many scopes and fine-grained tokens with per-permission settings.
250	253	- Every token expires, after at most 366 days.
251		-- Tokens can only be created with the API or CLI when you already hold an `admin`-scoped token; the first one comes from the web UI.
	254	+- Tokens can only be created with the API or CLI when you already hold an `admin`-scoped token that isn't restricted to repositories; the first one comes from the web UI.
252	255	- Git accepts a token as the password with any username, as on GitHub.
253	256
254	257	## Troubleshooting
		@@ -258,11 +261,13 @@
258	261	\| `401 invalid, expired or revoked token` \| The token is unknown, expired or revoked, or your account is disabled or not yet active. Create a new token. \|
259	262	\| `401 unrecognised token; create one under Settings → Access tokens` \| The credential doesn't start with `dfy_` (or `djt_`, `dst_`), for example a GitHub token or a password. Use a Diffinery token from Settings → Access tokens. \|
260	263	\| `401 authentication required` \| No token was sent to a private repository. Configure Git credentials or add the `Authorization` header. \|
261		-\| `404 repository not found` \| You have no access, or the token is restricted to other repositories. \|
	264	+\| `404 repository not found` \| You have no access, or the token is restricted to other repositories. A `read` token that tries to change a private repository it can't see also gets this. \|
	265	+\| `401 malformed basic credentials` \| The `Authorization: Basic` value isn't valid base64. Encode `username:token` with base64, or send `Authorization: Bearer dfy_...` instead. \|
	266	+\| `422 unknown repository <name>` when creating a token \| The repository doesn't exist, or it is private and your account can't see it. Check the `owner/name` spelling and your access. \|
262	267	\| `401 authentication required` on a public repository \| You sent no token for a change (opening an issue, commenting, reacting, watching). Anonymous callers can only read. Send a `write` token. \|
263	268	\| `403 write access required` (or another role) \| Your role, or the token's scope, is too low. For `admin` actions, use an `admin` token. \|
264	269	\| `403 this token needs the write scope` \| A `read` token tried to change something. Use a `write` or `admin` token. \|
265		-\| `403 this token needs the admin scope` \| Account-level actions such as inviting, creating organizations or agents, organization secrets and revoking tokens need an `admin` token. \|
	270	+\| `403 this token needs the admin scope` \| Account-level actions such as inviting, creating organizations or agents, organization secrets, and creating or revoking tokens need an `admin` token. \|
266	271	\| `403 this token is limited to repositories and can't change account settings` \| The token has a repository list. Use a token without one, or the web UI. \|
267	272	\| `422 scopes must be a non-empty list of: read, write, admin` \| The `scopes` field was empty, not a list, or had an unknown name. \|
268	273	\| `403 creating tokens needs a browser session: sign in at https://diffinery.com/settings/tokens` \| Tokens can't create tokens. Create it in the web UI. \|

		@@ -57,7 +57,7 @@
57	57	3. The runner's work directory is mounted into the container at the same path, so `GITHUB_WORKSPACE`, `$GITHUB_OUTPUT`, `$GITHUB_ENV` and the other file commands work unchanged. `HOME` is `/github/home` inside the container.
58	58	4. Each `run:` step is executed with `docker exec` in the container, with the step's environment. The default shell is `bash` if the image has it, otherwise `sh`. `PATH` comes from the image unless the workflow sets `PATH`.
59	59	5. JavaScript actions run inside the container with the runner's own Node.js binary, mounted at `/__e/node`. That binary needs glibc, so JavaScript actions don't work in musl-based images such as Alpine (the same limitation GitHub has).
60		-6. The built-in actions (`actions/checkout`, `actions/cache`, `actions/upload-artifact`, `actions/download-artifact`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go`) run on the runner itself and work on the shared workspace.
	60	+6. The built-in actions (`actions/checkout`, `actions/cache`, `actions/upload-artifact`, `actions/download-artifact`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go`) run on the runner itself and work on the shared workspace. When the runner uses the real action instead (for a version or input the built-in doesn't cover, see [Compatibility with GitHub Actions](/docs/actions/compatibility#built-in-actions)), it runs like any other JavaScript action, inside the container.
61	61	7. The Docker socket is mounted into the job container when the runner has one at `/var/run/docker.sock`, so a step in the container can use Docker if the image includes the `docker` CLI.
62	62	8. When the job ends, every container the job started and its network are removed.
63	63
		@@ -178,19 +178,33 @@
178	178
179	179	`docker/setup-buildx-action`, `docker/login-action`, `docker/metadata-action` and `docker/build-push-action` also work. On hosted runners, `docker buildx create` with the `docker-container` driver (what `docker/setup-buildx-action` runs) starts BuildKit on the host network and registers it as a remote builder, because the regular driver can't run inside a Cloudflare Container. You don't need to change your workflow for this.
180	180
181		-> Note: BuildKit's `type=gha` cache (`cache-from: type=gha`, `cache-to: type=gha`) needs GitHub's cache service, which Diffinery doesn't provide. Remove those lines when you port a workflow.
	181	+BuildKit's `type=gha` cache works with `docker/build-push-action`. The action runs with the job's cache service credentials and hands them to BuildKit, and the layers are stored in the repository's Actions cache, with the same scope, size limit and eviction as `actions/cache`. See [Caching and artifacts](/docs/actions/caching-and-artifacts).
182	182
	183	+```yaml
	184	+- uses: docker/setup-buildx-action@v3
	185	+- uses: docker/build-push-action@v6
	186	+ with:
	187	+ context: .
	188	+ push: false
	189	+ cache-from: type=gha
	190	+ cache-to: type=gha,mode=max
	191	+```
	192	+
	193	+> Note: The cache service credentials (`ACTIONS_RUNTIME_TOKEN` and `ACTIONS_RESULTS_URL`) are given only to JavaScript actions, Docker container actions and the built-in actions, never to `run:` steps. `docker buildx build --cache-to type=gha` in a `run:` step has no credentials, so use `docker/build-push-action` for the gha cache.
	194	+
183	195	## Push images to the Diffinery registry
184	196
185	197	Diffinery hosts a container registry at `diffinery.com`, in place of ghcr.io. A workflow signs in with its own `GITHUB_TOKEN`; the job's `packages` permission decides what the token can do:
186	198
187	199	\| `permissions` in the workflow or job \| `GITHUB_TOKEN` can \|
188	200	\|---\|---\|
189		-\| No `permissions` block, or `write-all` \| Push and pull \|
190		-\| `packages: write` \| Push and pull \|
	201	+\| No `permissions` block \| What the repository default allows: pull for repositories with the `read` default (the default for new repositories), push and pull for those with `write` \|
	202	+\| `write-all`, or `packages: write` \| Push and pull \|
191	203	\| `packages: read`, or `read-all` \| Pull \|
192	204	\| A mapping without `packages` \| Nothing \|
193	205
	206	+A job's own `permissions:` replaces the workflow's. To push from a repository with the `read` default, add `packages: write` to the job or the workflow. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions).
	207	+
194	208	With write, the token pushes only to packages linked to the workflow's own repository, and creates new packages under the repository's owner (linked to the repository). Other packages of the same owner, including ones that aren't linked to any repository, are pull-only for it.
195	209
196	210	Image names are `diffinery.com/<owner>/<name>` and must be lowercase. `github.repository` keeps the owner's and repository's capitals, so lowercase it in a shell step with `${GITHUB_REPOSITORY,,}`.
		@@ -375,3 +389,4 @@
375	389	\| `the --network option is not supported` \| Remove `--network` from `options`. Services are already on the job's network. \|
376	390	\| A JavaScript action fails inside an Alpine job container \| The runner's Node.js needs glibc. Use a Debian or Ubuntu based image, or run the action outside the container. \|
377	391	\| A registry error ending in `the workflow's GITHUB_TOKEN has no packages permission; add permissions: packages: write` \| The job's `permissions` mapping leaves out `packages`. Add `packages: write` to push, or `packages: read` to pull. \|
	392	+\| A push fails with a registry error ending in `the workflow's GITHUB_TOKEN has packages: read; add permissions: packages: write to push` \| The job has only read access to packages, often because it has no `permissions:` and the repository default is `read`. Add `packages: write`. \|

		@@ -131,8 +131,8 @@
131	131	\| `created`, `deleted`, `forced` \| Whether the push created the ref, deleted it (always `false` for runs) or was a force push \|
132	132	\| `head_commit` \| `id`, `message`, `timestamp` (committer time) and `author` (`name`, `email`) of the pushed commit \|
133	133	\| `commits` \| A list with the pushed commit only (`id`, `message`). GitHub lists up to 20 commits. \|
134		-\| `pusher` \| `name`: the login of the account that pushed \|
135		-\| `sender` \| `login`, and `type`: `Bot` for agents, `User` otherwise \|
	134	+\| `pusher` \| `name`: the login of the account that pushed, and `email`: `null` \|
	135	+\| `sender` \| See [The sender object](#the-sender-object) \|
136	136	\| `repository` \| See [The repository object](#the-repository-object) \|
137	137
138	138	## pull_request
		@@ -199,21 +199,28 @@
199	199	\| `action` \| The activity type \|
200	200	\| `number` \| The pull request number \|
201	201	\| `pull_request.number`, `pull_request.id` \| The pull request number (both) \|
	202	+\| `pull_request.node_id` \| An opaque ID \|
202	203	\| `pull_request.state` \| `open` or `closed` \|
	204	+\| `pull_request.locked` \| `false` \|
203	205	\| `pull_request.title`, `pull_request.body` \| Title and description \|
204	206	\| `pull_request.draft`, `pull_request.merged` \| Booleans \|
205	207	\| `pull_request.merged_at` \| When it merged, or `null` \|
206	208	\| `pull_request.merged_by` \| `{ "login": ... }` or `null` \|
207	209	\| `pull_request.merge_commit_sha` \| The merge commit once merged, otherwise the test merge commit (or `null` while it conflicts) \|
208		-\| `pull_request.user` \| `{ "login": ... }` of the author \|
	210	+\| `pull_request.user` \| The author, as a user object (see [The sender object](#the-sender-object)) \|
209	211	\| `pull_request.labels` \| `[{ "name": ... }]` \|
210	212	\| `pull_request.assignees` \| `[{ "login": ... }]` \|
211		-\| `pull_request.head` \| `ref` (branch), `sha` (head commit) and `repo` \|
212		-\| `pull_request.base` \| `ref` (branch), `sha` (base commit) and `repo` \|
	213	+\| `pull_request.requested_reviewers` \| `[]` \|
	214	+\| `pull_request.author_association` \| `MEMBER` \|
	215	+\| `pull_request.head` \| `label` (`<owner>:<branch>`), `ref` (branch), `sha` (head commit), `user` (the repository owner) and `repo` (a repository object) \|
	216	+\| `pull_request.base` \| The same fields for the base branch \|
213	217	\| `pull_request.html_url` \| `https://diffinery.com/acme/website/pull/<n>` \|
214	218	\| `pull_request.url` \| `https://diffinery.com/api/v3/repos/acme/website/pulls/<n>` \|
	219	+\| `pull_request.diff_url`, `pull_request.patch_url` \| `https://diffinery.com/acme/website/pull/<n>.diff` and `.patch` \|
	220	+\| `pull_request.issue_url`, `pull_request.commits_url`, `pull_request.review_comments_url`, `pull_request.comments_url` \| API URLs, as on GitHub \|
215	221	\| `repository` \| See [The repository object](#the-repository-object) \|
216		-\| `sender` \| `{ "login": ... }` of whoever caused the event \|
	222	+\| `organization` \| For repositories owned by an organization; see [The repository object](#the-repository-object) \|
	223	+\| `sender` \| Whoever caused the event; see [The sender object](#the-sender-object) \|
217	224
218	225	## pull_request_target
219	226
		@@ -391,6 +398,7 @@
391	398	- `branches` and `branches-ignore` filter on the other run's head branch: the pushed branch, or the pull request's head branch for pull request runs.
392	399	- Like on GitHub, the triggered workflow is read from the default branch and runs there, whatever branch the other run was on.
393	400	- Chains stop after three levels: if A triggers B, B triggers C and C triggers D, D's runs don't trigger anything.
	401	+- If the run it follows came from an agent (for example CI on a branch an agent pushed), the `workflow_run` run counts as agent code too, although it runs on the default branch: its `GITHUB_TOKEN` acts as an agent and environment secrets follow the agent rules. A follower acts on what the other run produced (artifacts, outputs), so it can't be used to carry agent-written results past the agent guardrails. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions#runs-whose-code-came-from-an-agent).
394	402
395	403	\| Variable \| Value \|
396	404	\| --- \| --- \|
		@@ -402,7 +410,7 @@
402	410	\| Field \| Value \|
403	411	\| --- \| --- \|
404	412	\| `action` \| `requested` or `completed` \|
405		-\| `workflow_run.id` \| The other run's ID \|
	413	+\| `workflow_run.id` \| The other run's number, which is also its `github.run_id` and what `download-artifact`'s `run-id` takes \|
406	414	\| `workflow_run.name`, `workflow_run.path` \| The other workflow's name and file path \|
407	415	\| `workflow_run.display_title` \| The other run's title \|
408	416	\| `workflow_run.run_number`, `workflow_run.run_attempt` \| Its number and attempt \|
		@@ -479,10 +487,10 @@
479	487	\| `release.url`, `release.assets_url`, `release.upload_url` \| API URLs. Upload assets to `upload_url` (with the `{?name,label}` template removed). \|
480	488	\| `release.tarball_url`, `release.zipball_url` \| Source archives of the tag \|
481	489	\| `release.node_id`, `release.reactions` \| As on GitHub \|
482		-\| `repository` \| `id` (a number), `node_id`, `name`, `full_name`, `owner.login`, `default_branch`, `html_url` and `clone_url` \|
483		-\| `sender` \| `login`, and `type`: `User` for people, `Bot` otherwise \|
	490	+\| `repository` \| See [The repository object](#the-repository-object) \|
	491	+\| `sender` \| See [The sender object](#the-sender-object) \|
484	492
485		-Uploading an asset needs a token with write access. The job's `GITHUB_TOKEN` is read-only, so store a personal or agent token as a secret for that:
	493	+Uploading an asset needs `contents: write`. Give the job that permission and use its `GITHUB_TOKEN`, or use a personal or agent token stored as a secret (see [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions)):
486	494
487	495	```yaml
488	496	on:
		@@ -566,9 +574,9 @@
566	574	\| `action` \| The `event_type` \|
567	575	\| `branch` \| The default branch \|
568	576	\| `client_payload` \| The `client_payload` you sent \|
	577	+\| `repository` \| See [The repository object](#the-repository-object) \|
	578	+\| `sender` \| The account whose token sent the event; see [The sender object](#the-sender-object) \|
569	579
570		-Unlike GitHub, and unlike the other events on this page, the `repository_dispatch` payload has no `repository` or `sender` field. Use `github.repository` and `github.actor` instead.
571		-
572	580	## workflow_call
573	581
574	582	Makes the workflow reusable: other workflows call it from a job with `uses:`. It never starts a run on its own.
		@@ -608,28 +616,47 @@
608	616
609	617	## The repository object
610	618
611		-Every payload except `repository_dispatch` has a `repository` field. For `push`, `pull_request`, `pull_request_target`, `merge_group`, `workflow_dispatch`, `schedule` and `workflow_run` it has:
	619	+Every payload has a `repository` field with GitHub's full repository object, the same one the REST API returns for `GET /repos/{owner}/{repo}`. The fields workflows read most:
612	620
613	621	\| Field \| Value \|
614	622	\| --- \| --- \|
615		-\| `id` \| The repository's ID \|
	623	+\| `id` \| The repository's ID, a number \|
	624	+\| `node_id` \| An opaque ID \|
616	625	\| `name` \| `website` \|
617	626	\| `full_name` \| `acme/website` \|
618		-\| `owner.login` \| `acme` \|
	627	+\| `private` \| `true` for a private repository, `false` for a public one \|
	628	+\| `visibility` \| `public` or `private` \|
	629	+\| `owner` \| A user object for the owner (`login`, a numeric `id`, `type`: `User` or `Organization`, and URLs) \|
619	630	\| `default_branch` \| `main` \|
	631	+\| `archived` \| Whether the repository is archived \|
	632	+\| `topics` \| The repository's topics \|
620	633	\| `html_url` \| `https://diffinery.com/acme/website` \|
621	634	\| `clone_url` \| `https://diffinery.com/acme/website.git` \|
622		-\| `private` \| Always `true`, whatever the repository's visibility \|
	635	+\| `url` and the `*_url` templates \| API URLs under `https://diffinery.com/api/v3/repos/acme/website` \|
	636	+\| `created_at`, `updated_at`, `pushed_at` \| Timestamps \|
623	637
624		-For `release`, `repository.id` is a number (as in the REST API), there is also a `node_id`, and there is no `private` field.
	638	+For a repository owned by an organization, payloads also have an `organization` field with `login`, `id` (a number), `node_id`, `url`, `repos_url`, `avatar_url` and `description`.
625	639
626		-The payload is also written to the file at `GITHUB_EVENT_PATH` for tools that read it from disk.
	640	+The payload is also written to the file at `GITHUB_EVENT_PATH` for tools that read it from disk, such as `@actions/github`'s `context.payload` in `actions/github-script`.
627	641
	642	+## The sender object
	643	+
	644	+`sender` is the account that caused the event, as a GitHub user object:
	645	+
	646	+\| Field \| Value \|
	647	+\| --- \| --- \|
	648	+\| `login` \| The account's login \|
	649	+\| `id` \| A number derived from the account's ID, like GitHub's numeric user IDs \|
	650	+\| `node_id` \| An opaque ID \|
	651	+\| `type` \| `User` for people, `Bot` for agents and Diffinery itself (for example `diffinery-scheduler`) \|
	652	+\| `site_admin` \| `false` \|
	653	+\| `avatar_url`, `html_url`, `url` \| The avatar, the profile page and the API URL \|
	654	+
628	655	## Runs started from inside a workflow
629	656
630		-As on GitHub, an event caused by a job's own `GITHUB_TOKEN` doesn't start new workflow runs, so workflows can't trigger themselves in a loop. `repository_dispatch` is the exception, as on GitHub: it is meant for starting workflows on purpose.
	657	+As on GitHub, an event caused by a job's own `GITHUB_TOKEN` doesn't start new workflow runs, so workflows can't trigger themselves in a loop. A push, a pull request or a release made with a job token starts nothing. The two exceptions, as on GitHub, are `workflow_dispatch` (a job with `permissions: actions: write` can start another workflow with `POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`) and `repository_dispatch` (a job with `contents: write` can send `POST /repos/{owner}/{repo}/dispatches`).
631	658
632		-On Diffinery the job's `GITHUB_TOKEN` has read access only, so in practice it can't push, open pull requests, publish releases or send `repository_dispatch` events in the first place (the API answers `403 write access required`). To do any of that from a job, use a personal or agent token stored as a secret. Events caused by such a token are treated like any other event from that account and do start workflows: a push starts `push` workflows, a published release starts `release` workflows, and a dispatch starts `repository_dispatch` workflows.
	659	+Events caused by a personal or agent token stored as a secret are treated like any other event from that account and do start workflows: a push starts `push` workflows, a published release starts `release` workflows, and a dispatch starts `repository_dispatch` workflows.
633	660
634	661	```yaml
635	662	- name: Ask the deploy workflow to run
		@@ -650,8 +677,7 @@
650	677	- `pull_request` and `pull_request_target` fire for `opened`, `synchronize`, `reopened`, `closed`, `edited`, `ready_for_review` and `converted_to_draft` only, and the `edited` payload has no `changes` object.
651	678	- `workflow_run` fires for `requested` and `completed`, not `in_progress`, and requires `workflows`.
652	679	- `release` workflows get no `branches`, `tags` or `paths` filtering, and a published release whose tag doesn't exist any more starts no runs.
653		-- `repository_dispatch` payloads have no `repository` or `sender` field.
654		-- `repository.private` is always `true` in payloads (except `release`, which has no `private` field).
	680	+- `deployment` and `deployment_status` events go to webhooks (a job with `environment:` sends both), but don't start workflow runs.
655	681	- `push` payloads list only the pushed commit in `commits`.
656	682	- Path filters pass when a push creates a branch.
657	683	- `github.event.inputs` keeps input types.

		@@ -129,15 +129,17 @@
129	129
130	130	### Status check functions
131	131
132		-In a job's `if:`:
	132	+In a job's `if:`, the functions look at all of the job's ancestors: the jobs in its `needs`, the jobs those need, and so on up the chain, as on GitHub.
133	133
134	134	\| Function \| True when \|
135	135	\| --- \| --- \|
136		-\| `success()` \| The run hasn't been cancelled and every job in `needs` succeeded or was skipped. \|
137		-\| `failure()` \| A job in `needs` failed or timed out. \|
	136	+\| `success()` \| The run hasn't been cancelled and every ancestor succeeded. A skipped or cancelled ancestor makes it false. \|
	137	+\| `failure()` \| An ancestor failed or timed out. \|
138	138	\| `cancelled()` \| The run has been cancelled. \|
139	139	\| `always()` \| Always. \|
140	140
	141	+A matrix job's result combines its legs: any failed leg fails it, otherwise any cancelled leg cancels it, and it's skipped when every leg was skipped. A leg that failed with `continue-on-error: true` counts as a success. A reusable workflow call's result combines the jobs inside it the same way.
	142	+
141	143	In a step's `if:`:
142	144
143	145	\| Function \| True when \|
		@@ -165,8 +167,28 @@
165	167	- run: echo "test finished with ${{ needs.test.result }}"
166	168	```
167	169
168		-> Important: Two differences from GitHub at the job level. On GitHub, when a job is skipped, every job that needs it is skipped too; on Diffinery a skipped job counts as a success, so the jobs that need it run. And `failure()` only looks at the jobs listed in the job's own `needs`, not at the jobs those depend on. If a job must not run after an earlier failure further up the chain, list that job in `needs` or check its result, for example `if: needs.build.result == 'success'`.
	170	+Because a job's default `if:` is `success()`, a skipped job skips every job that depends on it, directly or further down the chain. To run a job anyway, give it a status function, for example `if: always()` or `if: ${{ !cancelled() && needs.build.result != 'failure' }}`:
169	171
	172	+```yaml
	173	+jobs:
	174	+ build:
	175	+ if: github.event_name == 'push'
	176	+ runs-on: ubuntu-latest
	177	+ steps:
	178	+ - run: make
	179	+ test:
	180	+ needs: build # skipped when build is skipped
	181	+ runs-on: ubuntu-latest
	182	+ steps:
	183	+ - run: make test
	184	+ report:
	185	+ needs: test
	186	+ if: ${{ !cancelled() }} # runs even when build and test were skipped
	187	+ runs-on: ubuntu-latest
	188	+ steps:
	189	+ - run: echo "test result was ${{ needs.test.result }}"
	190	+```
	191	+
170	192	## Contexts
171	193
172	194	### Where each context is available
		@@ -177,9 +199,9 @@
177	199	\| --- \| --- \|
178	200	\| `run-name`, top-level `concurrency` \| `github`, `inputs`, `vars` \|
179	201	\| `jobs.<id>.if` \| `github`, `needs`, `inputs`, `vars`, `env` (workflow-level values, unevaluated), status functions \|
180		-\| `jobs.<id>.runs-on`, `jobs.<id>.strategy` \| `github`, `needs`, `inputs`, `vars`, `env` \|
181		-\| `jobs.<id>.name`, `jobs.<id>.timeout-minutes` \| `github`, `needs`, `inputs`, `vars`, `env`, `matrix`, `strategy` \|
182		-\| `jobs.<id>.environment` (`name` and `url`) \| `github`, `inputs`, `vars`, `matrix`. A `url` that refers to `steps.` is ignored. \|
	202	+\| `jobs.<id>.strategy` \| `github`, `needs`, `inputs`, `vars`, `env` \|
	203	+\| `jobs.<id>.name`, `jobs.<id>.runs-on`, `jobs.<id>.timeout-minutes`, `jobs.<id>.continue-on-error`, `jobs.<id>.concurrency` \| `github`, `needs`, `inputs`, `vars`, `env`, `matrix`, `strategy`. These are evaluated for each matrix combination. \|
	204	+\| `jobs.<id>.environment` (`name` and `url`) \| `github`, `needs`, `inputs`, `vars`, `matrix`, `strategy`. A `url` that refers to `steps.` is ignored. \|
183	205	\| `jobs.<id>.with` (reusable workflow call) \| `github`, `needs`, `inputs`, `vars` \|
184	206	\| `jobs.<id>.secrets` (reusable workflow call) \| `github`, `needs`, `inputs`, `vars`, `secrets` \|
185	207	\| `jobs.<id>.env`, `container`, `services` \| `github`, `needs`, `inputs`, `vars`, `secrets`, `matrix`, `strategy`, `runner`, `job` \|
		@@ -210,7 +232,7 @@
210	232	\| `github.repositoryUrl` \| `https://diffinery.com/acme/website.git` \|
211	233	\| `github.actor` \| The login of the account that triggered the run (for a re-run, who re-ran it): for `release`, whoever published, edited or deleted the release; for `repository_dispatch`, the account whose token sent the event. Scheduled runs use `diffinery-scheduler`; merge queue groups use the login of whoever queued the pull request. \|
212	234	\| `github.triggering_actor` \| Same as `github.actor` \|
213		-\| `github.run_id` \| The run's ID, a 32-character hexadecimal string \|
	235	+\| `github.run_id` \| The run number, as a string, for example `128`. It stays the same on a re-run, and the REST API accepts it wherever a run ID goes, so actions that parse it as a number work. \|
214	236	\| `github.run_number` \| The run's number, as a string \|
215	237	\| `github.run_attempt` \| `1`, or higher for re-runs, as a string \|
216	238	\| `github.workflow` \| The workflow's `name`, or its path when it has none \|
		@@ -229,7 +251,7 @@
229	251
230	252	GitHub properties Diffinery doesn't set include `github.actor_id`, `github.repository_owner_id`, `github.workflow_sha`, `github.event_path` (use the `GITHUB_EVENT_PATH` variable), `github.env`, `github.path`, `github.output`, `github.state` and `github.step_summary` (use the environment variables of the same names).
231	253
232		-> Note: `github.run_number` counts runs of all workflows in the repository, not each workflow separately as on GitHub, and `github.run_id` is a hexadecimal string, not a number.
	254	+> Note: `github.run_number` counts runs of all workflows in the repository, not each workflow separately as on GitHub. Because `github.run_id` is the run number, the two are always equal.
233	255
234	256	### env
235	257
		@@ -254,8 +276,8 @@
254	276
255	277	\| Property \| Value \|
256	278	\| --- \| --- \|
257		-\| `secrets.<NAME>` \| A repository secret, or an organization secret of the repository's owner. A repository secret wins over an organization secret with the same name. In a job with `environment:`, the environment's secrets win over both (pull request runs, and some runs started by agents, don't get environment secrets; see [environment](/docs/actions/workflow-syntax#environment)). \|
258		-\| `secrets.GITHUB_TOKEN` \| The job's token. It has read access to the repository; see [Workflow syntax](/docs/actions/workflow-syntax#permissions). \|
	279	+\| `secrets.<NAME>` \| A repository secret, or an organization secret of the repository's owner. A repository secret wins over an organization secret with the same name. In a job with `environment:`, the environment's secrets win over both (pull request runs, and some runs whose code came from an agent, don't get environment secrets; see [environment](/docs/actions/workflow-syntax#environment)). \|
	280	+\| `secrets.GITHUB_TOKEN` \| The job's token. What it may do follows the job's `permissions:`; see [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions). \|
259	281	\| `secrets.DIFFINERY_TOKEN` \| The same job token, under a Diffinery name. \|
260	282
261	283	Secret names are stored in upper case and lookups ignore case; an unset secret is `''`. Inside a reusable workflow, `secrets` holds only what the caller passed (or everything with `secrets: inherit`), plus the two tokens. Secret values are masked in logs.
		@@ -303,7 +325,7 @@
303	325	\| `runner.temp` \| A temporary directory for the job; `/workspace/_temp` on hosted runners, where every job starts in a fresh container \|
304	326	\| `runner.tool_cache` \| Where setup actions install tools; `/opt/hostedtoolcache` on hosted runners \|
305	327	\| `runner.workspace` \| The parent of `GITHUB_WORKSPACE`; `/workspace` on hosted runners \|
306		-\| `runner.debug` \| `1` when debug logging is on (secret or variable `ACTIONS_STEP_DEBUG` set to `true`), otherwise `''` \|
	328	+\| `runner.debug` \| `1` when debug logging is on (secret or variable `ACTIONS_STEP_DEBUG` set to `true`), otherwise `''`. `ACTIONS_RUNNER_DEBUG` doesn't change it. \|
307	329
308	330	### job
309	331
		@@ -338,7 +360,7 @@
338	360	\| `GITHUB_REF_TYPE` \| `branch` or `tag` \|
339	361	\| `GITHUB_HEAD_REF` \| The head branch for pull request events, otherwise empty \|
340	362	\| `GITHUB_BASE_REF` \| The base branch for pull request events, otherwise empty \|
341		-\| `GITHUB_RUN_ID` \| The run's ID \|
	363	+\| `GITHUB_RUN_ID` \| The run number, as in `github.run_id` \|
342	364	\| `GITHUB_RUN_NUMBER` \| The run's number \|
343	365	\| `GITHUB_RUN_ATTEMPT` \| The attempt number \|
344	366	\| `GITHUB_JOB` \| The job's ID \|
		@@ -363,12 +385,15 @@
363	385	\| `RUNNER_TOOL_CACHE` \| `/opt/hostedtoolcache` \|
364	386	\| `RUNNER_WORKSPACE` \| `/workspace` \|
365	387	\| `AGENT_TOOLSDIRECTORY` \| Same as `RUNNER_TOOL_CACHE` \|
	388	+\| `ImageOS` \| `ubuntu24`, as on GitHub's `ubuntu-24.04` image \|
	389	+\| `ImageVersion` \| `20250101.1` \|
366	390
367	391	Set only in some cases:
368	392
369	393	\| Variable \| When \|
370	394	\| --- \| --- \|
371		-\| `RUNNER_DEBUG` \| `1` when the secret or variable `ACTIONS_STEP_DEBUG` is `true` \|
	395	+\| `RUNNER_DEBUG` \| `1` when the secret or variable `ACTIONS_STEP_DEBUG` or `ACTIONS_RUNNER_DEBUG` is `true` \|
	396	+\| `ACTIONS_RUNTIME_TOKEN`, `ACTIONS_RUNTIME_URL`, `ACTIONS_RESULTS_URL`, `ACTIONS_CACHE_URL`, `ACTIONS_CACHE_SERVICE_V2` \| In JavaScript actions, Docker container actions and the built-in actions only, never in `run:` steps. They give access to the job's cache and artifact services and stop working when the job ends. See [Caching and artifacts](/docs/actions/caching-and-artifacts#the-runtime-services). \|
372	397	\| `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` \| When the job has `permissions: id-token: write`. Used by OIDC clients; see [OIDC](/docs/actions/oidc). \|
373	398	\| `GITHUB_ACTION_PATH`, `GITHUB_ACTION_REPOSITORY`, `GITHUB_ACTION_REF` \| In JavaScript and Docker actions, and in the steps of composite actions \|
374	399	\| `INPUT_<NAME>` \| In JavaScript and Docker actions: each input, with the name upper-cased and spaces replaced by `_` \|
		@@ -376,7 +401,7 @@
376	401
377	402	Hosted runners also set `LANG=C.UTF-8`, `LC_ALL=C.UTF-8`, `PIP_BREAK_SYSTEM_PACKAGES=1` (so `pip install` works with Ubuntu's Python) and `COREPACK_ENABLE_DOWNLOAD_PROMPT=0`.
378	403
379		-GitHub variables that Diffinery doesn't set include `GITHUB_ACTOR_ID`, `GITHUB_REPOSITORY_ID`, `GITHUB_REPOSITORY_OWNER_ID`, `GITHUB_WORKFLOW_SHA`, `GITHUB_REF_PROTECTED`, `ImageOS` and `ImageVersion`. `GITHUB_TOKEN` isn't an environment variable unless you set it, as on GitHub:
	404	+GitHub variables that Diffinery doesn't set include `GITHUB_ACTOR_ID`, `GITHUB_REPOSITORY_ID`, `GITHUB_REPOSITORY_OWNER_ID`, `GITHUB_WORKFLOW_SHA` and `GITHUB_REF_PROTECTED`. `GITHUB_TOKEN` isn't an environment variable unless you set it, as on GitHub:
380	405
381	406	```yaml
382	407	- run: gh api repos/${{ github.repository }}
		@@ -386,13 +411,11 @@
386	411
387	412	## Differences from GitHub
388	413
389		-- A skipped job counts as a success for the jobs that need it, so they run; on GitHub they're skipped. `failure()` in a job's `if:` only looks at its direct `needs`.
390		-- `runs-on` can't use the `matrix` context.
391		-- `jobs.<id>.environment` can't use the `needs` or `strategy` contexts, and its `url` can't use step outputs.
	414	+- `jobs.<id>.environment.url` can't use step outputs.
392	415	- Job-level `if:` can also read the workflow-level `env`.
393	416	- `hashFiles()` returns `''` outside steps and other runner-evaluated values.
394	417	- `github.event.inputs` keeps the types of dispatch inputs; on GitHub its values are strings.
395		-- `github.run_id` is a hexadecimal string, and `github.run_number` counts runs across all workflows of the repository.
	418	+- `github.run_number` counts runs across all workflows of the repository, and `github.run_id` is the same number.
396	419	- On a re-run, `github.actor` is whoever started the re-run (and `github.triggering_actor` matches it).
397	420	- `github.ref_protected` is always `false`, and `secrets.DIFFINERY_TOKEN` is an extra name for the job token.
398	421	- `GITHUB_` and `RUNNER_` defaults can't be overridden, but `CI` and `DIFFINERY` can.

		@@ -7,9 +7,10 @@
7	7
8	8	## Requirements
9	9
10		-- The job needs `permissions: id-token: write`, in the workflow's top-level `permissions`, in the job's `permissions`, or through `permissions: write-all`.
	10	+- The job's effective permissions must include `id-token: write`. A job's own `permissions:` replaces the workflow's top-level `permissions:` entirely, as on GitHub, so a job that sets `permissions:` must list `id-token: write` itself. `permissions: write-all` includes it.
	11	+- The repository's default permissions never include `id-token`, and neither does `read-all`. `id-token: read` grants nothing.
11	12	- It works on hosted and self-hosted runners.
12		-- In a reusable workflow, the called workflow (or its job) must grant `id-token: write`; the calling job's `permissions` isn't used.
	13	+- In a reusable workflow, the called jobs get the calling job's permissions, and anything the called workflow or its jobs declare is lowered to the calling job's permissions. So the calling job's effective permissions must include `id-token: write`, and so must the called workflow's or job's `permissions:` when it sets one. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions#reusable-workflows).
13	14
14	15	```yaml
15	16	permissions:
		@@ -17,6 +18,22 @@
17	18	contents: read
18	19	```
19	20
	21	+This job gets no OIDC token, because its own `permissions:` replaces the workflow's:
	22	+
	23	+```yaml
	24	+permissions:
	25	+ id-token: write
	26	+ contents: read
	27	+
	28	+jobs:
	29	+ deploy:
	30	+ runs-on: ubuntu-latest
	31	+ permissions:
	32	+ contents: read # id-token is now none for this job
	33	+ steps:
	34	+ - run: echo "no ACTIONS_ID_TOKEN_REQUEST_URL here"
	35	+```
	36	+
20	37	Without the permission, the variables below aren't set, and `core.getIDToken()` in an action fails because `ACTIONS_ID_TOKEN_REQUEST_URL` is missing.
21	38
22	39	## The issuer
		@@ -92,7 +109,7 @@
92	109	\| `sha` \| `9fceb02d0ae598e95dc970b74767f19372d61af8` \| The commit the run checked out. \|
93	110	\| `workflow` \| `Deploy` \| The workflow's `name`, or its file path when it has none. \|
94	111	\| `event_name` \| `push` \| The event that started the run. \|
95		-\| `run_id` \| `01J9Z...` \| Diffinery's run id (an opaque string, not a number). \|
	112	+\| `run_id` \| `128` \| The run number, as a string. It's the same value as `github.run_id`, and stays the same when the run is re-run. \|
96	113	\| `actor` \| `diffy` \| Who started the run. \|
97	114	\| `job_workflow_ref` \| `acme/website/.github/workflows/deploy.yml@refs/heads/main` \| The run's top-level workflow file and ref. \|
98	115
		@@ -334,9 +351,7 @@
334	351	\| `sub` \| Varies by event (for example `repo:o/r:pull_request`, `repo:o/r:environment:prod`) \| Always `repo:<owner>/<repo>:ref:<ref>`; pull requests use `refs/pull/<n>/merge` \|
335	352	\| Claims \| Many, including `repository_id`, `workflow_ref`, `ref_type`, `environment`, `runner_environment` \| Only the claims listed in [Claims](#claims) \|
336	353	\| Jobs with `environment:` \| `environment` claim, and `sub` is `repo:o/r:environment:<name>` \| No `environment` claim; `sub` is unchanged (see [Jobs that use an environment](#jobs-that-use-an-environment)) \|
337		-\| `run_id` \| A number \| An opaque string \|
338	354	\| `job_workflow_ref` \| The reusable workflow's file when the job is in one \| Always the run's top-level workflow \|
339		-\| `permissions` \| A job's `permissions` replaces the workflow's \| `id-token: write` at either level (or `write-all`) grants it \|
340	355	\| Token lifetime \| About 5 to 10 minutes \| 10 minutes \|
341	356
342	357	When you port a trust policy from GitHub, change the issuer host (`token.actions.githubusercontent.com` to `diffinery.com`) in provider URLs and condition keys, and rewrite `sub` patterns to the `repo:<owner>/<repo>:ref:<ref>` form.
		@@ -345,7 +360,7 @@
345	360
346	361	\| Problem \| Fix \|
347	362	\|---\|---\|
348		-\| `Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable` from an action \| Add `permissions: id-token: write` to the workflow or the job (in a reusable workflow, to the called workflow). \|
	363	+\| `Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable` from an action \| The job's effective permissions lack `id-token: write`. Add it to the job's `permissions:` if the job has one, otherwise to the workflow's. In a reusable workflow, the calling job needs it too. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions). \|
349	364	\| AWS: `Not authorized to perform sts:AssumeRoleWithWebIdentity` \| The trust policy's `sub` or `aud` doesn't match. Decode the token (its middle part is base64url JSON) and compare `sub` and `aud` with the policy. \|
350	365	\| AWS: `No OpenIDConnect provider found in your account for https://diffinery.com` \| Create the identity provider with URL `https://diffinery.com`. \|
351	366	\| Google Cloud: `The given credential is rejected by the attribute condition` \| The `attribute-condition` on the provider doesn't match the token's claims. \|

		@@ -18,7 +18,7 @@
18	18	\| Check \| The result of one job, reported on the commit the run is about. Branch protection can require checks to pass before merging. \|
19	19	\| Environment \| A named deployment target, such as `production`, with its own secrets, variables and branch policy. A job that sets `environment:` gets them and records a deployment. See [Environments](/docs/actions/environments). \|
20	20
21		-Workflows are compatible with GitHub Actions: the same triggers, expressions, matrices, `needs`, outputs, caches, artifacts, secrets, environments, OIDC, `actions/checkout`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go`, and remote JavaScript, composite and Docker actions. Differences are called out on each page and collected in [GitHub Actions compatibility](/docs/actions/compatibility).
	21	+Workflows are compatible with GitHub Actions: the same triggers, expressions, matrices, `needs`, outputs, caches, artifacts, secrets, environments, OIDC, a `GITHUB_TOKEN` that follows `permissions:`, the official actions (`actions/checkout`, `actions/cache`, `actions/upload-artifact`, `actions/download-artifact`, `actions/github-script`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go` and the rest), and remote JavaScript, composite and Docker actions. Differences are called out on each page and collected in [GitHub Actions compatibility](/docs/actions/compatibility).
22	22
23	23	## Your first workflow
24	24
		@@ -108,10 +108,10 @@
108	108
109	109	1. An event happens. Diffinery loads the workflow files from the commit the event is about (see the table above) and checks each workflow's `on:` section, including branch, tag and path filters.
110	110	2. A run is created for each matching workflow, with status `queued`. It gets the next run number and a title: the `run-name` if the workflow sets one, otherwise the first line of the commit message (push), the pull request title (pull request events), `Merge group for #<n>: <title>` (merge groups), the release's name or tag (release), the `event_type` (repository_dispatch) or the workflow name (dispatch, schedule, workflow_run). If the workflow has a `concurrency` group, other runs in the group may be cancelled or this run may wait (see [Concurrency](#concurrency)).
111		-3. The run is orchestrated durably by a Cloudflare Workflow. It resolves the job graph from `needs` into levels, starts every job of a level, waits for all of them to finish, then moves on to the next level. The orchestration survives restarts of the platform, and each wait for a job lasts at most 6 hours.
112		-4. Each job is evaluated just before it starts: its `if:` condition, its `runs-on` labels and its matrix. A job whose condition is false is recorded as `skipped`. A matrix job becomes one job per combination (at most 256), started up to `max-parallel` at a time.
	111	+3. The run is orchestrated durably by a Cloudflare Workflow. It walks the job graph from `needs`: each job starts as soon as the jobs it needs have finished, without waiting for unrelated jobs. The orchestration survives restarts of the platform, and each wait for a job lasts at most 6 hours.
	112	+4. Each job is evaluated just before it starts: its `if:` condition and its matrix. A job whose condition is false is recorded as `skipped`; without a status function in its `if:`, a job is also skipped when any job above it in the `needs` chain failed, was cancelled or was skipped. A matrix job becomes one job per combination (at most 256), started up to `max-parallel` at a time, and each combination gets its own `name`, `runs-on`, `timeout-minutes`, `continue-on-error` and job `concurrency` group, evaluated with its `matrix` values. A job with a `concurrency` group waits as `pending` while another job of the group runs.
113	113	5. Each hosted job gets its own container. A fresh Cloudflare Container (Ubuntu 24.04, linux/amd64) starts with a job token that is valid only for that job. The runner agent inside fetches the job definition (for a job with `environment:`, this is when the environment's branch policy is checked and its secrets and variables are added), runs the steps in order, streams the log back as it goes, and reports each step's result and the job's conclusion. The container stops when the job ends. Jobs for self-hosted runners wait until a `diffinery runner` with matching labels claims them instead.
114		-6. The run finishes when every level is done. Its conclusion is `failure` if any job failed or timed out, otherwise `cancelled` if the run was cancelled or any job was cancelled, otherwise `success`. Skipped jobs don't make a run fail.
	114	+6. The run finishes when every job is done. Its conclusion is `failure` if any job failed or timed out (except jobs with `continue-on-error: true`), otherwise `cancelled` if the run was cancelled or any job was cancelled, otherwise `success`. Skipped jobs don't make a run fail.
115	115
116	116	### Timeouts
117	117
		@@ -128,6 +128,7 @@
128	128	\| Status \| Meaning \|
129	129	\| --- \| --- \|
130	130	\| `queued` \| The run or job has been created and hasn't started. \|
	131	+\| `pending` \| (Jobs) The job is held back by its job-level `concurrency` group until the group's running job finishes. Shown as Pending. \|
131	132	\| `waiting` \| (Jobs) The job is waiting for its container to start, or for a self-hosted runner to claim it. \|
132	133	\| `in_progress` \| The run is executing, or a runner has picked up the job. \|
133	134	\| `completed` \| Finished. See the conclusion. \|
		@@ -135,8 +136,8 @@
135	136	\| Conclusion \| Meaning \|
136	137	\| --- \| --- \|
137	138	\| `success` \| Every step succeeded (steps with `continue-on-error: true` may have failed). \|
138		-\| `failure` \| A step failed, the job could not start, or (for runs) a job failed. \|
139		-\| `cancelled` \| Someone cancelled the run, a newer run in the same concurrency group replaced it, or a sibling matrix job failed with `fail-fast` on. \|
	139	+\| `failure` \| A step failed, the job could not start, or (for runs) a job without `continue-on-error: true` failed. \|
	140	+\| `cancelled` \| Someone cancelled the run, a newer run or job in the same concurrency group replaced it, or a sibling matrix job failed or timed out with `fail-fast` on. \|
140	141	\| `skipped` \| The job's `if:` condition was false. \|
141	142	\| `timed_out` \| (Jobs) Diffinery waited 6 hours for the job without a result. \|
142	143
		@@ -156,11 +157,11 @@
156	157
157	158	### Run page
158	159
159		-Click a run to open `https://diffinery.com/acme/website/actions/runs/<run-id>`. It shows:
	160	+Click a run to open `https://diffinery.com/acme/website/actions/runs/<run-id>`. The run number works in place of the run ID (for example `.../actions/runs/128`) and opens its latest attempt. It shows:
160	161
161	162	- The run's Status and duration, what Triggered it and who, the Commit and ref (and pull request), and the Workflow file at that commit.
162	163	- One box per job id, listing the jobs it produced (a matrix job says how many, for example `4 jobs (matrix)`), each with its status, duration and, for a failed job, the first line of the failure reason.
163		-- Artifacts, when jobs uploaded any, with their size and age. Click a name to download it as a `.tar.gz` archive.
	164	+- Artifacts, when jobs uploaded any that haven't expired, with their size and age. Click a name to download it: a `.zip` file, or the file itself for an artifact uploaded with `archive: false`. See [Caching and artifacts](/docs/actions/caching-and-artifacts).
164	165	- Cancel run while the run is not completed (you confirm with Cancel this run?), and Re-run all jobs once it has completed. Both need write access.
165	166
166	167	### Job page and logs
		@@ -300,12 +301,12 @@
300	301	\| `GET /api/v3/repos/{owner}/{repo}/actions/runs/{run_id}/logs` \| A zip file with one text file per job (`1_<job name>.txt`, `2_<job name>.txt`, ...), each line prefixed with its timestamp. Holds at most 24 MB of logs; jobs past that are left out. \|
301	302	\| `GET /api/v3/repos/{owner}/{repo}/actions/jobs/{job_id}` \| One job, with its steps, outputs, failure and summary. \|
302	303	\| `GET /api/v3/repos/{owner}/{repo}/actions/jobs/{job_id}/logs` \| The log as text (`<timestamp> <line>` per line). Add `format=json` for JSON lines, and `after=<seq>` to get only lines after a sequence number. \|
303		-\| `GET /api/v3/repos/{owner}/{repo}/actions/runs/{run_id}/artifacts` \| The run's artifacts with `archive_download_url`. \|
	304	+\| `GET /api/v3/repos/{owner}/{repo}/actions/runs/{run_id}/artifacts` \| The run's artifacts (every attempt when `run_id` is a run number), expired ones included. See [Download artifacts with the API](/docs/actions/caching-and-artifacts#download-artifacts-with-the-api) for the other artifact and cache endpoints. \|
304	305	\| `POST /api/v3/repos/{owner}/{repo}/actions/runs/{run_id}/cancel` \| Cancels the run (`202`). Needs write. \|
305	306	\| `POST /api/v3/repos/{owner}/{repo}/actions/runs/{run_id}/rerun` \| Re-runs the run (`201`, `{"run_id": ...}`). Needs write. \|
306	307	\| `POST /api/v3/repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs` \| Same as `rerun` (see below). \|
307	308
308		-Run objects use GitHub's field names (`id`, `node_id`, `run_number`, `run_attempt`, `name`, `display_title`, `path`, `workflow_id`, `event`, `head_branch`, `head_sha`, `sha`, `ref`, `status`, `conclusion`, `actor` and `triggering_actor` as user objects, `created_at`, `updated_at`, `run_started_at`, `url`, `html_url`, `jobs_url`, `logs_url`, `artifacts_url`, `cancel_url`, `rerun_url`, `workflow_url`, `previous_attempt_url` and `pull_requests`) plus `pull_request_number`. Job objects carry GitHub's fields (`run_id`, `run_attempt`, `head_sha`, `head_branch`, `html_url`, `started_at`, `completed_at`, `workflow_name`, `steps` with `number`) next to Diffinery's own camelCase fields, which the CLI reads. `head_sha` is the commit checks are reported on (the pull request head for pull request runs) and `sha` is the commit the run checked out. Run and job IDs are 32-character hexadecimal strings, not numbers. While a job is running, one logs request returns at most 5,000 lines; page with `after`. The runs, jobs and artifacts lists send a `Link` header with `next`, `prev`, `first` and `last` URLs, so Octokit's `paginate()` works. Errors have a `message` and a `documentation_url`. Every endpoint is listed in the [API reference](/docs/api).
	309	+Run objects use GitHub's field names (`id`, `node_id`, `run_number`, `run_attempt`, `name`, `display_title`, `path`, `workflow_id`, `event`, `head_branch`, `head_sha`, `sha`, `ref`, `status`, `conclusion`, `actor` and `triggering_actor` as user objects, `created_at`, `updated_at`, `run_started_at`, `url`, `html_url`, `jobs_url`, `logs_url`, `artifacts_url`, `cancel_url`, `rerun_url`, `workflow_url`, `previous_attempt_url` and `pull_requests`) plus `pull_request_number`. Job objects carry GitHub's fields (`run_id`, `run_attempt`, `head_sha`, `head_branch`, `html_url`, `started_at`, `completed_at`, `workflow_name`, `steps` with `number`) next to Diffinery's own camelCase fields, which the CLI reads. `head_sha` is the commit checks are reported on (the pull request head for pull request runs) and `sha` is the commit the run checked out. Run and job IDs are 32-character hexadecimal strings. Wherever a path takes `{run_id}`, the run number works too and means its latest attempt; this is what `github.run_id` and `GITHUB_RUN_ID` hold inside a job. A job's `check_run_url` points at `GET /repos/{owner}/{repo}/check-runs/{job_id}`, which returns the job's check run. While a job is running, one logs request returns at most 5,000 lines; page with `after`. The runs, jobs and artifacts lists send a `Link` header with `next`, `prev`, `first` and `last` URLs, so Octokit's `paginate()` works. Errors have a `message` and a `documentation_url`. Every endpoint is listed in the [API reference](/docs/api).
309	310
310	311	### From MCP
311	312
		@@ -315,7 +316,7 @@
315	316
316	317	Click Cancel run on the run page, run `diffinery run cancel <run-id>`, call `POST /actions/runs/{run_id}/cancel`, or use the `cancel_workflow` MCP tool. You need write access.
317	318
318		-Cancelling stops every unfinished job's container and marks those jobs `cancelled` with the reason `Cancelled by <login>`. Jobs in later levels that have no `if:` condition are skipped; a job with `if: always()` or `if: cancelled()` still runs, as on GitHub. The run's conclusion is `cancelled`.
	319	+Cancelling stops every unfinished job's container and marks those jobs `cancelled` with the reason `Cancelled by <login>`. Jobs that haven't started yet and have no status function in their `if:` are skipped; a job with `if: always()` or `if: cancelled()` still runs, as on GitHub. The run's conclusion is `cancelled`.
319	320
320	321	## Re-run a run
321	322
		@@ -324,12 +325,15 @@
324	325	A re-run is a new run with:
325	326
326	327	- the same workflow file (read again from the original commit), commit, ref, event, event payload and inputs,
327		-- the same run number and an attempt number one higher (shown as `attempt 2`, and available as `github.run_attempt`),
328		-- a new run ID, and you as the actor.
	328	+- the same run number and an attempt number one higher (shown as `attempt 2`, and available as `github.run_attempt`), so `github.run_id` stays the same,
	329	+- a new run ID in the API, and you as the actor,
	330	+- whether its code came from an agent, kept from the original run whoever re-runs it (see [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions#runs-whose-code-came-from-an-agent)).
329	331
	332	+A workflow's own `GITHUB_TOKEN` can't re-run runs: `403 a workflow's GITHUB_TOKEN cannot re-run workflows`.
	333	+
330	334	It fails with `422 workflow file no longer valid at this commit` if the file can't be loaded from that commit any more.
331	335
332		-> Note: Diffinery always re-runs every job. `diffinery run rerun --failed` and `POST .../rerun-failed-jobs` are accepted for compatibility and behave like a full re-run. On GitHub a re-run keeps the same run ID; on Diffinery it gets a new one.
	336	+> Note: Diffinery always re-runs every job. `diffinery run rerun --failed` and `POST .../rerun-failed-jobs` are accepted for compatibility and behave like a full re-run. On GitHub a re-run keeps the same run ID in the API; on Diffinery the API's `id` is new, while `github.run_id` (the run number) stays the same.
333	337
334	338	## Job summaries
335	339
		@@ -386,8 +390,32 @@
386	390	- With `cancel-in-progress: true`, creating a run cancels every unfinished run (queued or in progress) in the same group, with the reason `cancelled by a newer run in the same concurrency group`.
387	391	- Without it, a new run waits while another run in the group is in progress, checking once a minute. After 6 hours of waiting it starts anyway.
388	392
389		-Differences from GitHub: GitHub keeps at most one pending run per group and cancels older pending ones; Diffinery lets several runs wait and starts them as the group frees up. Job-level `concurrency` (`jobs.<id>.concurrency`) is accepted but not enforced. If the group expression fails to evaluate, the run has no concurrency group.
	393	+Differences from GitHub: GitHub keeps at most one pending run per group and cancels older pending ones; Diffinery lets several runs wait and starts them as the group frees up. If the group expression fails to evaluate, the run has no concurrency group.
390	394
	395	+### Job concurrency
	396	+
	397	+`jobs.<id>.concurrency` limits a group to one running job at a time across the repository, whatever run or workflow the jobs belong to:
	398	+
	399	+```yaml
	400	+jobs:
	401	+ deploy:
	402	+ runs-on: ubuntu-latest
	403	+ concurrency:
	404	+ group: deploy-${{ matrix.env }}
	405	+ cancel-in-progress: false
	406	+ strategy:
	407	+ matrix:
	408	+ env: [staging, production]
	409	+ steps:
	410	+ - run: ./deploy.sh ${{ matrix.env }}
	411	+```
	412	+
	413	+- The group is evaluated for each matrix combination, with the `github`, `needs`, `inputs`, `vars`, `matrix` and `strategy` contexts.
	414	+- Without `cancel-in-progress`, a job whose group has a running job waits with the status `pending`. Only the newest pending job is kept: an older pending job of the group is cancelled.
	415	+- With `cancel-in-progress: true`, the new job takes the group and cancels the group's running and pending jobs.
	416	+- Jobs cancelled this way end as `cancelled` with the message `Canceling since a higher priority waiting request for '<group>' exists`.
	417	+- When the running job finishes, the oldest pending job of the group starts, from whichever run it belongs to.
	418	+
391	419	## Notifications
392	420
393	421	When a run completes with `success` or `failure`, Diffinery notifies the person who triggered it (for a run an agent triggered, the agent's owner; for runs started by the scheduler or the merge queue, the repository's watchers). By default they get an email and a web notification when a run fails; in their notification settings they can turn off Only failed runs to get emails for successful runs too. Cancelled runs don't notify anyone. See [Notifications](/docs/accounts/notifications).
		@@ -406,7 +434,9 @@
406	434	\| `This runner is being replaced by a new version. The job keeps running for up to 14 minutes before it is cancelled.` \| Diffinery is rolling out a new runner version. Jobs that finish within 14 minutes are unaffected; longer ones are cancelled and need a re-run. \|
407	435	\| `Error evaluating 'if': ...` \| The job's `if:` expression failed at runtime. See [Expressions](/docs/actions/expressions). \|
408	436	\| A step can't reach a secret \| Secrets are configured in the repository or organization settings. See [Secrets and variables](/docs/actions/secrets-and-variables). \|
409		-\| `git push` from a job fails \| The job's `GITHUB_TOKEN` has read access to the repository only. Push with a personal or agent token stored as a secret. \|
	437	+\| `git push` from a job fails \| The job's `GITHUB_TOKEN` needs `contents: write` (new repositories default to read-only tokens), can't change workflow files, and follows branch protection. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions). \|
	438	+\| `Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: ...)` \| Add the named scope to the job's `permissions:`. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions). \|
	439	+\| A job is `skipped` though its `if:` is true \| A job above it in the `needs` chain failed, was cancelled or was skipped. Add a status function, for example `if: ${{ !cancelled() && !failure() }}`. \|
410	440	\| `<branch> is not allowed to deploy to <environment> due to environment protection rules.` \| The job sets `environment:` and the environment's branch policy doesn't allow the run's ref. Run it from an allowed branch or tag, or change the policy. See [Environments](/docs/actions/environments). \|
411	441	\| `invalid environment name '<name>'` \| The job's `environment` name is empty, longer than 255 characters, or contains `/`, `\` or control characters. \|
412	442	\| An `on: release` workflow runs three times \| Creating a published release sends `created`, `published` and `released`. Add `types: [published]`. See [release](/docs/actions/events#release). \|

		@@ -83,7 +83,8 @@
83	83	\| `if` \| Skip the call (and every job inside it) when false. \|
84	84	\| `name` \| Display name, used as the prefix of the jobs inside the call. \|
85	85	\| `strategy` \| Accepted, but a `matrix` isn't supported yet (see [Matrix on the calling job](#matrix-on-the-calling-job)). \|
86		-\| `permissions`, `concurrency` \| Accepted but have no effect on a calling job. \|
	86	+\| `permissions` \| The most the jobs inside the call may have. They inherit these permissions, and anything the called workflow declares is lowered to them. See [Permissions in called workflows](#permissions-in-called-workflows). \|
	87	+\| `concurrency` \| Accepted but has no effect on a calling job. Jobs inside the called workflow can use their own job-level `concurrency`. \|
87	88
88	89	Any other key produces a warning (`unknown reusable-workflow job key '...'`) and is ignored. That includes `environment`: as on GitHub, a calling job can't use an environment, so put `environment:` on the jobs inside the called workflow (see [Environments in called workflows](#environments-in-called-workflows)). `steps` or `runs-on` on a calling job is an error.
89	90
		@@ -188,10 +189,28 @@
188	189	\| `env` \| The called workflow's own `env` (workflow and job level). The caller's `env` is not passed. \|
189	190	\| `needs` \| Job ids as written inside the called workflow. \|
190	191
191		-Because `github.repository` is the caller's, `actions/checkout` with no inputs checks out the calling repository, as on GitHub. To check out the repository that holds the workflow, pass `repository:` and a `token:` from a secret: the job's `GITHUB_TOKEN` can only read its own repository.
	192	+Because `github.repository` is the caller's, `actions/checkout` with no inputs checks out the calling repository, as on GitHub. To check out the repository that holds the workflow, pass `repository:`. The job's `GITHUB_TOKEN` can read that repository when it's public; when it's private, also pass a `token:` from a secret.
192	193
193		-`permissions` that control the job token (`id-token` and `packages`) are read from the called workflow itself: its workflow-level `permissions` or the job's own. The calling job's `permissions` isn't consulted.
	194	+### Permissions in called workflows
194	195
	196	+The jobs inside a call get their `GITHUB_TOKEN` permissions like this, as on GitHub:
	197	+
	198	+1. Start from the calling job's effective permissions: its own `permissions:`, or else the calling workflow's, or else the repository default.
	199	+2. If the called workflow or the called job declares `permissions:`, use that instead, but lowered scope by scope to what the calling job has. A called workflow can never get more than its caller.
	200	+3. If neither declares anything, the called jobs get exactly the calling job's permissions.
	201	+
	202	+```yaml
	203	+# .github/workflows/release.yml in acme/website
	204	+jobs:
	205	+ deploy:
	206	+ permissions:
	207	+ contents: read
	208	+ id-token: write
	209	+ uses: ./.github/workflows/deploy.yml
	210	+```
	211	+
	212	+Here the jobs in `deploy.yml` can have at most `contents: read` and `id-token: write`. If `deploy.yml` declares `permissions: write-all`, its jobs still get only those two. If it declares `packages: write`, its jobs get no `packages` access, because the calling job has none. This applies to `id-token` for [OIDC](/docs/actions/oidc), to `packages` for the [container registry](/docs/packages/container-registry), and to every other scope. See [GITHUB_TOKEN permissions](/docs/actions/workflow-permissions#reusable-workflows).
	213	+
195	214	## Environments in called workflows
196	215
197	216	A job inside a called workflow can deploy to an [environment](/docs/actions/environments) with `environment:`, and the environment's name and `url` can use the called workflow's `inputs`:
		@@ -212,7 +231,7 @@
212	231	- The environment belongs to the calling repository, the one whose run it is, even when the workflow file lives in another repository. Its branch policy is checked against the caller's ref.
213	232	- The job gets the environment's secrets and variables without the caller passing them in `secrets:`, as on GitHub. An environment secret replaces a passed secret with the same name.
214	233	- A secret declared with `required: true` under `on.workflow_call.secrets` must still be passed by the caller, even if the environment has it. Don't declare secrets that come from the environment.
215		-- The job records a deployment like any other job with `environment:`, and the usual rules for who receives environment secrets apply (pull request refs never do; runs started by agents only from environments set to protected branches only).
	234	+- The job records a deployment like any other job with `environment:`, and the usual rules for who receives environment secrets apply (pull request refs never do; runs whose code came from an agent only from environments set to protected branches only).
216	235
217	236	## How calls appear in runs and checks
218	237
		@@ -222,7 +241,7 @@
222	241
223	242	- Jobs inside the call that have no `needs` wait for the calling job's `needs`.
224	243	- A job that `needs` the calling job waits for every job inside the call.
225		-- If the calling job's `if` is false, or its `needs` failed, every job inside the call is reported as skipped.
	244	+- If the calling job's `if` is false, or (with the default `if`) any job it depends on, directly or through other jobs, failed or was skipped, every job inside the call is reported as skipped.
226	245
227	246	## Nesting
228	247
		@@ -363,8 +382,7 @@
363	382	\| Where workflows come from \| Only repositories on the same Diffinery instance. \|
364	383	\| Private repositories \| Callable only from repositories with the same owner. \|
365	384	\| Matrix on the calling job \| Not supported yet. \|
366		-\| `permissions` on the calling job \| Ignored. The called workflow's own `permissions` control `id-token` and `packages`. \|
367		-\| `concurrency` \| Only the top-level workflow's `concurrency` applies. A called workflow's `concurrency` and a calling job's `concurrency` are ignored. \|
	385	+\| `concurrency` \| The top-level workflow's `concurrency` and job-level `concurrency` on the jobs inside a call apply. A called workflow's top-level `concurrency` and a calling job's `concurrency` are ignored. \|
368	386	\| Number of calls per run \| At most 20. \|
369	387	\| OIDC `job_workflow_ref` claim \| The top-level workflow's reference, not the called workflow's. See [OpenID Connect (OIDC)](/docs/actions/oidc). \|
370	388	\| Branch references \| Re-resolved whenever a job of the run is planned or started. \|

		@@ -30,7 +30,8 @@
30	30
31	31	- Every `ubuntu-*` label gets the same Ubuntu 24.04 x64 image, including `ubuntu-22.04` and labels that ask for Arm, such as `ubuntu-24.04-arm`.
32	32	- `runs-on` can be a string, a list, or a mapping with `labels`. A `group` in the mapping form is ignored; only `labels` count.
33		-- `runs-on` is evaluated once per job, before the matrix is expanded, so it can use `github`, `inputs`, `vars` and `needs` but not `matrix`. `runs-on: ${{ matrix.os }}` evaluates to `null` and fails with "No Diffinery runner matches runs-on: null". Use a literal label (hosted runners are all the same Linux image anyway) or split the job.
	33	+- `runs-on` is evaluated for each matrix combination, so an entry can be an expression using `github`, `inputs`, `vars`, `needs`, `matrix` and `strategy`. An expression can give one label or a list of labels. Empty and `null` values are dropped.
	34	+- If evaluating `runs-on` fails, only that matrix combination fails, with `Error evaluating the job for this matrix combination: <message>`. If no labels are left, the job fails with `No Diffinery runner matches runs-on: (no labels). ...`.
34	35
35	36	```yaml
36	37	jobs:
		@@ -38,6 +39,15 @@
38	39	runs-on: ubuntu-latest # hosted
39	40	steps:
40	41	- run: echo "hosted"
	42	+ build:
	43	+ strategy:
	44	+ matrix:
	45	+ target: [linux, macos]
	46	+ # The linux leg runs on a hosted runner; the macos leg waits for a
	47	+ # self-hosted runner with the macos label.
	48	+ runs-on: ${{ matrix.target == 'macos' && fromJSON('["self-hosted","macos"]') \|\| 'ubuntu-latest' }}
	49	+ steps:
	50	+ - run: uname -a
41	51	gpu:
42	52	runs-on: [self-hosted, linux, gpu] # waits for a runner started with --labels linux,gpu
43	53	steps:
		@@ -69,7 +79,8 @@
69	79
70	80	\| Group \| Installed \|
71	81	\|---\|---\|
72		-\| Base tools \| `ca-certificates`, `curl`, `git`, `git-lfs`, `jq`, `zip`, `unzip`, `xz-utils`, `tar`, `gzip`, `pkg-config`, `openssh-client`, `gnupg` \|
	82	+\| Base tools \| `ca-certificates`, `curl`, `git`, `git-lfs`, `jq`, `zip`, `unzip`, `xz-utils`, `tar`, `gzip`, `zstd`, `pkg-config`, `openssh-client`, `gnupg` \|
	83	+\| GitHub CLI \| `gh`, from GitHub's apt repository \|
73	84	\| Build tools \| `build-essential` (gcc, g++, make and the C library headers) \|
74	85	\| Python \| Ubuntu's `python3` (3.12), `python3-pip`, `python3-venv`, `python-is-python3` (so `python` runs `python3`) \|
75	86	\| Node.js \| Node.js 22.22.0 with npm, plus corepack shims activated for pnpm 10.28.0 and yarn 1.22.22 \|
		@@ -80,6 +91,8 @@
80	91	- `git config --system safe.directory '*'` is set, and Git LFS is installed system-wide.
81	92	- `PIP_BREAK_SYSTEM_PACKAGES=1` is set, so `pip install` works without a virtual environment, as on GitHub's hosted runners.
82	93	- `COREPACK_ENABLE_DOWNLOAD_PROMPT=0` is set, so corepack never stops to ask.
	94	+- `ImageOS=ubuntu24` and `ImageVersion=20250101.1` are set, as on GitHub's `ubuntu-24.04` image. `actions/setup-go` and `actions/setup-python` include them in their cache keys.
	95	+- `zstd` is installed, so `actions/cache` compresses with zstd, as on GitHub.
83	96	- The apt package lists are removed to keep the image small. Run `apt-get update` before `apt-get install`.
84	97
85	98	Anything else (Go, Java, Ruby, Rust, .NET, PowerShell, browsers, cloud CLIs) is not preinstalled. Install it in a step:
		@@ -113,6 +126,12 @@
113	126
114	127	Hosted and self-hosted runners set the GitHub-compatible variables (`CI=true`, `GITHUB_ACTIONS=true`, `GITHUB_REPOSITORY`, `GITHUB_SHA`, `GITHUB_REF`, `GITHUB_WORKSPACE`, `GITHUB_ENV`, `GITHUB_OUTPUT`, and so on) plus `DIFFINERY=true`. `GITHUB_SERVER_URL` is `https://diffinery.com` and `GITHUB_API_URL` is `https://diffinery.com/api/v3`. `RUNNER_NAME` is `diffinery` and `RUNNER_ENVIRONMENT` is `diffinery-hosted` on every runner. Workflows can override `CI` and `DIFFINERY`, but not `GITHUB_` or `RUNNER_` variables.
115	128
	129	+Other variables a job gets:
	130	+
	131	+- `ImageOS` and `ImageVersion`, on hosted and self-hosted runners alike (`ubuntu24` and `20250101.1` unless the runner's environment sets them).
	132	+- `RUNNER_DEBUG=1` when the secret or variable `ACTIONS_STEP_DEBUG` or `ACTIONS_RUNNER_DEBUG` is `true`. See [Expressions and contexts](/docs/actions/expressions#default-environment-variables).
	133	+- `ACTIONS_RUNTIME_TOKEN`, `ACTIONS_RUNTIME_URL`, `ACTIONS_RESULTS_URL`, `ACTIONS_CACHE_URL` and `ACTIONS_CACHE_SERVICE_V2`, but only in JavaScript actions, Docker container actions and the built-in actions, never in `run:` steps. They let actions such as `actions/cache` and `actions/upload-artifact` use the cache and artifact services. See [Caching and artifacts](/docs/actions/caching-and-artifacts#the-runtime-services).
	134	+
116	135	### Limits and timeouts
117	136
118	137	\| Limit \| Value \| What happens \|
		@@ -244,11 +263,12 @@
244	263	### What a job sees on a self-hosted runner
245	264
246	265	- The job runs directly on the machine, as the user that started `diffinery runner`, with that user's files, network and permissions.
247		-- The job's environment is the runner's environment, minus `DIFFINERY_TOKEN`, `DIFFINERY_URL`, `DIFFINERY_RUNNER_AGENT`, `GH_TOKEN` and `GITHUB_TOKEN`, plus the usual `GITHUB_` and `RUNNER_` variables.
	266	+- The job's environment is the runner's environment, minus `DIFFINERY_TOKEN`, `DIFFINERY_URL`, `DIFFINERY_RUNNER_AGENT`, `GH_TOKEN` and `GITHUB_TOKEN`, plus the usual `GITHUB_` and `RUNNER_` variables. `DIFFINERY_GITHUB_TOKEN` (see below) is used by the agent to download actions but is removed from every step's environment.
248	267	- The workspace is `<work dir>/<repository name>` and is not wiped between jobs. `actions/checkout` cleans it by default (`clean: true`).
249	268	- The tool cache (`RUNNER_TOOL_CACHE`) is `<work dir>/_tool` unless the runner's environment sets `RUNNER_TOOL_CACHE`. Tools that `setup-node`, `setup-python` and `setup-go` download stay there for later jobs.
250	269	- `runner.os` reports `Linux` and `RUNNER_ENVIRONMENT` reports `diffinery-hosted` on every machine, including Macs. Use your own labels, or check `uname` in a step, if a workflow needs to know the platform.
251		-- Remote actions (`uses: owner/repo@ref`) are downloaded from `codeload.github.com`. Set `DIFFINERY_GITHUB_TOKEN` in the runner's environment to authenticate those downloads (useful against GitHub's rate limits), or `DIFFINERY_ACTIONS_DOWNLOAD_URL` to a URL template containing `{owner}`, `{repo}` and `{ref}` to download from a mirror instead.
	270	+- Remote actions (`uses: owner/repo@ref`) are downloaded from `codeload.github.com`. Set `DIFFINERY_GITHUB_TOKEN` in the runner's environment to authenticate those downloads (useful against GitHub's rate limits), or `DIFFINERY_ACTIONS_DOWNLOAD_URL` to a URL template containing `{owner}`, `{repo}` and `{ref}` to download from a mirror instead. If the download from `codeload.github.com` fails, the agent tries a shallow `git fetch` of the ref from `https://github.com/<owner>/<repo>` before failing the step with `Failed to download action '<owner>/<repo>@<ref>': ...`. There is no `git` fallback when `DIFFINERY_ACTIONS_DOWNLOAD_URL` is set.
	271	+- The common official actions (`actions/checkout`, `actions/cache`, `actions/upload-artifact`, `actions/download-artifact`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go`) run as built-in implementations when the version and inputs allow it. Set `DIFFINERY_DISABLE_BUILTINS=1` in the runner's environment to always download and run the real actions on that runner. See [Compatibility with GitHub Actions](/docs/actions/compatibility#built-in-actions).
252	272	- `setup-node`, `setup-python` and `setup-go` download their tools from `nodejs.org/dist`, the `actions/python-versions` manifest and `go.dev`. Override the sources with `DIFFINERY_NODE_MIRROR`, `DIFFINERY_PYTHON_MANIFEST` and `DIFFINERY_GO_INDEX` in the runner's environment if the machine can't reach them.
253	273
254	274	### Run as a service with systemd
		@@ -343,7 +363,7 @@
343	363	\| Symptom \| Cause and fix \|
344	364	\|---\|---\|
345	365	\| `No Diffinery runner matches runs-on: ...` \| A label isn't hosted and the job doesn't include `self-hosted`. Use an `ubuntu-*` label, or add `self-hosted` and start a runner with matching `--labels`. \|
346		-\| `No Diffinery runner matches runs-on: null` \| `runs-on` uses `matrix`, which isn't available there. Use a literal label. \|
	366	+\| `No Diffinery runner matches runs-on: (no labels)` \| Every `runs-on` entry evaluated to an empty value, for example a `matrix` key that the combination doesn't set. Check the expression. \|
347	367	\| A self-hosted job stays queued \| No runner serving that repository offers every label. Compare the job's `runs-on` with the labels the runner printed at start. The job fails after 6 hours. \|
348	368	\| `403 admin access required` \| The runner's token or account lacks admin on the repository, or the token isn't `admin`-scoped. \|
349	369	\| `no runner agent given` or `runner agent not found at ...` \| Pass `--agent /path/to/agent.mjs` or set `DIFFINERY_RUNNER_AGENT`. Build it with `pnpm --filter @diffinery/runner build`. \|

		@@ -1,13 +1,13 @@
1	1	---
2	2	title: Site administration
3		-description: What site administrators do: manage people and access requests, invite people, issue sign-in links, read the audit log and check email delivery.
	3	+description: What site administrators do: manage people and access, invite people, issue sign-in links, oversee GitHub imports, read the audit log and check email.
4	4	---
5	5
6	6	Site administrators run a Diffinery instance. They decide who gets in, help people who lost their passkeys, and check the audit log and email delivery. This page covers who the site administrators are and each page in the Site administration group of Settings.
7	7
8	8	## Site administrators
9	9
10		-Site administrators have admin on every repository, can act as an owner of every organization (including its Settings tab, where the organization's name and picture are changed, and the Add people form on its People tab), and see an extra Site administration group in the Settings sidebar with three pages:
	10	+Site administrators have admin on every repository, can act as an owner of every organization (including its Settings tab, where the organization's name, picture and base permission are changed, and the Add people form on its People tab), and see an extra Site administration group in the Settings sidebar with three pages:
11	11
12	12	\| Page \| Path \| What it is for \|
13	13	\| --- \| --- \| --- \|
		@@ -106,9 +106,27 @@
106	106
107	107	Anyone with the link can add a passkey to the account, so send it only to that person. The link also works for a first sign-in, for an account that exists but has no passkey yet.
108	108
	109	+## GitHub imports and linked accounts
	110	+
	111	+Site administrators have extra reach over [imports from GitHub](/docs/migrate-from-github):
	112	+
	113	+- Import into any account. A site administrator can start an import into any user's account or any organization, not only their own (agent accounts can't own imports).
	114	+- See and cancel any import. Open `https://diffinery.com/imports/<id>`, or call `GET /api/v3/diffinery/imports/{id}`, for any import, and stop one with Cancel import or `POST /api/v3/diffinery/imports/{id}/cancel` (audited as `import.cancel`, with you in `by`). The Imports page and `GET /api/v3/diffinery/imports` still list only the imports you started yourself.
	115	+- Retrying stays with the starter. Only the person or agent who started an import can retry it, site administrators included.
	116	+
	117	+### Clear a GitHub link
	118	+
	119	+An import attributes a GitHub user's issues, pull requests, comments and reviews to the Diffinery account linked to that GitHub user. If a link is wrong, for example after a Diffinery account changed hands, a site administrator can remove it. There is no page for this; use the API with an `admin`-scoped token that isn't limited to repositories (or a browser session):
	120	+
	121	+```sh
	122	+diffinery api DELETE /diffinery/admin/linked-accounts/<link id>
	123	+```
	124	+
	125	+The link id comes from `GET /api/v3/diffinery/user/linked-accounts`, called by the account that owns the link; Diffinery has no endpoint that lists other people's links. The request answers `204`, or `404 link not found`, and is audited as `account.link_cleared` with the link (`github.com/diffy`) as the target and the Diffinery account's id in the detail. Imports that already ran keep their attribution; later imports treat that GitHub user as a mannequin until someone links the account again. People unlink their own accounts on Settings → Linked accounts (`account.unlink_github`).
	126	+
109	127	## Audit log
110	128
111		-Settings → Audit log (`/settings/audit`) shows the 200 most recent security-relevant events: sign-ins, passkeys, tokens, invites, account status changes, repository and access changes, pushes, merges and push protection. Each row has When, Actor (and who an agent acted for), Action, Target and Detail. See [Audit log](/docs/security/audit-log) for every action and how to use it.
	129	+Settings → Audit log (`/settings/audit`) shows the 200 most recent security-relevant events: sign-ins, passkeys, tokens, invites, account status changes, repository and access changes, pushes, merges and push protection. Repository and organization settings changed through the REST API or the CLI are recorded too: repository settings, archiving, collaborators, branch protection, Actions secrets and variables (repository, environment and organization), webhooks, a repository's workflow token settings, and deleted Actions artifacts and caches. Imports from GitHub (`import.create`, `import.push`, `import.finish` and the rest) and linked GitHub accounts are recorded too. Settings changes made through the API have `via: api` in their Detail. Each row has When, Actor (and who an agent acted for), Action, Target and Detail. See [Audit log](/docs/security/audit-log) for every action and how to use it.
112	130
113	131	## Email
114	132
		@@ -118,7 +136,7 @@
118	136	\| --- \| --- \|
119	137	\| Sending \| "Cloudflare Email Sending is bound", or "not configured (no EMAIL binding): emails are logged, not sent" \|
120	138	\| Queue \| `diffinery-mail`, or "not bound: emails are dropped" \|
121		-\| From \| The sender address set in `MAIL_FROM` (see [Configuration](/docs/self-hosting/configuration)) \|
	139	+\| From \| The address emails are sent from: `MAIL_FROM`, or `notifications@<your hostname>` when it is empty (see [Configuration](/docs/self-hosting/configuration)) \|
122	140	\| Last 24 hours \| How many emails were sent, failed and skipped \|
123	141
124	142	Buttons:
		@@ -136,7 +154,7 @@
136	154
137	155	\| Method and path \| Description \| Needs \|
138	156	\| --- \| --- \| --- \|
139		-\| `GET /api/v3/diffinery/admin/email` \| `sending` and `queue` (whether they are configured), `from` (`MAIL_FROM`, or `null` when unset), `last_24h` counts (`sent`, `failed`, `skipped`) and the `last` email logged \| site administrator, any token scope \|
	157	+\| `GET /api/v3/diffinery/admin/email` \| `sending` and `queue` (whether they are configured), `from` (the sender address: `MAIL_FROM`, or `notifications@<your hostname>` when it is empty), `last_24h` counts (`sent`, `failed`, `skipped`) and the `last` email logged \| site administrator, any token scope \|
140	158	\| `POST /api/v3/diffinery/admin/emails/samples` \| Send every template to yourself now, or only some with `{"only": ["signin", "invite-org"]}`. Returns `to`, `sent`, `total` and each result. \| site administrator, with an `admin` token for all repositories or a browser session \|
141	159	\| `GET /api/v3/diffinery/emails?all=1` \| Everyone's recent emails (without `all=1`, only yours). Also takes `kind`, `since` and `per_page` (up to 500). \| site administrator for `all=1` \|
142	160
		@@ -175,6 +193,8 @@
175	193	\| Message \| Cause and fix \|
176	194	\| --- \| --- \|
177	195	\| `403 site administrators only` \| Your account isn't a site administrator. \|
	196	+\| `403 site admin only` from `DELETE /api/v3/diffinery/admin/linked-accounts/{id}` \| Your account isn't a site administrator. \|
	197	+\| `404 link not found` \| No GitHub link has that id. Ask the account's owner for the id from `GET /api/v3/diffinery/user/linked-accounts`. \|
178	198	\| "you cannot change your own status" \| Ask another site administrator. \|
179	199	\| "enable this account first" \| Sign-in links can't be created for disabled accounts. Set the status to `active`, then create the link. \|
180	200	\| "enter a valid email address" \| The invite form needs an address like `friend@example.com`. \|

		@@ -3,7 +3,7 @@
3	3	description: Connect AI agents to Diffinery over the Model Context Protocol at https://diffinery.com/mcp, with client setup, the tool list, permissions and example calls.
4	4	---
5	5
6		-Diffinery runs a Model Context Protocol (MCP) server at `https://diffinery.com/mcp`. An MCP client such as Claude Code, Cursor or VS Code can use it to read code, commit changes, open and review pull requests, follow CI, publish releases, run commands in sandboxes and look things up in these docs, all without a git client. Every tool goes through the same permission checks, branch protection and agent guardrails as git and the REST API.
	6	+Diffinery runs a Model Context Protocol (MCP) server at `https://diffinery.com/mcp`. An MCP client such as Claude Code, Cursor or VS Code can use it to read code, commit changes, open and review pull requests, follow CI, publish releases, run commands in sandboxes, import repositories from GitHub and look things up in these docs, all without a git client. Every tool goes through the same permission checks, branch protection and agent guardrails as git and the REST API.
7	7
8	8	## Endpoint and transport
9	9
		@@ -123,7 +123,7 @@
123	123
124	124	## Tools
125	125
126		-Every tool that works on a repository takes `owner` and `repo`. Tools marked read-only have the MCP annotation `readOnlyHint: true`, so clients can run them without asking. Every tool marked No needs a token with the `write` or `admin` scope, whatever its minimum role. The full input schema of each tool is on [MCP tools reference](/docs/reference/mcp-tools), and `tools/list` returns it at runtime.
	126	+Every tool that works on a repository takes `owner` and `repo`. A repository that was transferred or renamed is also found under its old owner and name, for anyone who can read it, so an agent configured with the old name keeps working. Tools marked read-only have the MCP annotation `readOnlyHint: true`, so clients can run them without asking. Every tool marked No needs a token with the `write` or `admin` scope, whatever its minimum role. The full input schema of each tool is on [MCP tools reference](/docs/reference/mcp-tools), and `tools/list` returns it at runtime.
127	127
128	128	### Account and repositories
129	129
		@@ -160,7 +160,9 @@
160	160	\| `create_pull_request` \| No \| Open a pull request: `title`, `head`, optional `base`, `body`, `draft`, `intent`, `reviewers` \| write \|
161	161	\| `comment` \| No \| Comment on an issue or pull request \| triage \|
162	162	\| `review_pull_request` \| No \| Submit an `APPROVE`, `REQUEST_CHANGES` or `COMMENT` review, with optional line `comments` \| read (write to approve or request changes) \|
163		-\| `merge_pull_request` \| No \| Merge with `method`, `expected_head_sha`, `delete_branch`; queues the pull request when the base branch uses a merge queue \| write \|
	163	+\| `merge_pull_request` \| No \| Merge with `method`, `expected_head_sha`, `delete_branch`; queues the pull request when the base branch uses a merge queue. Agents can't merge into the default branch or protected branches this way: they use `enable_auto_merge` \| write \|
	164	+\| `enable_auto_merge` \| No \| Turn on auto-merge, optionally with `merge_method`, `commit_title` and `commit_message`: Diffinery merges the pull request (or adds it to the merge queue) once every branch rule is met. Returns `state` (`enabled`, `queued` or `merged`), `autoMerge` and, once merged, `mergeCommit`. See [Auto-merge](/docs/collaboration/pull-requests#auto-merge) \| write \|
	165	+\| `disable_auto_merge` \| No \| Turn auto-merge off; returns `{"auto_merge": null}` \| write \|
164	166	\| `dequeue_pull_request` \| No \| Remove a pull request from the merge queue \| write \|
165	167
166	168	### Issues
		@@ -169,7 +171,7 @@
169	171	\| --- \| --- \| --- \| --- \|
170	172	\| `list_issues` \| Yes \| Up to 100 issues by `state`, search text `q` and `label` \| read \|
171	173	\| `get_issue` \| Yes \| An issue (or pull request) with its comments and reviews \| read \|
172		-\| `create_issue` \| No \| Open an issue with `title`, optional `body` and `labels` \| read \|
	174	+\| `create_issue` \| No \| Open an issue with `title`, optional `body` and `labels` (`labels` from an account below triage are dropped, as on GitHub) \| read \|
173	175	\| `update_issue` \| No \| Change the `title`, `body`, `state` (`open`, `closed`) or `labels` of an issue or pull request \| triage \|
174	176
175	177	### Workflows
		@@ -215,6 +217,14 @@
215	217
216	218	See [Sandboxes](/docs/agents/sandboxes) for what is inside a sandbox and its limits.
217	219
	220	+### Imports from GitHub
	221	+
	222	+\| Tool \| Read-only \| What it does \| Minimum role \|
	223	+\| --- \| --- \| --- \| --- \|
	224	+\| `start_github_import` \| No \| Start a server-side import of one GitHub repository: `source` (`owner/name` or a GitHub URL) and `owner` (the Diffinery organization or user to import into), optional `name`, `visibility` (`keep`, `private`, `public`), `github_token` and `github_api_url`. Returns the import, with its `id`. \| See [Imports over MCP](#imports-over-mcp) \|
	225	+\| `get_import` \| Yes \| An import by `id`: `status`, per-step progress, `git` transfer progress, `summary`, `warnings`, `error` and, for an organization import, its repositories \| You started it; a person who administers its target, or a site administrator, can also read it \|
	226	+\| `list_imports` \| Yes \| The imports you started, newest first \| Any token \|
	227	+
218	228	## Commit without git
219	229
220	230	`commit_files` creates a single commit from file contents:
		@@ -230,6 +240,8 @@
230	240
231	241	It returns `{ "sha": "...", "branch": "..." }`. At least one file or delete is required (`nothing to commit`). Committing to a branch that doesn't exist without `create_branch_from` fails with `branch fix-pricing-link not found`. Commits made by agents are stamped with the agent and its owner; see [Agents](/docs/agents/overview#how-agent-activity-is-recorded).
232	242
	243	+`commit_files` runs [push protection](/docs/security/push-protection) before it writes anything, like `git push`. If a file under 1 MiB looks like a credential (an AWS key, a GitHub or Diffinery token, a private key and so on), nothing is committed and the tool fails with, for example, `push protection: possible secret detected (AWS access key) in config/deploy.env. Remove it, or rotate it and ask an admin.` The attempt is recorded in the audit log as `api.blocked_secret` against the token's account. `commit_files` has no bypass. For a test fixture with fake keys, put the text `diffinery:allow-secret` anywhere in the file.
	244	+
233	245	## Releases over MCP
234	246
235	247	Release tools return a compact release object:
		@@ -258,6 +270,33 @@
258	270	- `generate_release_notes` only drafts text; pass its `body` to `create_release`, or set `generate_release_notes: true` there.
259	271	- Publishing a release for a tag that doesn't exist creates the tag at `target_commitish`, and that follows the same rules as any ref update. A draft creates its tag only when it is published.
260	272
	273	+## Imports over MCP
	274	+
	275	+`start_github_import` starts the same server-side importer as the web UI, `diffinery migrate github` and `POST /api/v3/diffinery/imports`. It imports one repository with every part turned on: Git history and Git LFS, issues and pull requests with their numbers, comments, reviews and review comments, labels, milestones, branch protection, releases, and (for people) Actions variables, environments and secret names. Secret values are never read from GitHub. The tool returns at once; the import runs on the server.
	276	+
	277	+```sh
	278	+curl -s https://diffinery.com/mcp \
	279	+ -H "Authorization: Bearer $DIFFINERY_TOKEN" -H "Content-Type: application/json" \
	280	+ -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"start_github_import","arguments":{"source":"acme/website","owner":"acme","github_token":"ghp_..."}}}'
	281	+```
	282	+
	283	+The result is the import object (`id`, `html_url`, `status`, `source`, `target`, `steps`, `git`, `summary`, `warnings`, `error`). Call `get_import` with the `id` every minute or so until `status` is `succeeded`, `failed` or `cancelled`. While the import runs, every push to the new repository is refused with `repository is locked by an import in progress`.
	284	+
	285	+Who can start one:
	286	+
	287	+- The token needs the `write` or `admin` scope (`starting an import needs a token with write or admin scope`).
	288	+- A person can import into their own account or an organization they own or administer.
	289	+- An agent can import only into an organization: the one that owns it, or one where its owner is an owner or admin (`agents can import only into organizations they or their owner administer`). Its maximum role must be at least `write` (`this agent's policy does not allow writing; an import needs at least write`).
	290	+
	291	+Rules for imports an agent starts:
	292	+
	293	+- Push protection is never bypassed. If old history contains something that looks like a credential, the import stops and fails with `Push protection found possible secrets in the history (...)`. A person who administers the target starts a new import from the web or API to import it with an audited bypass.
	294	+- Variables, secret names and environments are skipped (`skipped (agents cannot manage variables)`); a person sets them up afterwards. Agents never read or set secret values.
	295	+- No retry once the repository exists. Retrying is limited to whoever started the import, through the web or REST API, and an agent's retry is refused after the repository was created.
	296	+- The agent sees only the imports it started (`get_import`, `list_imports`).
	297	+
	298	+An import uses the GitHub token only for that import, deletes it when the import ends, and never returns it. For GitHub Enterprise, pass `github_api_url`, for example `https://ghe.example.com/api/v3`; when `source` is an Enterprise URL and you pass a token, `github_api_url` must be on the same host. See [Migrate from GitHub](/docs/migrate-from-github) for what is copied, limits (at most 3 repository imports at a time per account and per target) and errors.
	299	+
261	300	## Permissions
262	301
263	302	The token's account (person or agent), its role on the repository and the token's scope decide what each tool may do, exactly as for the REST API. The minimum role for each tool is in the tables above.
		@@ -272,10 +311,14 @@
272	311
273	312	On top of the role and scope:
274	313
275		-- Agents can't push or commit to the default branch or protected branches, and can't merge into them, unless the branch's rule allows it (`agentsMayPush`, `agentsMayMerge`).
	314	+- Agents can't push or commit to the default branch or protected branches, and can't merge into them, unless the branch's rule allows it (`agentsMayPush`, `agentsMayMerge`). Where the rule has `allowAgentAutoMerge` and a required check, an agent lands its pull request there with `enable_auto_merge` instead, and Diffinery merges once the rules are met (see [Agents landing changes](/docs/repositories/branch-protection#agents-landing-changes)).
276	315	- Pull requests opened by agents need a human approval, and approvals submitted by agents with `review_pull_request` never count toward it.
277	316	- Private repositories you can't see return `repository not found`, the same as a repository that doesn't exist.
	317	+- Archived repositories refuse every tool that changes something (`repository is archived (read-only)`), whatever the role. Read-only tools keep working.
	318	+- `commit_files` refuses files that look like credentials (see [Commit without git](#commit-without-git)).
	319	+- `create_issue` drops `labels` when the account's role is below triage, as GitHub does for issues opened by people without triage access.
278	320	- Release tools follow the same rules as the REST API: anyone who can read the repository can list published releases, writers create, edit and publish them and see drafts, and a release that creates a tag is a ref update, so agent branch and tag rules apply.
	321	+- `start_github_import` follows the agent import rules in [Imports over MCP](#imports-over-mcp).
279	322	- `search_docs` and `read_docs` read the public documentation. They work with any token, read-only included, and don't touch a repository.
280	323
281	324	See [Agents](/docs/agents/overview#guardrails) and [Permissions](/docs/accounts/permissions).
		@@ -405,7 +448,7 @@
405	448	5. `sandbox_create` and `sandbox_exec` to build and run tests when needed.
406	449	6. `create_pull_request` with an `intent` that states the goal.
407	450	7. `list_workflow_runs`, `get_workflow_run` and `get_job_logs` to follow CI, fixing failures with more commits.
408		-8. `get_pull_request` to read reviews and the remaining merge blockers. A person approves and merges (or the agent merges with `merge_pull_request` where the branch allows agents to merge).
	451	+8. `get_pull_request` to read reviews and the remaining merge blockers. A person approves and merges. Or the agent calls `enable_auto_merge` where the branch allows it (`allowAgentAutoMerge`), and Diffinery merges once the checks pass and a person has approved, or merges with `merge_pull_request` where the branch allows agents to merge.
409	452
410	453	## Limitations
411	454
		@@ -419,13 +462,20 @@
419	462	\| --- \| --- \|
420	463	\| The client says it can't connect or gets `401` \| The `Authorization` header is missing or the token is wrong. Check the header name and the `Bearer ` prefix, and that the token hasn't expired. \|
421	464	\| `repository not found` \| Wrong `owner` or `repo`, or the account (or, for an agent, its owner) can't see the repository. \|
422		-\| `this token needs the write scope` \| The tool isn't read-only and the token has only the `read` scope. Create a `write` token (for an agent, in Settings → Agents or with `POST /api/v3/diffinery/agents/{login}/tokens`). \|
	465	+\| `this token needs the write scope` \| The tool isn't read-only and the token has only the `read` scope. Create a `write` token (for an agent, in Settings → Agents while signed in). \|
423	466	\| `write access required` (or `triage access required`) \| The account's role, or the token's scope, is too low for the tool. A `read` token can only use read-only tools. \|
424	467	\| `agents may not push to protected or default branches; open a pull request` \| Commit to a new branch with `create_branch_from` and open a pull request. \|
	468	+\| `agents may not merge into this branch; a human must merge` \| `merge_pull_request` into the default branch or a protected branch. Use `enable_auto_merge` where the branch allows it, or ask a person to merge. \|
	469	+\| `agents may not have pull requests merged into main automatically unless its branch protection allows it ...` \| `enable_auto_merge` on a branch whose rule doesn't set `allowAgentAutoMerge`. A person merges, or an admin allows it. \|
	470	+\| `Auto-merge was turned off: ...` (a comment on the pull request) \| Auto-merge stopped, for example because someone else pushed to the branch. Read the reason and call `enable_auto_merge` again. See [When auto-merge turns itself off](/docs/collaboration/pull-requests#when-auto-merge-turns-itself-off). \|
425	471	\| `branch moved; refresh and retry` \| Someone else committed to the branch. Read the new head and retry with the new `expected_head_sha`. \|
	472	+\| `push protection: possible secret detected (...)` \| A file passed to `commit_files` looks like a credential. Remove it and commit again, or add `diffinery:allow-secret` to a file whose keys are fake. \|
	473	+\| `repository is archived (read-only)` \| The repository is archived. Only read-only tools work until a repository admin unarchives it. \|
426	474	\| `method not found: resources/list` \| The server only offers tools; the client can ignore this. \|
427	475	\| `MCP uploads are limited to 25 MB; use the upload_url of the REST API for larger files` \| `upload_release_asset` takes the file inline. Upload larger files (up to 100 MB) to the release's `upload_url` with the [REST API](/docs/reference/rest-api#release-assets). \|
428	476	\| `pass exactly one of content or content_base64` \| `upload_release_asset` needs the file as either text or base64, not both and not neither. \|
429	477	\| `make_latest must be true, false or legacy` \| Pass `make_latest` as one of those strings, not as a boolean. \|
430	478	\| `query is required` \| `search_docs` was called with an empty `query`. \|
	479	+\| `agents can import only into organizations they or their owner administer` \| `start_github_import` from an agent needs an organization the agent or its owner administers as `owner`, never a user account. \|
	480	+\| `too many repository imports are already running (at most 3 at a time); wait for one to finish` \| Wait for one of the running imports to finish (check with `list_imports`). \|
431	481	\| `no docs page "..."; pages: ...` \| `read_docs` didn't recognize the slug. Pick one from the list in the message, or call `read_docs` with `index`. \|

		@@ -24,7 +24,7 @@
24	24	1. Go to Settings → Agents (`https://diffinery.com/settings/agents`).
25	25	2. Under Create an agent, fill in:
26	26	- Agent username, for example `review-bot`.
27		- - Display name (optional), for example `Review bot`.
	27	+ - Display name (optional), for example `Review bot`. Without one, the agent's username is shown.
28	28	- Owner: yourself, or an organization where you are an owner or admin.
29	29	- Maximum role: the highest role the agent can have on any repository (default `write`).
30	30	3. Click Create agent. You see `Agent created. Create a token for it below.`
		@@ -60,23 +60,27 @@
60	60
61	61	### With the REST API
62	62
63		-```sh
64		-curl -X POST https://diffinery.com/api/v3/diffinery/agents \
65		- -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
66		- -d '{
67		- "login": "review-bot",
68		- "name": "Review bot",
69		- "org": "acme",
70		- "policy": { "maxRole": "write" },
71		- "token": { "scopes": ["write"], "expires_in_days": 90 }
72		- }'
	63	+Creating an agent mints a token, so it needs a browser session: a token gets `403 creating tokens needs a browser session: sign in at https://diffinery.com/settings/tokens`. Send it from a page on diffinery.com while signed in, for example from the browser console:
	64	+
	65	+```js
	66	+await fetch("/api/v3/diffinery/agents", {
	67	+ method: "POST",
	68	+ headers: { "Content-Type": "application/json" },
	69	+ body: JSON.stringify({
	70	+ login: "review-bot",
	71	+ name: "Review bot",
	72	+ org: "acme",
	73	+ policy: { maxRole: "write" },
	74	+ token: { scopes: ["write"], expires_in_days: 90 },
	75	+ }),
	76	+}).then((r) => r.json());
73	77	```
74	78
75	79	The response (`201`) contains the agent (`id`, `login`, `name`, `type: "Bot"`, `html_url`) and its first token (`token`, `id`, `expiresAt`). Leave out `org` to own the agent yourself, `policy.maxRole` for the default `write`, and `token` for a `write` token that lasts 90 days.
76	80
77	81	`token.scopes` (and `scopes` when you create another token) must be a non-empty list of `read`, `write` and `admin`; leaving it out gives `["write"]`. An empty list or an unknown name returns `422 scopes must be a non-empty list of: read, write, admin`.
78	82
79		-The `POST` endpoints below create tokens, so they need a browser session: every token gets `403 creating tokens needs a browser session: sign in at https://diffinery.com/settings/tokens`. `DELETE` also accepts a personal token with the `admin` scope that isn't restricted to repositories.
	83	+The `POST` endpoints below create tokens, so they need a browser session. `DELETE` also accepts a personal token with the `admin` scope that isn't restricted to repositories.
80	84
81	85	\| Endpoint \| Purpose \| Who \|
82	86	\| --- \| --- \| --- \|
		@@ -118,21 +122,27 @@
118	122	\| Rule \| Details \| How to relax it \|
119	123	\| --- \| --- \| --- \|
120	124	\| No pushes to the default branch or protected branches \| Pushes, `commit_files`, the contents API, the git data refs API, the merges API, update-branch and branch updates are refused with `agents may not push to protected or default branches; open a pull request`. \| Tick Allow agents to push directly (`agentsMayPush`) on that branch's protection rule. \|
121		-\| No merges into the default branch or protected branches \| The merge blocker `agents may not merge into this branch; a human must merge`. Agents can't add pull requests to a merge queue or turn on auto-merge there either. \| Tick Allow agents to merge pull requests (`agentsMayMerge`) on the rule, or, so that CI decides instead of the agent, Allow agents to land pull requests through auto-merge (`allowAgentAutoMerge`, see [Agents landing changes](/docs/repositories/branch-protection#agents-landing-changes)). \|
122		-\| Pull requests opened by agents need a human approval \| At least one approval from a person, even on a branch with no protection rule. \| None. \|
	125	+\| No merges into the default branch or protected branches \| The merge blocker `agents may not merge into this branch; a human must merge`. Agents can't add pull requests to a merge queue or turn on auto-merge there either. \| Tick Allow agents to merge pull requests (`agentsMayMerge`) on the rule, or, so that CI decides instead of the agent, Allow agents to land pull requests through auto-merge (`allowAgentAutoMerge`, see [Agents landing changes](/docs/repositories/branch-protection#agents-landing-changes)); the agent then turns on [auto-merge](/docs/collaboration/pull-requests#auto-merge-for-agents-and-workflow-tokens) with `enable_auto_merge` or `PUT /repos/{owner}/{repo}/pulls/{number}/auto-merge`. \|
	126	+\| Pull requests opened by agents need a human approval \| At least one approval from a person, even on a branch with no protection rule. When an agent has Diffinery land its pull request on the default branch or a protected branch through auto-merge or the merge queue, the approval counts only for the commit it approved. \| Only for landings an agent asked for: Let agents' auto-merges land without an approving review (`agentAutoMergeWithoutApproval`), which lets green required checks stand in for the approval. See [Waiving approvals for agents](/docs/repositories/branch-protection#waiving-approvals-for-agents). \|
123	127	\| Agent approvals don't count \| An agent's Approve review is shown but never counts toward required approvals. An agent's Request changes review still blocks. \| None. \|
124	128	\| No branch protection changes \| `agents cannot change branch protection` \| None. \|
125	129	\| No secret management \| Setting or deleting repository or environment secrets fails with `agents cannot manage secrets`, and agents can't use the organization secrets endpoints, whatever their role. \| None. \|
126	130	\| No variable changes \| Creating, changing or deleting repository or environment Actions variables fails with `agents cannot manage variables`, whatever the agent's role. Agents with write or higher can still list and read variables. \| None. \|
127	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. \|
128	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. \|
129		-\| No environment secrets for agent-started runs on open environments \| A job with `environment:` in a run an agent started 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. \|
	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 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. \|
130	135	\| 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. \|
131	136	\| No review dismissal \| Dismissing a review fails with `agents can't dismiss reviews`, whatever the agent's role. \| None. \|
132	137	\| No repository deletion \| `agents cannot delete repositories` \| None. \|
133		-\| No push protection bypass \| Only repository admins who are people can push past secret scanning with `git push -o allow-secrets=<reason>`. \| None. \|
	138	+\| No repository transfers \| `agents and workflow tokens cannot transfer repositories`. Only people move repositories to another owner. \| None. \|
	139	+\| No push protection bypass \| Only repository admins who are people can commit past secret scanning, with `git push -o allow-secrets=<reason>` or `allow_secrets` on `POST /repos/{owner}/{repo}/diffinery/commits`. An agent's push or commit that contains a credential is always refused (and `commit_files` has no bypass at all); see [Push protection](/docs/security/push-protection). \| None. \|
134	140	\| No admin bypass of merge requirements \| Merging past unmet branch rules (`"bypass_rules": true`) or past the merge queue (`"bypass_merge_queue": true`) is for repository admins who are people. An agent's merge with these flags is still refused with the usual blockers. \| None. \|
135	141	\| No creating agents \| `only people can create agents` \| None. \|
	142	+\| Imports from GitHub only into organizations \| An agent can start a GitHub import only into the organization that owns it, or one where its owner is an owner or admin, never into a user account (`agents can import only into organizations they or their owner administer`). Its maximum role must be at least `write`. \| None. \|
	143	+\| No push protection bypass in imports \| An agent's import always stops when old history contains something that looks like a credential, whatever it asks for. \| A person who administers the target starts the import. \|
	144	+\| No variables, secret names or environments in imports \| The import's variables steps are skipped (`skipped (agents cannot manage variables)`). \| A person sets them up after the import. \|
	145	+\| No import retry once the repository exists \| `an agent cannot retry an import after the repository was created; a person must retry it` \| A person starts a new import. \|
136	146
137	147	The default branch is protected from agents even if it has no protection rule. Agents can still push freely to other branches, open pull requests, comment, review, run workflows, report commit statuses and check runs, create releases and start sandboxes, within their role.
138	148
		@@ -178,6 +188,19 @@
178	188	- Audit log: entries for agent actions (pushes, merges and other audited actions) record the owner in `on_behalf_of`. Creating, disabling and enabling agents, and creating agent tokens, are audited (`agent.create`, `agent.disable`, `agent.enable`, `agent.token.create`). See [Audit log](/docs/security/audit-log).
179	189	- Email: the person who creates an agent gets a security email, `A new agent was added: review-bot`, which can't be turned off.
180	190
	191	+## Imports from GitHub
	192	+
	193	+Agents can import a GitHub repository with the `start_github_import` MCP tool (or `POST /api/v3/diffinery/imports`, or `diffinery migrate github` with the agent's token), and follow it with `get_import` and `list_imports`. The import runs on the server and copies the Git history, issues and pull requests with their numbers, comments, reviews, labels, milestones, branch protection and releases. The agent rules:
	194	+
	195	+- The target must be an organization: the one that owns the agent, or one where the agent's owner is an owner or admin.
	196	+- The agent's maximum role must be at least `write`, and its token needs the `write` scope.
	197	+- Push protection is never bypassed: the `secrets` option is always `stop`, so history with something that looks like a credential fails the import instead of being imported.
	198	+- Actions variables, secret names, environments and organization variables are skipped. Agents never read or set secret values.
	199	+- Once the repository exists, the agent can't retry a failed import; a person starts a new one.
	200	+- The agent sees only the imports it started.
	201	+
	202	+Everything the import writes fires no workflows, webhooks or notifications, and the repository is locked against other pushes until the import ends. Imported reviews never count as approvals, so an imported open pull request still needs a fresh human approval. See [Migrate from GitHub](/docs/migrate-from-github#agents-and-imports) and [Imports over MCP](/docs/agents/mcp#imports-over-mcp).
	203	+
181	204	## Disable an agent
182	205
183	206	Disabling an agent revokes all its tokens at once.
		@@ -247,8 +270,9 @@
247	270	## Differences from GitHub
248	271
249	272	- Agents are accounts owned by a person or an organization, rather than GitHub Apps with installations, and authenticate with ordinary `dfy_` tokens.
250		-- Agents are held to built-in guardrails (no pushes or merges to default and protected branches, human approval for their pull requests, agent approvals not counted) that you relax per branch with `agentsMayPush` and `agentsMayMerge`.
	273	+- Agents are held to built-in guardrails (no pushes or merges to default and protected branches, human approval for their pull requests, agent approvals not counted) that you relax per branch with `agentsMayPush`, `agentsMayMerge`, `allowAgentAutoMerge` and `agentAutoMergeWithoutApproval`. The guardrails also hold for workflow runs of code an agent wrote, so an agent can't use a workflow's `GITHUB_TOKEN` to get around them.
251	274	- Commit statuses and check runs reported by agents never satisfy required checks, and agents can't manage environments, secrets or Actions variables, or dismiss reviews.
	275	+- Agents can run GitHub imports, within the import rules above.
252	276	- Commits Diffinery writes for agents carry a `diffinery-agent ... on-behalf-of ...` header.
253	277
254	278	## Troubleshooting
		@@ -261,6 +285,8 @@
261	285	\| `only people can create agents` \| You called the agents API with an agent's token. Use your own. \|
262	286	\| `agents cannot manage secrets` \| A person with admin access must set or delete repository, environment and organization secrets. \|
263	287	\| `agents cannot manage variables` \| A person with admin access must create, change or delete repository and environment variables. \|
	288	+\| A workflow on the agent's branch fails to push to `main` with `agents may not push to protected or default branches; open a pull request` \| The run's code came from an agent, so its job token acts as the agent. Open a pull request from the branch and have a person merge it. \|
	289	+\| `push protection: possible secret detected (...)` from `commit_files` or the commits API \| A file the agent committed looks like a credential. Remove it, or mark a test fixture with `diffinery:allow-secret`. Agents can't bypass push protection. \|
264	290	\| `this token needs the write scope` \| The agent's token has only the `read` scope. Create a `write` token for it. \|
265	291	\| `this token needs the admin scope` \| Creating agents or agent tokens, or disabling an agent, through the API or CLI needs your personal `admin` token. \|
266	292	\| `this token is limited to repositories and can't change account settings` \| Managing agents needs a personal token without a repository list. \|
		@@ -273,4 +299,7 @@
273	299	\| `name already taken` \| Pick another login; agents share the namespace with people and organizations. \|
274	300	\| `not your agent` \| Only the owner, or an owner or admin of the owning organization, can manage it. \|
275	301	\| `repository not found` for a repository you can see \| The agent's owner (or, for an organization agent, the organization) has no access to it. \|
	302	+\| `agents can import only into organizations they or their owner administer` \| Import into an organization that owns the agent or that the agent's owner administers. Agents can't import into user accounts. \|
	303	+\| `this agent's policy does not allow writing; an import needs at least write` \| Raise the agent's Maximum role to `write` or higher. \|
	304	+\| `skipped (agents cannot manage variables)` on an import \| Expected for an agent's import. A person sets variables, environments and secrets afterwards. \|
276	305	\| `invalid, expired or revoked token` \| The token expired or was revoked, or the agent is disabled. Create a new token. \|

		@@ -52,6 +52,7 @@
52	52	"actions/docker",
53	53	"actions/reusable-workflows",
54	54	"actions/secrets-and-variables",
	55	+ "actions/workflow-permissions",
55	56	"actions/environments",
56	57	"actions/oidc",
57	58	"actions/caching-and-artifacts",

		@@ -27,8 +27,9 @@
27	27	- Creating and using a sandbox needs write access to the repository. A `read`-scoped token can't create one.
28	28	- Each call on a sandbox is allowed for the account that created it and for repository admins; anyone else gets `not your sandbox`.
29	29	- Inside the sandbox, git authenticates as the creator, with the role the creator had when the sandbox was created, capped at write (even if the creator is an admin) and at the creator's current role. The sandbox's credentials stop working 24 hours after it starts, when it is closed, or as soon as the creator's account is disabled or loses access to the repository.
	30	+- The sandbox's git credential (a `dst_` token) also lets git clone and fetch other public repositories, for example public submodules, but no other private repository. Use a token of your own inside the sandbox if you need one.
30	31	- Job and sandbox tokens can't create sandboxes (`403 job and sandbox tokens can't start sandboxes`). Pushes from the sandbox follow the same rules as any push: branch protection, push protection (secret scanning) and, for agents, the [agent guardrails](/docs/agents/overview#guardrails). An agent can't push to the default branch from a sandbox either.
31		-- Archived repositories can't have sandboxes.
	32	+- Archived repositories can't have sandboxes: starting one, and every call on an existing one (running commands, reading or writing files, closing it), gets `403 repository is archived (read-only)`. A sandbox left running when its repository is archived stops on its own after 30 idle minutes.
32	33
33	34	## What's inside
34	35

		@@ -31,10 +31,30 @@
31	31
32	32	Re-running a job replaces the check of the same name on the same commit. Check runs from Actions can't be changed over the REST API: a `PATCH` fails with `check runs from Diffinery Actions can't be changed over the API`.
33	33
	34	+A job's `check_run_url` (in `GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs` and `GET /repos/{owner}/{repo}/actions/jobs/{job_id}`) is `https://diffinery.com/api/v3/repos/acme/website/check-runs/{job_id}`. `GET` on it returns the check run that job reports (its latest one, after a re-run), so tools that follow `check_run_url` from a job to its check run work as on GitHub.
	35	+
34	36	> Note: GitHub names an Actions check run after the job only. In Diffinery the name includes the workflow name, so required check names copied from GitHub usually need the `<workflow> / ` prefix.
35	37
36		-The job's own `GITHUB_TOKEN` is read-only on the REST API, so a step can't post extra statuses or check runs with it. If a workflow needs to report something beyond its job checks, store a personal token with the `write` scope as a secret and use that.
	38	+A step can also report with the job's own `GITHUB_TOKEN`, within the job's `permissions:`:
37	39
	40	+- Commit statuses need `statuses: write`. They are reported by `diffinery-actions[bot]` and count toward required checks like any other non-agent report (in a run whose code came from an agent, the token acts as an agent, and its statuses don't count).
	41	+- Check runs can't be created with the job token: `POST .../check-runs` fails with `this account can't report check runs`. Report a commit status instead, or use a personal token with the `write` scope stored as a secret.
	42	+
	43	+```yaml
	44	+permissions:
	45	+ contents: read
	46	+ statuses: write
	47	+steps:
	48	+ - run: \|
	49	+ curl -sS -X POST -H "Authorization: Bearer $GITHUB_TOKEN" -H "Content-Type: application/json" \
	50	+ "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \
	51	+ -d '{"state": "success", "context": "lighthouse", "description": "Score 98"}'
	52	+ env:
	53	+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	54	+```
	55	+
	56	+Without `statuses: write`, the request fails with `403` and `Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: statuses: write)`.
	57	+
38	58	## Report results from external CI
39	59
40	60	An external CI system (or any script or bot) reports results with a token for an account that has the write role on the repository. A personal access token with the `write` scope works. For results that should satisfy required checks, use a regular account, not an agent: reports from agents never satisfy required checks (see [Agents and checks](#agents-and-checks)).
		@@ -304,7 +324,7 @@
304	324	- Binding only affects names listed in `requiredChecks`.
305	325	- Binding a check to an agent's login means it can never pass, because agent reports are ignored.
306	326
307		-> Important: `requiredCheckSources` can only be set through the API, and the Branch protection settings page does not show it. Saving the rule from that page writes the rule without `requiredCheckSources`, which removes the bindings. Set them again with the API after editing the rule in the web UI.
	327	+`requiredCheckSources` can only be set through the API, and the Branch protection settings page does not show it. Saving the rule from that page keeps the bindings of every check that is still listed in Required status checks (also when you rename the rule's pattern). A binding for a check you removed from the list is dropped; add the check back with the API, binding included.
308	328
309	329	### Required checks and the merge queue
310	330
		@@ -351,7 +371,7 @@
351	371	\| Check suites can be created and re-requested \| Check suites are derived from check runs and read-only. \|
352	372	\| Status descriptions are limited to 140 characters \| Up to 1,024 characters are kept. \|
353	373	\| `required_status_checks` with an app id restricts who can satisfy a check \| `requiredCheckSources` binds a check name to a login or to `diffinery-actions`; when Actions reports a name, it alone decides that check even without a binding. \|
354		-\| Statuses and check runs can be posted with the workflow's `GITHUB_TOKEN` \| The job token is read-only on the REST API. \|
	374	+\| Statuses and check runs can be posted with the workflow's `GITHUB_TOKEN` \| Statuses can (with `statuses: write`); check runs can't. \|
355	375	\| `check_run` and `check_suite` webhook events \| Not sent. Commit statuses send `status` events. \|
356	376	\| Agents don't exist \| Reports from agents never decide a required check. \|
357	377
		@@ -361,8 +381,10 @@
361	381	\|---\|---\|
362	382	\| `required check '<name>' has not run` \| No report with exactly that name on the head commit, or only reports that don't count (from agents, from Actions-overridden reporters, or from someone other than the bound source). Compare the name with the Checks tab, including the `<workflow> / ` prefix for Actions jobs. \|
363	383	\| A passing external status is ignored \| Actions also reports a check with that name, and Actions wins; or `requiredCheckSources` binds the name to a different login; or the reporter is an agent. Rename your context or fix the binding. \|
364		-\| Bindings disappeared \| The rule was saved from the Branch protection settings page, which drops `requiredCheckSources`. Set them again with the API. \|
365		-\| `write access required` \| The token's account lacks the write role, or the request used a workflow's `GITHUB_TOKEN`, which is always read-only here. \|
	384	+\| Bindings disappeared \| The check was removed from Required status checks when the rule was saved from the Branch protection settings page, which drops the binding of a check that is no longer required. Set it again with the API. \|
	385	+\| `write access required` \| The token's account lacks the write role, or a workflow's `GITHUB_TOKEN` has no write permission at all (for example `permissions: read-all`). \|
	386	+\| `Resource not accessible by integration (...)` \| A workflow's `GITHUB_TOKEN` lacks the permission named in the message. Add `statuses: write` to the job's `permissions:` to post statuses. \|
	387	+\| `this account can't report check runs` \| Check runs can't be created with a workflow's `GITHUB_TOKEN`. Post a commit status, or use a personal token. \|
366	388	\| `this token needs the write scope` \| The token has only the `read` scope. Use a token with the `write` scope. \|
367	389	\| `only the app that created a check run can update it` \| Update the check run with the same account (any of its tokens) that created it. \|
368	390	\| `check runs from Diffinery Actions can't be changed over the API` \| Re-run the job instead. \|

		@@ -1,6 +1,6 @@
1	1	---
2	2	title: Issues
3		-description: Open, discuss, label, assign, lock, react to, close and search issues in the web UI, the CLI, the REST API and over MCP.
	3	+description: Open, discuss, label, assign, lock, react to, close and search issues, and group them in milestones, in the web UI, the CLI, the REST API and over MCP.
4	4	---
5	5
6	6	Issues track bugs, tasks and ideas for a repository. Each issue has a title, a Markdown description, a conversation, labels, assignees and an open or closed state, and you can work with them from the web UI, the `diffinery` CLI, the REST API or an MCP client.
		@@ -34,16 +34,19 @@
34	34	\| Set labels and assignees with `PATCH .../issues/{number}` \| The issue's author, or triage or higher \|
35	35	\| Add or remove labels and assignees with the label and assignee endpoints \| Triage or higher \|
36	36	\| Create, rename, recolor and delete labels \| Triage or higher \|
	37	+\| Create, edit and close milestones, and set an issue's milestone \| Triage or higher \|
37	38	\| Edit or delete a comment \| The comment's author, or maintain or higher \|
38	39	\| Lock and unlock a conversation \| Triage or higher \|
39	40	\| Comment or react on a locked issue \| Triage or higher \|
40	41	\| Add a reaction \| Anyone signed in who can read the repository (with a `write` or `admin` token through the API) \|
41	42	\| Delete a reaction \| The person who added it, or admin \|
42	43
43		-When you open an issue through the API or MCP, the `labels` and `assignees` you send are applied whatever your role; the web form only offers labels to triage or higher.
	44	+When you open an issue, the `labels` and `assignees` you send are applied only if you have triage access or higher. Without it they are silently dropped and the issue is created without them, as on GitHub: the request still succeeds with `201`. This applies to the REST API, the CLI (`--label`, `--assignee`) and the MCP `create_issue` tool; the web form only offers labels to triage or higher. Editing works the same way: when the issue's author (or anyone else) without triage access sends `labels` or `assignees` with `PATCH .../issues/{number}`, they are dropped too, and the rest of the edit is applied.
44	45
45		-In an archived repository the web UI shows issues read-only and has no forms to change them, and the label, assignee, lock, reaction and comment deletion endpoints refuse changes with `403` and `repository is archived (read-only)`. The REST endpoints that open and edit issues and add or edit comments (`POST` and `PATCH .../issues`, `POST .../issues/{number}/comments`, `PATCH .../issues/comments/{id}`) and the MCP `create_issue` tool don't check the archived state and still accept changes.
	46	+In an archived repository every change is refused, whatever your role: opening and editing issues, comments, labels, assignees, locks and reactions, through the web UI, the REST API, the CLI and MCP, all fail with `403` and `repository is archived (read-only)`. The web UI shows issues read-only. Subscribing to an issue and watching the repository still work.
46	47
	48	+A workflow's `GITHUB_TOKEN` can work with issues within its `permissions:`: opening an issue (`POST .../issues`) needs `issues: write`, and comments, labels, assignees and reactions on an issue accept `issues: write` or `pull-requests: write`. Without them the request fails with `403` and `Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: issues: write)`. A job token acts with at most the write role, so it can set labels and assignees when it opens an issue.
	49	+
47	50	## Open an issue
48	51
49	52	### Open an issue in the web UI
		@@ -209,6 +212,73 @@
209	212
210	213	Logins are not checked when you assign them, so check the spelling. `GET /repos/{owner}/{repo}/assignees` lists the accounts GitHub clients offer as assignees: the repository's direct collaborators with triage or higher, plus the owner of a personal repository. `GET /repos/{owner}/{repo}/assignees/{login}` answers `204` for those accounts and `404` otherwise; it doesn't stop you from assigning anyone else.
211	214
	215	+## Milestones
	216	+
	217	+A milestone groups issues and pull requests that belong to one goal, such as a release, with an optional due date. Each issue or pull request has at most one milestone. Milestones have their own numbers in each repository, starting at 1; milestones brought in by a [GitHub import](/docs/migrate-from-github) keep their GitHub numbers, and new ones are numbered after them.
	218	+
	219	+You create and edit milestones with the REST API (there's no web page, CLI command or MCP tool for them yet) and set an issue's milestone in the web UI or with the REST API. Creating, editing and setting milestones needs triage or higher and a token with the `write` scope; anyone who can read the repository can read them.
	220	+
	221	+### Milestone fields
	222	+
	223	+\| Field \| Description \|
	224	+\| --- \| --- \|
	225	+\| `number` (also `id`) \| The milestone's number in the repository \|
	226	+\| `title` \| 1 to 255 characters; required when you create a milestone \|
	227	+\| `description` \| Text up to 65,536 characters; empty by default \|
	228	+\| `state` \| `open` or `closed`. New milestones are always `open`. \|
	229	+\| `due_on` \| An ISO 8601 timestamp, or `null` for no due date. It's stored in UTC. \|
	230	+\| `creator` \| `{"login": "..."}` of the account that created it \|
	231	+\| `open_issues`, `closed_issues` \| How many open and closed issues and pull requests have this milestone (merged pull requests count as closed) \|
	232	+\| `created_at`, `updated_at`, `closed_at` \| Timestamps; `closed_at` is set when the milestone is closed and cleared when it's reopened \|
	233	+
	234	+### Create and edit milestones with the REST API
	235	+
	236	+\| Request \| Needs \| Does \|
	237	+\| --- \| --- \| --- \|
	238	+\| `GET /repos/{owner}/{repo}/milestones` \| read \| Lists milestones. `state` is `open` (default), `closed` or `all`. Sorted by due date (milestones without one last), then by number. The list isn't paged. \|
	239	+\| `GET /repos/{owner}/{repo}/milestones/{number}` \| read \| One milestone, or `404 milestone not found` \|
	240	+\| `POST /repos/{owner}/{repo}/milestones` \| triage \| Creates a milestone from `title`, `description` and `due_on`; returns `201` with the milestone. A `state` in the body is ignored. \|
	241	+\| `PATCH /repos/{owner}/{repo}/milestones/{number}` \| triage \| Changes any of `title`, `description`, `state` and `due_on` (`null` removes the due date); returns the milestone \|
	242	+
	243	+```sh
	244	+# Create a milestone
	245	+curl -X POST https://diffinery.com/api/v3/repos/acme/website/milestones \
	246	+ -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
	247	+ -d '{"title": "v2.0", "description": "Pricing page redesign", "due_on": "2026-12-01T00:00:00Z"}'
	248	+
	249	+# Close it
	250	+curl -X PATCH https://diffinery.com/api/v3/repos/acme/website/milestones/1 \
	251	+ -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
	252	+ -d '{"state": "closed"}'
	253	+
	254	+# List every milestone, open and closed
	255	+curl "https://diffinery.com/api/v3/repos/acme/website/milestones?state=all" \
	256	+ -H "Authorization: Bearer dfy_..."
	257	+```
	258	+
	259	+Milestones can't be deleted; close one you no longer use. To clear a description, send `"description": ""` (`null` leaves it unchanged).
	260	+
	261	+### Set the milestone of an issue or pull request
	262	+
	263	+- Web UI (triage or higher): the sidebar of an issue or pull request has a Milestone section showing the milestone's title, a `closed` badge if it's closed and its due date, or No milestone. Click Set milestone, choose a milestone in the Milestone list (it offers the open milestones and No milestone), and click Save. Set milestone appears only when the repository has an open milestone or the issue already has one.
	264	+- REST API (triage or higher): send `milestone` with the milestone's number, or `null` to remove it, on `PATCH /repos/{owner}/{repo}/issues/{number}`. This works for pull request numbers too, and also accepts closed milestones.
	265	+
	266	+```sh
	267	+curl -X PATCH https://diffinery.com/api/v3/repos/acme/website/issues/12 \
	268	+ -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
	269	+ -d '{"milestone": 1}'
	270	+```
	271	+
	272	+Issues and pull requests returned by the REST API carry a `milestone` object (`number`, `id`, `title`, `state`, `due_on`, `url`; `description` is always `null` there), or `null`. Things to know about setting it with `PATCH`:
	273	+
	274	+- The response shows the issue as it was before the milestone changed. Read the issue again (`GET .../issues/{number}`) to see the new milestone.
	275	+- The other fields in the same request are saved first. If you're the issue's author without triage access, or the milestone doesn't exist, the title, body, state, labels and assignees you sent are saved and the request then fails with `403 triage access required` or `404 milestone not found`. Send `milestone` in a request of its own.
	276	+- A value that isn't a whole number or `null` fails with `422 milestone must be a milestone number or null`, and nothing is saved.
	277	+
	278	+A workflow's `GITHUB_TOKEN` needs `issues: write` or `pull-requests: write` to create, edit or set milestones.
	279	+
	280	+Setting or changing a milestone doesn't create an event in the timeline, doesn't send a webhook or a notification, and there are no `milestone` webhook events. You can't filter issue lists or searches by milestone yet: `milestone` on `GET .../issues` is ignored, and `milestone:` in a search is searched as text.
	281	+
212	282	## Comments
213	283
214	284	### Add a comment
		@@ -330,7 +400,7 @@
330	400	\| `review_requested`, `review_request_removed` \| `requested_reviewer`, `review_requester` \|
331	401	\| `review_dismissed` \| `dismissed_review` (`state`, `review_id`, `dismissal_message`) \|
332	402	\| `merged` \| `commit_id` \|
333		-\| `ready_for_review`, `converted_to_draft` \| none; pull requests only (see [Pull requests](/docs/collaboration/pull-requests)) \|
	403	+\| `ready_for_review`, `convert_to_draft` \| none; pull requests only (see [Pull requests](/docs/collaboration/pull-requests#drafts)). The matching webhook actions are `ready_for_review` and `converted_to_draft`. \|
334	404
335	405	Every event also has `id`, `actor`, `event`, `created_at`, `commit_id` and `commit_url`.
336	406
		@@ -499,7 +569,8 @@
499	569
500	570	- An issue's `id` is its number; issues are addressed by number only.
501	571	- `/search/issues` covers at most 50 repositories per search and ignores qualifiers it doesn't know (they are searched as text). `review-requested:`, `mentions:`, `commenter:`, `milestone:`, `linked:` and `reactions:` are not supported.
502		-- There are no milestones, issue types, issue templates, transfers or pinned issues.
	572	+- There are no issue types, issue templates, transfers or pinned issues.
	573	+- Milestones are created and edited through the REST API only, can't be deleted, and have no events, webhooks or list filters. See [Milestones](#milestones).
503	574	- Deleting a label in the web UI keeps its name on issues; deleting it through the API removes it from them.
504	575	- Locking, reactions, events and comment deletion are available through the REST API only, not in the web UI.
505	576	- `GET /repos/{owner}/{repo}/assignees` lists direct collaborators only, not organization members.
		@@ -512,11 +583,21 @@
512	583	\| `title is required` \| The title was empty. Give the issue a title. \|
513	584	\| `body is required` \| You posted an empty comment. \|
514	585	\| `permission denied` \| You tried to edit, close or reopen someone else's issue without triage access, or edit someone else's comment without maintain access. \|
515		-\| `triage access required` \| Creating, changing or deleting labels, setting labels and assignees in the web UI, and the issue label, assignee and lock endpoints need triage or higher. \|
	586	+\| `triage access required` \| Creating, changing or deleting labels, setting labels and assignees in the web UI, the issue label, assignee and lock endpoints, and creating, editing and setting milestones need triage or higher. \|
516	587	\| `#12 not found` \| There is no issue or pull request with that number. \|
517	588	\| `conversation is locked` \| The issue is locked. Only triage or higher can comment or react. \|
518	589	\| `a label with this name already exists` \| Use `PATCH /labels/{name}` to change an existing label. \|
	590	+\| `milestone not found` \| There is no milestone with that number. List them with `GET .../milestones?state=all`. \|
	591	+\| `title is required`, `title must be 1 to 255 characters` \| A new milestone needs a title, and a milestone title can't be blank or longer than 255 characters. \|
	592	+\| `due_on must be an ISO 8601 timestamp` \| Send a date such as `2026-12-01T00:00:00Z`, or `null`. \|
	593	+\| `state must be open or closed`, `state must be open, closed or all` \| Use one of the listed values for a milestone's `state`, or for the `state` filter when listing milestones. \|
	594	+\| `description must be a string` \| A milestone description must be text of at most 65,536 characters. \|
	595	+\| `milestone must be a milestone number or null` \| `PATCH .../issues/{number}` takes the milestone's number, not its title. \|
	596	+\| The milestone didn't change in the `PATCH` response \| The response shows the issue before the milestone changed. Read the issue again. \|
519	597	\| `incomplete_results: true` in a search \| You can read more than 50 repositories. Add `repo:`, `user:` or `org:` to the query. \|
520	598	\| `repository not found` \| The repository doesn't exist, or your account or token can't see it (private repositories return 404). \|
521	599	\| `authentication required` \| You called the API without a token, either on a private repository or to change something (open an issue, comment, react) on a public one. Send `Authorization: Bearer dfy_...`. \|
522	600	\| `this token needs the write scope` \| Your token has only the `read` scope, which can't open issues, comment or react. Create a token with the `write` scope. \|
	601	+\| The new issue has no labels or assignees \| You don't have triage access, so the `labels` and `assignees` you sent were dropped. Ask someone with triage access to add them. \|
	602	+\| `repository is archived (read-only)` \| The repository is archived. An admin must unarchive it before issues can change. \|
	603	+\| `Resource not accessible by integration (...)` \| A workflow's `GITHUB_TOKEN` lacks the permission named in the message. Add `issues: write` to the job's `permissions:`. \|

		@@ -119,7 +119,7 @@
119	119
120	120	## Add a pull request to the queue
121	121
122		-The pull request must have no merge blockers: approvals, required checks on its head, no conflicts, not a draft (mark a draft ready first with Ready for review or `diffinery pr ready 12`; see [Drafts](/docs/collaboration/pull-requests#drafts)). You need write access, and through the API a token with the `write` scope. Agents (and workflow tokens) can queue a pull request into the default branch or a protected one only when its rule has Allow agents to land pull requests through auto-merge and at least one required check, or, for agents, Allow agents to merge pull requests. An agent can also turn on auto-merge, which adds the pull request to the queue once it is ready (see [Agents landing changes](/docs/repositories/branch-protection#agents-landing-changes)).
	122	+The pull request must have no merge blockers: approvals, required checks on its head, no conflicts, not a draft (mark a draft ready first with Ready for review or `diffinery pr ready 12`; see [Drafts](/docs/collaboration/pull-requests#drafts)). You need write access, and through the API a token with the `write` scope. Agents (and workflow tokens) can queue a pull request into the default branch or a protected one only when its rule has Allow agents to land pull requests through auto-merge and at least one required check, or, for agents, Allow agents to merge pull requests. To queue a pull request that isn't ready yet, turn on [auto-merge](/docs/collaboration/pull-requests#auto-merge): it adds the pull request to the queue by itself once it has no blockers, with the auto-merge method (by default the queue's). Agents use it the same way (see [Agents landing changes](/docs/repositories/branch-protection#agents-landing-changes)).
123	123
124	124	### Queue in the web UI
125	125
		@@ -276,14 +276,24 @@
276	276
277	277	## Bypass the queue
278	278
279		-A repository admin who is a person can merge a pull request directly, skipping the queue, when it has no conflicts, isn't a draft, and the rule doesn't have Do not allow administrators to bypass these rules. Through a token, that needs the `admin` scope. The bypass must be asked for explicitly:
	279	+A repository admin who is a person can merge a pull request directly, skipping the queue, when it has no conflicts, isn't a draft, and the rule doesn't have Do not allow administrators to bypass these rules. Through a token, that needs the `admin` scope. The bypass must be asked for explicitly, and it skips only the queue:
280	280
281		-- Web UI: Merge now (bypass the queue), which asks `Merge directly, bypassing the merge queue?` first. It merges with the queue's merge method. When the pull request doesn't meet the rules, the button reads Merge now (bypass the queue and the unmet requirements) instead and also sends `bypass_rules`; the bypass is audited as `pull_request.merge_bypassed`.
282		-- CLI: `diffinery pr merge 12 --admin`. It sends `bypass_merge_queue` and `bypass_rules`, so the CLI doesn't fall back to queueing the pull request.
283		-- REST API: `PUT /repos/{owner}/{repo}/pulls/{number}/merge` with `"bypass_merge_queue": true`. `"bypass_rules": true` alone doesn't skip the queue.
	281	+\| Request \| Effect \|
	282	+\| --- \| --- \|
	283	+\| `"bypass_merge_queue": true` \| Merges directly instead of queueing. The pull request must still meet its branch rules (approvals, required checks on its head, linear history); otherwise the merge fails with `405` and `pull request is not mergeable: ...`. \|
	284	+\| `"bypass_rules": true` \| Skips unmet branch rules, but not the queue: alone, it still gets `main requires a merge queue: add the pull request to the queue`. \|
	285	+\| Both \| Merges directly even with unmet branch rules. \|
284	286
285		-Skipping the queue also skips the pull request's unmet branch rules (missing approvals, required checks, linear history), as with an [admin bypass](/docs/collaboration/pull-requests#admin-bypass). When the pull request had unmet blockers, the merge is recorded in the [audit log](/docs/security/audit-log#git-and-pull-requests) as `pull_request.merge_bypassed`.
	287	+How to ask for it:
286	288
	289	+- Web UI: Merge now (bypass the queue) under Merge when ready, which asks `Merge directly, bypassing the merge queue?` first. It merges with the queue's merge method. When the pull request doesn't meet the rules, the button reads Merge now (bypass the queue and the unmet requirements) instead and also sends `bypass_rules`. The button isn't shown when the rule has Do not allow administrators to bypass these rules.
	290	+- CLI: `diffinery pr merge 12 --admin`. It sends `bypass_merge_queue` and `bypass_rules`, so it skips both the queue and unmet rules, and the CLI doesn't fall back to queueing the pull request.
	291	+- REST API: `PUT /repos/{owner}/{repo}/pulls/{number}/merge` with `"bypass_merge_queue": true`, plus `"bypass_rules": true` when the pull request has unmet rules.
	292	+
	293	+A direct merge with the `merge` method on a branch that requires linear history also needs `bypass_rules`; otherwise it fails with `main requires linear history; use squash or rebase`.
	294	+
	295	+Every merge that skipped the queue is recorded in the [audit log](/docs/security/audit-log#git-and-pull-requests) as `pull_request.merge_bypassed`, with `merge queue` in the detail's `blockers`, together with any unmet rules skipped with `bypass_rules` (and `linear history required` for a merge commit on a linear-history branch). See [Admin bypass](/docs/collaboration/pull-requests#admin-bypass).
	296	+
287	297	Everyone else gets `main requires a merge queue: add the pull request to the queue` (`405`) from a direct merge; an admin who could bypass sees `(or, as an admin, bypass the queue with bypass_merge_queue)` added to it. A bypass moves the base branch, so the queued groups are rebuilt.
288	298
289	299	## Differences from GitHub
		@@ -302,6 +312,7 @@
302	312	\| `main does not use a merge queue; merge the pull request directly` \| The base branch's rule doesn't have Require a merge queue. Merge normally. \|
303	313	\| `pull request cannot be added to the merge queue: ...` \| The pull request has merge blockers, listed after the colon. Fix them first. \|
304	314	\| `main requires linear history; use squash or rebase` \| Pick `squash` or `rebase`, or change the queue's method. \|
	315	+\| Merge now (bypass the queue) fails with `pull request is not mergeable: ... (as an admin you can bypass with bypass_rules)` \| Skipping the queue doesn't skip unmet rules. Meet them, or merge with `diffinery pr merge 12 --admin` (or the API with both `bypass_merge_queue` and `bypass_rules`). \|
305	316	\| `the pull request left the merge queue: ...` (web UI) \| It joined and was removed in the same step, for example because it conflicts with the groups ahead. \|
306	317	\| `merge queue branches are read-only` \| You pushed to a `gh-readonly-queue/` branch. Push to the pull request's branch instead. \|
307	318	\| The group waits until the timeout \| The required check names don't match what the workflow reports, or the workflow has no `merge_group` trigger. Compare Required status checks with the check names on the merge group commit. \|

		@@ -29,7 +29,7 @@
29	29	\| React to a release \| read (signed in) \|
30	30
31	31	- With a personal access token, the token needs the `write` scope (or `admin`) to create or change releases. A `read` token can list and download.
32		-- A workflow's `GITHUB_TOKEN` (the job token) is read-only on the REST API, whatever the workflow's `permissions` say, so it can read releases but not create them or upload assets. Store a personal or agent token with the `write` scope as an Actions secret and use that instead.
	32	+- A workflow's `GITHUB_TOKEN` (the job token) can create, edit and delete releases and upload assets when the job has `contents: write`, as on GitHub. With only `contents: read` (the default for new repositories) it can read releases, and a write fails with `403` and `Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: contents: write)`. Releases a job token creates or changes don't start `on: release` workflows (see [Workflows triggered by releases](#workflows-triggered-by-releases)).
33	33	- On an archived repository, every release change (including assets) fails with `repository is archived (read-only)`.
34	34	- Deleting a release never deletes its tag. Moving or deleting an existing tag needs the maintain role.
35	35
		@@ -420,6 +420,8 @@
420	420	on:
421	421	release:
422	422	types: [published]
	423	+permissions:
	424	+ contents: write
423	425	jobs:
424	426	build:
425	427	runs-on: ubuntu-latest
		@@ -428,7 +430,7 @@
428	430	- run: ./build.sh "${{ github.event.release.tag_name }}"
429	431	- name: Attach the build to the release
430	432	env:
431		- TOKEN: ${{ secrets.RELEASE_TOKEN }}
	433	+ TOKEN: ${{ secrets.GITHUB_TOKEN }}
432	434	run: \|
433	435	curl -fsS -X POST \
434	436	-H "Authorization: Bearer $TOKEN" \
		@@ -437,7 +439,7 @@
437	439	"https://diffinery.com/api/uploads/repos/${{ github.repository }}/releases/${{ github.event.release.id }}/assets?name=website.tar.gz"
438	440	```
439	441
440		-`RELEASE_TOKEN` is a personal or agent token with the `write` scope, stored as an Actions secret: the job's own `GITHUB_TOKEN` can't upload assets.
	442	+The job's own `GITHUB_TOKEN` uploads the asset, which needs `contents: write` (set above for the whole workflow). Uploads go to the release's `upload_url`, under `/api/uploads/repos/...` (GitHub's `uploads.github.com`). To use a personal or agent token instead, store it as an Actions secret and put it in `TOKEN`.
441	443
442	444	### Activity types
443	445
		@@ -456,7 +458,7 @@
456	458	- Without `types`, every activity type starts the workflow. Creating a published release sends `created`, `published` and `released` (or `prereleased`), so a workflow without `types` runs three times. Use `types: [published]` for "run once per new release".
457	459	- Changes to drafts (creating, editing or deleting a draft) never start workflows. They do send webhooks.
458	460	- The workflow only runs when the release's tag exists.
459		-- Releases created or changed with a job's `GITHUB_TOKEN` don't start workflows (the job token can't change releases anyway). Releases made with a personal or agent token do.
	461	+- Releases created or changed with a job's `GITHUB_TOKEN` don't start workflows, so a workflow can't trigger itself in a loop. Releases made with a personal or agent token do.
460	462
461	463	### The event payload
462	464
		@@ -466,7 +468,7 @@
466	468	\|---\|---\|
467	469	\| `action` \| The activity type, for example `published` \|
468	470	\| `release` \| The release, in the same shape as the REST API (`id`, `tag_name`, `name`, `body`, `draft`, `prerelease`, `assets`, `upload_url`, `html_url`, `author`, ...) \|
469		-\| `repository` \| `id`, `node_id`, `name`, `full_name`, `owner.login`, `default_branch`, `html_url`, `clone_url` \|
	471	+\| `repository` \| GitHub's full repository object, as `GET /repos/{owner}/{repo}` returns it: `id`, `name`, `full_name`, `owner`, `private` and `visibility` (the repository's real visibility), `default_branch`, `html_url`, `clone_url`, the API URLs and so on \|
470	472	\| `sender` \| `login` and `type` (`User` or `Bot`) of who caused the event \|
471	473
472	474	## Release webhooks
		@@ -502,7 +504,8 @@
502	504	\| `'<tag>' is not a valid tag name` \| The tag isn't a valid git ref name (for example it contains spaces, `..` or ends with `.lock`). \|
503	505	\| `target_commitish '<x>' does not exist` \| The branch, tag or SHA for the new tag doesn't exist in the repository. `generate-notes` reports it as `target_commitish does not exist`. \|
504	506	\| `tag was created concurrently; retry` \| Someone created the tag at the same moment. Send the request again. \|
505		-\| `write access required` \| Your role is below write, or the request used a workflow's `GITHUB_TOKEN`, which is always read-only here. Use a stored personal or agent token. \|
	507	+\| `write access required` \| Your role is below write, or the request used a workflow's `GITHUB_TOKEN` without any write permission. \|
	508	+\| `Resource not accessible by integration (...)` \| A workflow's `GITHUB_TOKEN` lacks `contents: write`. Add it to the job's or workflow's `permissions:`. \|
506	509	\| `this token needs the write scope` \| Your token has only the `read` scope. \|
507	510	\| `release not found` \| Wrong id, or the release is a draft and you can't write to the repository. \|
508	511	\| `no published releases` \| `/releases/latest` with no published full release. Publish one, or mark one as latest. \|

		@@ -23,11 +23,11 @@
23	23
24	24	\| Organization role \| Role on the organization's repositories \|
25	25	\| --- \| --- \|
26		-\| member \| write \|
	26	+\| member \| The organization's base permission: `none`, `read`, `write` or `admin` \|
27	27	\| admin \| admin \|
28	28	\| owner \| admin, plus managing owners and renaming the organization \|
29	29
30		-Unlike GitHub, there are no teams and no custom roles. To give someone access to a single repository, add them as a collaborator on it instead. See [Organizations](/docs/accounts/organizations).
	30	+The base permission is a setting of the organization, as on GitHub: new organizations start with `read`, and owners change it on the organization's Settings tab. A member who creates a repository in the organization gets `admin` on it. Unlike GitHub, there are no teams and no custom roles. To give someone more access to a single repository, add them as a collaborator on it. See [Organizations](/docs/accounts/organizations) and [Base permission](/docs/accounts/organizations#base-permission).
31	31
32	32	### Agents
33	33
		@@ -37,22 +37,30 @@
37	37
38	38	- An agent never has more access than its owner. An organization's agent can reach only that organization's repositories.
39	39	- Its maximum role is `write` unless its owner chooses otherwise.
40		-- It can't push to, or merge into, the default branch or a protected branch, unless a branch protection rule explicitly allows it.
	40	+- It can't push to, or merge into, the default branch or a protected branch, unless a branch protection rule explicitly allows it. A rule can instead let it turn on auto-merge, so Diffinery merges its pull request once the required checks pass and a person approves (or, if an admin waives that, on green checks alone).
41	41	- A pull request it opens needs at least one approval from a person, and its own approvals never count.
42		-- It can't change branch protection, add, change or delete secrets or variables (repository, organization or environment), create, change or delete environments, dismiss reviews, delete repositories or bypass push protection.
	42	+- It can't change branch protection, add, change or delete secrets or variables (repository, organization or environment), create, change or delete environments, dismiss reviews, delete or transfer repositories, or bypass push protection.
43	43	- Commit statuses and check runs it reports never satisfy a required check, and tags it pushes never match an environment's tag rules.
44	44	- Commits it makes carry a `diffinery-agent` header naming the agent and the person it acts for.
	45	+- A workflow run whose code came from an agent (the agent triggered it, pushed the branch last, or opened the pull request, and re-runs and `workflow_run` followers of such a run) acts as the agent, so a workflow can't carry agent-written code past these rules.
	46	+- It can import from GitHub only into an organization it or its owner administers, its imports never bypass push protection, and they skip variables, secret names and environments.
45	47
46	48	Agents work through the [MCP server](/docs/agents/mcp), the REST API, the CLI and Git. See [Agents](/docs/agents/overview).
47	49
	50	+### People imported from GitHub
	51	+
	52	+When you [import from GitHub](/docs/migrate-from-github), no accounts are created. A GitHub user whose GitHub account is linked to a Diffinery account (under Settings → Linked accounts, matched by GitHub's numeric user id) is credited to that account. Everyone else becomes a mannequin: a placeholder that carries their issues, comments and reviews under their GitHub login, with a GitHub badge in the web UI and `"type": "Mannequin"` and a `github:<login>` login in the API. A mannequin isn't an account: it can't sign in or act. Imported reviews, whoever wrote them, are history and never count as approvals. See [People: linked accounts and mannequins](/docs/migrate-from-github#people-linked-accounts-and-mannequins).
	53	+
48	54	## Repositories
49	55
50	56	A repository holds a project's Git history plus its issues, pull requests, reviews, checks, releases, deployment environments, workflow runs, webhooks, secrets and variables. It lives at `https://diffinery.com/<owner>/<name>` (for example `https://diffinery.com/acme/website`) and is cloned from the same URL with `.git` appended.
51	57
52	58	New repositories are private and use `main` as the default branch unless you choose otherwise.
53	59
54		-To move a repository from GitHub, `diffinery migrate github` copies its branches, tags, default branch and variables, and optionally its labels, issues, comments and open pull requests. See [Migrate from GitHub](/docs/migrate-from-github).
	60	+A repository can be renamed, or transferred to your own account or to an organization you own or administer. Its old URLs keep working, as on GitHub: web pages and the REST API redirect, and Git, MCP and container images are served under the old name, for anyone who can still read it.
55	61
	62	+To move from GitHub, the server-side importer copies a repository, or every repository of an organization, with its history, issues and pull requests (keeping their numbers), comments, reviews, labels, milestones, releases, branch protection, variables and environments. Secret values are never copied, only their names. Start it from Settings → Imports, `diffinery migrate github`, the REST API or MCP. See [Migrate from GitHub](/docs/migrate-from-github).
	63	+
56	64	There is no forking. Pull requests are always between two branches of the same repository, so contributors need write access to push a branch.
57	65
58	66	Repositories can carry topics, and any branch, tag or commit can be downloaded as a `.zip` or `.tar.gz` source archive. Code is shown with syntax highlighting.
		@@ -65,10 +73,10 @@
65	73
66	74	\| Visibility \| Who can see it \|
67	75	\| --- \| --- \|
68		-\| Private \| The owner, organization members (for organization repositories), collaborators and site administrators \|
	76	+\| Private \| The owner, organization members (for organization repositories, unless the organization's base permission is `none`), collaborators and site administrators \|
69	77	\| Public \| Everyone, including people who aren't signed in. Signed-in users get `read`. \|
70	78
71		-Someone without access to a private repository gets `404 repository not found`, never `403`, so its name isn't revealed. Writing to a public repository still needs a signed-in account (or a token) with a role that allows it. People who aren't signed in can only read: opening an issue, commenting, reacting or pushing without an account fails with `401 authentication required`. See [Visibility](/docs/repositories/overview#visibility).
	79	+Someone without access to a private repository gets `404 repository not found`, never `403`, so its name isn't revealed. Writing to a public repository still needs a signed-in account (or a token) with a role that allows it. People who aren't signed in can only read: opening an issue, commenting, reacting or pushing without an account fails with `401 authentication required` (for a push, Git then asks for your token). See [Visibility](/docs/repositories/overview#visibility).
72	80
73	81	## Roles
74	82
		@@ -82,7 +90,7 @@
82	90	\| `maintain` \| Also move or delete tags, edit other people's comments and dismiss reviews \|
83	91	\| `admin` \| Settings, access, branch protection, secrets and webhooks \|
84	92
85		-Your role on a repository comes from owning it, your organization role, a collaborator grant or the repository being public, whichever is highest. Tokens and agent limits can then only lower it. See [Permissions](/docs/accounts/permissions).
	93	+Your role on a repository comes from owning it, your organization role (members get the organization's base permission), a collaborator grant or the repository being public, whichever is highest. Tokens and agent limits can then only lower it. See [Permissions](/docs/accounts/permissions).
86	94
87	95	## Tokens
88	96
		@@ -106,15 +114,15 @@
106	114	\| Create an organization, send invitations, manage organization secrets \| `admin` \|
107	115	\| Create or revoke tokens, create or disable agents, create agent tokens \| `admin` \|
108	116
109		-A token can also be restricted to a list of repositories; every other repository then answers `404` as if you had no access, and the token can't create repositories or organizations, send invitations or manage agents. Browser sessions aren't capped, so in the web UI you always act with your full role. Unlike GitHub's fine-grained tokens, there are no per-permission settings: the scope and the repository list are the whole model.
	117	+A token can also be restricted to a list of repositories; every other repository then answers `404` as if you had no access, and the token can't create repositories or organizations, send invitations, manage agents or create other tokens. A token can only be restricted to repositories your account can see. Browser sessions aren't capped, so in the web UI you always act with your full role. Unlike GitHub's fine-grained tokens, there are no per-permission settings: the scope and the repository list are the whole model.
110	118
111	119	Use a token as the Git password (with any username), as `Authorization: Bearer dfy_...` for the API and MCP, or let `diffinery login` and `diffinery auth setup-git` store it. See [Personal access tokens](/docs/accounts/tokens).
112	120
113	121	## Job tokens
114	122
115		-Each workflow job gets a short-lived job token as `GITHUB_TOKEN` (also `DIFFINERY_TOKEN`). It starts with `djt_`, acts as `diffinery-actions[bot]`, works only for the repository the job runs in and stops working when the job completes.
	123	+Each workflow job gets a short-lived job token as `GITHUB_TOKEN` (also `DIFFINERY_TOKEN`). It starts with `djt_`, acts as `diffinery-actions[bot]` on the repository the job runs in (it can also read other public repositories) and stops working when the job completes.
116	124
117		-The job token has `read` on the repository: the checkout step uses it to clone. With the job's `permissions: packages`, it can pull its owner's container images and push to images linked to its own repository. This differs from GitHub, where `GITHUB_TOKEN` can usually push. To push commits or call write endpoints from a workflow, store a personal or agent token as a secret and use that.
	125	+As on GitHub, the token can do what the workflow's `permissions:` grant (`contents`, `issues`, `pull-requests`, `statuses`, `packages` and so on), and an endpoint it lacks the permission for answers `403 Resource not accessible by integration`. Without `permissions:`, a job gets the repository's default, which for new repositories is GitHub's restricted one (`contents` and `packages` read); a repository admin can change it (see [Workflow permissions](/docs/actions/workflow-permissions)). The token never acts above `write`, so branch protection applies; it never changes repository settings, secrets or workflow files; it can't open or approve pull requests unless the repository allows it, and its approvals never count; and a run whose code came from an agent acts as that agent.
118	126
119	127	Sandboxes get a similar token starting with `dst_` (see [Sandboxes](#sandboxes)). See [Job tokens and sandbox tokens](/docs/accounts/permissions#job-tokens-and-sandbox-tokens) and [Secrets and variables](/docs/actions/secrets-and-variables).
120	128
		@@ -126,7 +134,7 @@
126	134
127	135	Some protections apply even without any rule: the default branch can't be deleted, and agents can't push to it or merge into it. When several rules match a branch, the rule that names the branch exactly wins over patterns; otherwise the oldest matching rule applies.
128	136
129		-Repository admins can bypass the rules unless the rule sets Do not allow administrators to bypass these rules (`enforceAdmins`). A push by an admin bypasses them on its own. A merge doesn't: an admin has to ask for it explicitly (the Merge without waiting for requirements (bypass) button, `"bypass_rules": true` in the API, or `diffinery pr merge --admin`), and the bypass is recorded in the audit log as `pull_request.merge_bypassed`. Bypassing merge requirements is for people only, never agents, and never works for a draft or a pull request with conflicts.
	137	+Repository admins can bypass the rules unless the rule sets Do not allow administrators to bypass these rules (`enforceAdmins`). A push by an admin bypasses them on its own. A merge doesn't: an admin has to ask for it explicitly (the Merge without waiting for requirements (bypass) button, `"bypass_rules": true` in the API, or `diffinery pr merge --admin`), and the bypass is recorded in the audit log as `pull_request.merge_bypassed`. `"bypass_rules": true` skips unmet rules, and `"bypass_merge_queue": true` skips only a required merge queue. Bypassing merge requirements is for people only, never agents, and never works for a draft or a pull request with conflicts.
130	138
131	139	See [Branch protection](/docs/repositories/branch-protection) and [Merge queue](/docs/collaboration/merge-queue).
132	140
		@@ -138,7 +146,7 @@
138	146
139	147	A pull request can be opened as a draft: a draft can't be merged until it is marked ready for review (the Ready for review button, `diffinery pr ready`, or `PATCH` with `"draft": false`), and it can be turned back into a draft later.
140	148
141		-Pull requests are reviewed with Approve, Request changes or comments, checked by workflow runs and other CI, and merged with a merge commit, a squash or a fast-forward rebase once nothing blocks them. See [Pull requests](/docs/collaboration/pull-requests) and [Issues](/docs/collaboration/issues).
	149	+Pull requests are reviewed with Approve, Request changes or comments, checked by workflow runs and other CI, and merged with a merge commit, a squash or a fast-forward rebase once nothing blocks them. With auto-merge turned on, Diffinery merges a pull request by itself as soon as nothing blocks it. See [Pull requests](/docs/collaboration/pull-requests) and [Issues](/docs/collaboration/issues).
142	150
143	151	## Actions
144	152
		@@ -187,11 +195,11 @@
187	195
188	196	## Push protection
189	197
190		-Every `git push` is scanned for leaked credentials such as API keys and private keys. A push that contains one is rejected and nothing from it is stored. A repository admin who is a person can push anyway with `git push -o allow-secrets=<reason>`, which is recorded and emailed. See [Push protection](/docs/security/push-protection) and [Security overview](/docs/security/overview).
	198	+Every `git push` is scanned for leaked credentials such as API keys and private keys, and so is every commit made without Git: in the web editor, through the REST API (`POST /repos/{owner}/{repo}/diffinery/commits` and the contents and git data APIs) and with the MCP `commit_files` tool. A push or commit that contains one is rejected and nothing from it is stored. A repository admin who is a person can push anyway with `git push -o allow-secrets=<reason>`, or commit through the commits API with `allow_secrets`, which is recorded and emailed. See [Push protection](/docs/security/push-protection) and [Security overview](/docs/security/overview).
191	199
192	200	## Audit log
193	201
194		-The audit log is an append-only record of security-relevant actions: sign-ins, passkey and token changes, repository settings, pushes, force pushes, merges, push protection decisions and package changes. When an agent acts, the entry names both the agent and the account it acts for.
	202	+The audit log is an append-only record of security-relevant actions: sign-ins, passkey and token changes, repository settings (whether changed on the web or through the API), pushes, force pushes, merges, push protection decisions and package changes. When an agent acts, the entry names both the agent and the account it acts for.
195	203
196	204	Only site administrators can view it, under Settings → Audit log, which shows the 200 most recent entries. See [Audit log](/docs/security/audit-log).
197	205
		@@ -205,6 +213,6 @@
205	213
206	214	- [Quickstart](/docs/quickstart): try these concepts end to end in about 15 minutes.
207	215	- [Releases](/docs/collaboration/releases), [Environments](/docs/actions/environments) and [Checks and statuses](/docs/collaboration/checks-and-statuses).
208		-- [Migrate from GitHub](/docs/migrate-from-github): import repositories, variables, issues and open pull requests with `diffinery migrate github`, and set secrets again.
	216	+- [Migrate from GitHub](/docs/migrate-from-github): import repositories or whole organizations, link your GitHub account, and set secrets again.
209	217	- [REST API](/docs/reference/rest-api), the [CLI reference](/docs/reference/cli) and the [MCP tool reference](/docs/reference/mcp-tools).
210	218	- [Limits](/docs/reference/limits): sizes, timeouts and quotas in one place.

		@@ -3,7 +3,7 @@
3	3	description: What Diffinery is, how it fits together, and where to start, whether you are a person, a team moving from GitHub or an AI agent.
4	4	---
5	5
6		-Diffinery is a git forge for teams of people and AI agents, running entirely on Cloudflare. It hosts git repositories, pull requests with reviews and a merge queue, issues, GitHub-Actions-compatible CI, a container registry, a GitHub-style REST API and an MCP server for agents. Your existing `.github/workflows/*.yml` files run as they are, and `diffinery migrate github` imports a GitHub repository in one command (see [Migrate from GitHub](/docs/migrate-from-github)).
	6	+Diffinery is a git forge for teams of people and AI agents, running entirely on Cloudflare. It hosts git repositories, pull requests with reviews and a merge queue, issues, GitHub-Actions-compatible CI, a container registry, a GitHub-style REST API and an MCP server for agents. Your existing `.github/workflows/*.yml` files run as they are, and a server-side importer brings over a GitHub repository or a whole organization, with its history, issues, pull requests, reviews and releases, from the web, the CLI (`diffinery migrate github`), the REST API or MCP (see [Migrate from GitHub](/docs/migrate-from-github)).
7	7
8	8	## Start here
9	9
		@@ -11,7 +11,7 @@
11	11	\| --- \| --- \|
12	12	\| Get set up and push your first repository \| [Quickstart](/docs/quickstart) \|
13	13	\| Understand accounts, roles, agents and runs \| [Concepts](/docs/concepts) \|
14		-\| Move a project from GitHub (`diffinery migrate github`) \| [Migrate from GitHub](/docs/migrate-from-github) \|
	14	+\| Move a project or an organization from GitHub (Settings → Imports, or `diffinery migrate github`) \| [Migrate from GitHub](/docs/migrate-from-github) \|
15	15	\| Run CI \| [Actions overview](/docs/actions/overview) and [Workflow syntax](/docs/actions/workflow-syntax) \|
16	16	\| Connect an AI agent \| [Agents](/docs/agents/overview) and [MCP](/docs/agents/mcp) \|
17	17	\| Script against Diffinery \| [REST API guide](/docs/reference/rest-api), [REST API reference](/docs/api) and [CLI reference](/docs/reference/cli) \|

		@@ -160,6 +160,8 @@
160	160
161	161	When a linked repository is [transferred](/docs/repositories/overview#transfer-a-repository) to another owner, its packages move with it and keep following its access: `diffinery.com/acme/website` becomes `diffinery.com/acme-labs/website`. The old name keeps working for pulls and pushes, for anyone the moved package allows (everyone else gets `NAME_UNKNOWN`), until the old owner gets a repository of that name again. Images under a renamed owner's old login resolve the same way. Unlinked packages stay with their owner.
162	162
	163	+An image keeps its own name when it moves: transferring the repository under a new name, or renaming it, doesn't rename its images. Workflows that push to `diffinery.com/${{ github.repository }}` push to the new owner and name from then on, which creates a new package there on the first push. A redirect for an image name ends when the old owner creates a repository whose name is that image name (or its first part, for an image such as `acme/website/api`). A transfer is refused when the new owner already has an image with the name of one of the repository's images.
	164	+
163	165	## Permissions
164	166
165	167	Each caller gets one of four roles on a package:
		@@ -210,16 +212,16 @@
210	212
211	213	### Workflows
212	214
213		-A workflow's `GITHUB_TOKEN` follows the job's `packages` permission:
	215	+A workflow's `GITHUB_TOKEN` follows the `packages` permission of the job's effective permissions, the same ones the rest of the API checks (see [Workflow permissions](/docs/actions/workflow-permissions)):
214	216
215	217	\| `permissions` in the workflow or job \| `packages` permission \|
216	218	\| --- \| --- \|
217		-\| No `permissions` anywhere \| `write` \|
	219	+\| No `permissions` anywhere \| The repository's default: `read` when the default is read-only (the default for new repositories), `write` when it is read and write \|
218	220	\| `write-all` or `packages: write` \| `write` \|
219	221	\| `read-all` or `packages: read` \| `read` \|
220	222	\| A mapping without `packages`, or `packages: none` \| none \|
221	223
222		-The job's `permissions` replace the workflow's. With that permission, the token gets these roles:
	224	+The job's `permissions` replace the workflow's. A job in a reusable workflow never gets more than the job that calls it, and a run for a pull request from another repository gets `read` at most. With that permission, the token gets these roles:
223	225
224	226	\| Package \| `read` \| `write` \|
225	227	\| --- \| --- \| --- \|
		@@ -576,7 +578,7 @@
576	578	\| `denied: pushing to acme/tools is not allowed` \| You can pull but not push. For an organization member, this happens on an unlinked package another member created: ask its creator or an organization owner to link it to a repository you can write to. \|
577	579	\| `denied: deleting from acme/website is not allowed` \| Deleting needs the admin role, and an `admin`-scoped token. \|
578	580	\| `... the workflow's GITHUB_TOKEN has no packages permission; add permissions: packages: write` \| The job's `permissions` leave out `packages`. Add `packages: write` (or `read` to pull). \|
579		-\| `... the workflow's GITHUB_TOKEN has packages: read; add permissions: packages: write to push` \| Change the permission to `write`. \|
	581	+\| `... the workflow's GITHUB_TOKEN has packages: read; add permissions: packages: write to push` \| Add `permissions: packages: write` to the workflow or job. Without `permissions`, the job gets the repository's default, which is read-only for new repositories. \|
580	582	\| `... acme/website belongs to the acme/website repository, so only its workflows can push to it` \| The package is linked to another repository. Push from that repository's workflows, or change the linked repository. \|
581	583	\| `... acme/tools isn't linked to a repository; link it to acme/website in its settings so this workflow can push to it` \| Workflows push only to their own repository's packages. Link the package to the workflow's repository on the package page. \|
582	584	\| `... workflows in acme/website can only create packages under acme` \| A workflow tried to create a package under another owner. Use a personal or agent token from a secret. \|

		@@ -89,7 +89,7 @@
89	89
90	90	## 5. Push your code
91	91
92		-To bring over a repository that lives on GitHub, with its branches, tags, variables and optionally its issues and open pull requests, use `diffinery migrate github` instead; see [Migrate from GitHub](/docs/migrate-from-github).
	92	+To bring over a repository that lives on GitHub, import it instead of pushing: Settings → Imports → Import from GitHub in the web UI, or `diffinery migrate github acme/website --to acme/website`. The import runs on the server and copies the history, issues and pull requests with their numbers, reviews, labels, releases, branch protection and variables (secret names only, never values); see [Migrate from GitHub](/docs/migrate-from-github).
93	93
94	94	From an existing project:
95	95
		@@ -113,7 +113,7 @@
113	113
114	114	Open `https://diffinery.com/acme/website` to see the files (with syntax highlighting) and the rendered README.
115	115
116		-Every push is checked for leaked credentials. If you accidentally commit an API key or private key, the push is rejected with `Push blocked: possible secrets detected.` and nothing from it is stored: remove the secret from your commits and push again. See [Push protection](/docs/security/push-protection) and [Git over HTTPS](/docs/repositories/git).
	116	+Every push is checked for leaked credentials, and so is every commit made in the web editor, through the REST API or over MCP. If you accidentally commit an API key or private key, the push is rejected with `Push blocked: possible secrets detected.` and nothing from it is stored: remove the secret from your commits and push again. See [Push protection](/docs/security/push-protection) and [Git over HTTPS](/docs/repositories/git).
117	117
118	118	## 6. Add a workflow and watch it run
119	119
		@@ -160,6 +160,16 @@
160	160
161	161	`runs-on: ubuntu-latest` runs in a fresh Ubuntu 24.04 container on Diffinery's hosted runners. The job reports a check named `CI / test` (workflow name, then job name) on the commit, which you can require in branch protection later. If you also run another CI system, it can report its results on the same commits as commit statuses or check runs through the GitHub-compatible REST API; see [Checks and statuses](/docs/collaboration/checks-and-statuses). If a workflow file has a syntax error, its run fails and shows the errors; `diffinery workflow validate` checks files before you push. See [Actions](/docs/actions/overview).
162	162
	163	+Each job gets a `GITHUB_TOKEN` that follows GitHub's `permissions:` model. In a new repository it can only read the code and packages (`contents: read`, `packages: read`), which is all the checkout above needs. A workflow that comments on pull requests, pushes or publishes releases has to ask for more, for example:
	164	+
	165	+```yaml
	166	+permissions:
	167	+ contents: write
	168	+ pull-requests: write
	169	+```
	170	+
	171	+A repository admin can also change the default. See [Workflow permissions](/docs/actions/workflow-permissions).
	172	+
163	173	## 7. Open a pull request
164	174
165	175	Make a change on a branch and push it:
		@@ -248,7 +258,7 @@
248	258	## Next steps
249	259
250	260	- [Concepts](/docs/concepts): accounts, roles, tokens, visibility, Actions and agents in one page.
251		-- [Migrate from GitHub](/docs/migrate-from-github): import a GitHub repository with `diffinery migrate github` (branches, tags, variables and, optionally, issues and open pull requests), then set its secrets again.
	261	+- [Migrate from GitHub](/docs/migrate-from-github): import a GitHub repository or organization from the web, the CLI, the API or MCP, then set its secrets again.
252	262	- [Branch protection](/docs/repositories/branch-protection): require pull requests, reviews and checks, and [Checks and statuses](/docs/collaboration/checks-and-statuses) to report results from other CI systems.
253	263	- [Releases](/docs/collaboration/releases) and [Environments](/docs/actions/environments): ship versions and deploy them.
254	264	- [Organizations](/docs/accounts/organizations) and [Invitations](/docs/accounts/invitations): bring your team.

		@@ -1,11 +1,11 @@
1	1	---
2	2	title: Limits
3		-description: Every hard limit in Diffinery and where it applies: sign-in, tokens, API, search, archives, releases, git, pull requests, Actions, sandboxes, packages, email.
	3	+description: Every hard limit in Diffinery and where it applies: sign-in, tokens, API, search, archives, releases, git, Actions, sandboxes, packages, imports, email.
4	4	---
5	5
6	6	This page lists the fixed limits built into Diffinery: sizes, counts, timeouts and lifetimes. Use it when a push, a workflow, an upload or an API call fails with a size or count error, or when you plan something large. Values come from the code of the running version. Where a limit comes from Cloudflare rather than from Diffinery, the table says so.
7	7
8		-Units: 1 KiB is 1,024 bytes, 1 MiB is 1,048,576 bytes, and 1 GB in the cache row is 1,073,741,824 bytes. Sizes Diffinery checks itself and writes as "MB" (pushes, release assets, archives, profile pictures, forms) are in MiB: "100 MB" for pushes means 104,857,600 bytes.
	8	+Units: 1 KiB is 1,024 bytes, 1 MiB is 1,048,576 bytes, and 1 GB in the cache and artifact rows is 1,073,741,824 bytes. Sizes Diffinery checks itself and writes as "MB" (pushes, release assets, archives, profile pictures, forms) are in MiB: "100 MB" for pushes means 104,857,600 bytes.
9	9
10	10	## Sign-in and sessions
11	11
		@@ -31,7 +31,7 @@
31	31	\| An agent's first token \| 90 days, `write` scope \| The token created together with an agent, unless you pass `token.expires_in_days` or `token.scopes`. \|
32	32	\| Expiry reminder email \| 7 days before expiry \| Sent once per token, and only for tokens that were valid for more than 8 days. \|
33	33	\| "Last used" accuracy \| 1 hour \| A token's last-used time is updated at most once an hour. \|
34		-\| Creating tokens through the API \| A browser session \| No token can create a token or an agent: `POST /api/v3/diffinery/tokens` and the agent endpoints return `403 creating tokens needs a browser session: sign in at https://diffinery.com/settings/tokens` for every token. \|
	34	+\| Creating tokens through the API \| A browser session \| No token can create a token or an agent: `POST /api/v3/diffinery/tokens` and the agent endpoints return `403 creating tokens needs a browser session: sign in at https://diffinery.com/settings/tokens` for every token. Each name in `repositories` must be a repository you can see, or the request fails with `422 unknown repository acme/website`. \|
35	35	\| Sandbox token lifetime \| 24 hours \| A sandbox's git and API credentials stop working 24 hours after it starts, or earlier when it is closed or its creator loses access. \|
36	36	\| Token scopes \| `read`, `write` or `admin`; default `["write"]` \| A new token (personal or agent) without `scopes` gets `write`. An empty list or any other name returns `422 scopes must be a non-empty list of: read, write, admin`. Repeated names are stored once. \|
37	37	\| Writes with a `read` token \| Refused \| Every change returns `403 this token needs the write scope`. Git fetch and Git LFS downloads still work. \|
		@@ -172,16 +172,29 @@
172	172	\| Service container health check \| 15 minutes \| How long a job waits for a `services:` container's health check to pass. \|
173	173	\| Log line length \| 16,384 characters \| Longer lines are cut and end with `…`. \|
174	174	\| Log shown in the web UI \| 20,000 lines \| The job page shows the first 20,000 lines and links to the full log. \|
	175	+\| Job log retention \| 90 days \| A finished job's log is stored for 90 days, then deleted. The run and its jobs stay listed. \|
175	176	\| OIDC token lifetime \| 10 minutes \| ID tokens from `permissions: id-token: write`. \|
176	177
177	178	## Caches and artifacts
178	179
	180	+These apply to `actions/cache` and `actions/upload-artifact` (and the matching built-ins) in hosted and self-hosted jobs. See [Artifacts and caches](/docs/reference/rest-api#actions) in the REST API reference for listing and deleting them.
	181	+
179	182	\| Limit \| Value \| Applies to \|
180	183	\| --- \| --- \| --- \|
181		-\| Cache storage per repository \| 10 GB \| When saving a cache pushes the total over 10 GB, the least recently used entries are deleted until it fits. \|
182		-\| Cache key length \| 512 characters \| Longer keys fail with `cache key too long`. \|
183		-\| Saving an existing cache key \| Not allowed \| Cache entries are immutable; saving a key that exists is skipped (`409 cache entry already exists`). \|
184		-\| Cache entry and artifact size \| 100 MB compressed \| Each cache entry and each artifact is uploaded as one compressed archive in one request, and Cloudflare refuses request bodies over 100 MB. \|
	184	+\| Cache storage per repository \| 10 GB \| Every cache entry of the repository together, on all branches. When saving a cache would go over 10 GB, the least recently used entries are deleted until it fits. \|
	185	+\| Unused caches \| Deleted after 7 days \| An entry that no job restored for 7 days is deleted the next time a job saves a cache in the repository. \|
	186	+\| Cache entry size \| 10 GB \| A larger entry fails with `413 a cache entry may be at most 10737418240 bytes`. If caches still being uploaded by other jobs fill the budget, saving fails with `413 uploads in progress use the repository's whole cache budget`. \|
	187	+\| Cache key \| 512 characters, no commas \| Longer keys or keys with `,` fail with `400 invalid cache key`. Up to 20 restore keys per lookup. \|
	188	+\| Saving an existing cache key \| Skipped \| A key and version that already exist for the branch are not replaced; the save is skipped with a warning. \|
	189	+\| Which caches a job can restore \| Its own branch, then the base branch, then the default branch \| A pull request job also restores caches of its base branch, a merge queue job those of the target branch. \|
	190	+\| Artifact storage per repository \| 10 GB by default \| Artifacts that haven't expired plus uploads in progress. Past the quota, an upload fails with `413 the repository's artifact storage quota (N bytes) is used up; delete artifacts or wait for them to expire`. Operators change it with `ARTIFACT_QUOTA_BYTES` (see [Configuration](/docs/self-hosting/configuration#worker-variables)). \|
	191	+\| Artifact retention \| 1 to 90 days, default 90 \| `retention-days`. Values outside the range are clamped. \|
	192	+\| Expired artifacts \| Listed for 90 more days \| After its retention the content is deleted. The artifact stays in the API with `expired: true`, and downloading it returns `410 Artifact has expired`. \|
	193	+\| Artifact name \| 256 characters, unique per run \| Names can't contain `"`, `:`, `<`, `>`, `\|`, `*`, `?`, `\`, `/` or line breaks. A second artifact with the same name in a run fails with `409 an artifact with this name already exists on the workflow run`. \|
	194	+\| Upload request size \| 256 MiB, and Cloudflare's 100 MB request limit \| `actions/cache` and `actions/upload-artifact` upload in blocks, so cache entries and artifacts can be larger than one request. On plans where Cloudflare refuses request bodies over 100 MB, that is the effective block size. \|
	195	+\| Blocks per upload \| 50,000 \| More fails with `Too many blocks.` \|
	196	+\| Download links \| 1 hour, or 10 minutes from the REST API \| The signed links a job gets to restore a cache or download an artifact, and the redirect from `GET .../actions/artifacts/{id}/zip`. \|
	197	+\| Runtime token \| While the job runs \| `ACTIONS_RUNTIME_TOKEN` works only while its job is in progress, and at most until 30 minutes after the job's timeout. \|
185	198
186	199	## Agent sandboxes
187	200
		@@ -206,6 +219,31 @@
206	219	\| Tags per tag-list page \| 10,000 \| `GET /v2/<owner>/<name>/tags/list?n=`. \|
207	220	\| Packages listed per owner \| 1,000 \| `GET /api/v3/users/{owner}/packages`, `/orgs/{owner}/packages`, `/user/packages`. \|
208	221
	222	+## Imports
	223	+
	224	+Limits of [imports from GitHub](/docs/migrate-from-github), from the web form, `diffinery migrate github`, `POST /api/v3/diffinery/imports` and the MCP tool `start_github_import`.
	225	+
	226	+\| Limit \| Value \| Applies to \|
	227	+\| --- \| --- \| --- \|
	228	+\| Imports at a time \| 1 organization import and 3 repository imports \| Counted per person or agent who starts them and per account imported into. Organization imports count while `draft`, `queued` or `running`; repository imports while `queued` or `running`, not counting the repositories inside an organization import. Over the limit: `429 an organization import is already in progress (at most 1 at a time); wait for it to finish or cancel it` or `429 too many repository imports are already running (at most 3 at a time); wait for one to finish`. \|
	229	+\| Repository size \| 10 GB by default \| GitHub's reported size of the repository in a one-repository import, checked before the import starts: `422 the repository is about N GB, over the M GB import limit; ask an administrator to raise IMPORT_MAX_REPO_KB or split the repository`. Operators change it with `IMPORT_MAX_REPO_KB` (see [Configuration](/docs/self-hosting/configuration#worker-variables)). The repositories of an organization import are not checked against it. \|
	230	+\| Repositories per organization import \| 1,000 \| The `repositories` list (`422 at most 1000 repositories per import`), and the repositories read from the GitHub organization or user. \|
	231	+\| Repositories imported at once \| 1 to 8, default 3 \| One organization import's `concurrency` (Repositories at a time in the form). `422 concurrency must be between 1 and 8`. \|
	232	+\| Git transfer \| 6 hours \| Copying the Git data in the import container. After that the import fails with `the Git transfer did not finish within 6 hours`. A transfer that fails for another reason is tried once more, except when push protection stopped it. \|
	233	+\| Size of each push in the transfer \| 32 MiB \| The import agent pushes history in chunks of at most this size, below the 100 MB push limit, and smaller ones if a push is still refused as too large. \|
	234	+\| Retries of each import step \| 5, 15 seconds apart at first and backing off exponentially \| Each step of the import's durable workflow, which may run for at most 15 minutes per call. \|
	235	+\| Calls per paged step \| 2,000 \| Steps that page through GitHub (issues, comments, reviews and the rest). Each call reads up to 10 pages of 100 items (30 pull requests for reviews). More fails the import with `the <step> step did not finish within 2000 pages`. \|
	236	+\| GitHub rate limits \| Waits 5 seconds to 1 hour at a time \| When GitHub answers with a rate limit, the import sleeps until it resets and continues; it doesn't fail. \|
	237	+\| GitHub responses \| 8 MiB each, 30 seconds per request \| A larger response fails with `GitHub response is too large` or `GitHub response exceeded the size limit`. Redirects are followed only on the same host. \|
	238	+\| Organization import duration \| 1 week \| An organization import waits up to 168 hours for its repositories. Any still unfinished then count as not imported, and the organization import fails. \|
	239	+\| Draft organization imports \| 7 days \| An organization import started in the web form whose repositories were never chosen is cancelled (`draft expired`) and its GitHub token erased. \|
	240	+\| Release assets \| 2 GiB each \| Larger assets, and assets that can't be downloaded, are skipped with a warning. \|
	241	+\| Warnings \| 500 per import, 1,000 characters each \| Further warnings are not recorded. \|
	242	+\| Imports listed \| 100 \| The most recent imports you started, in `GET /api/v3/diffinery/imports`, `list_imports` and the Imports page. \|
	243	+\| GitHub token \| 400 characters, no spaces \| `422 github_token is not a valid token`. Deleted when the import ends. \|
	244	+\| Push token of the transfer \| 1 day, one repository \| The token the import container pushes with. It works only for Git, Git LFS and the import's own agent endpoints, and is revoked when the transfer ends. \|
	245	+\| Copied repository details \| 20 topics, 1,000 characters of description, 500 of homepage \| Taken from the GitHub repository. \|
	246	+
209	247	## Webhooks and events
210	248
211	249	\| Limit \| Value \| Applies to \|
		@@ -239,7 +277,8 @@
239	277	\| Worker CPU time \| 300,000 ms per request \| `limits.cpu_ms`. \|
240	278	\| Runner containers \| `standard-2`, up to 100 instances \| `containers[RunnerContainer]`. \|
241	279	\| Sandbox containers \| `standard-1`, up to 50 instances \| `containers[SandboxContainer]`. \|
242		-\| Container rollout grace period \| 3,600 seconds \| `rollout_active_grace_period` for both container classes. \|
	280	+\| Import containers \| `standard-4`, up to 20 instances \| `containers[ImportContainer]`: one container per Git transfer of an import. \|
	281	+\| Container rollout grace period \| 3,600 seconds \| `rollout_active_grace_period` for every container class. \|
243	282	\| Event queue \| Batches of up to 50 messages (2 seconds), 8 retries \| `diffinery-events`, dead-letter queue `diffinery-events-dlq`. \|
244	283	\| Mail queue \| Batches of up to 20 messages (2 seconds), 8 retries \| `diffinery-mail`, dead-letter queue `diffinery-mail-dlq`. The consumer itself gives up after 6 attempts. \|
245		-\| Cron trigger \| Every 5 minutes \| `/5 * * *`: scheduled workflows, token expiry reminders, email log pruning and container registry cleanup. \|
	284	+\| Cron trigger \| Every 5 minutes \| `/5 * * *`: scheduled workflows, token expiry reminders, email log pruning, container registry cleanup and cancelling draft imports older than 7 days. \|

codician/diffinerypublic

Docs: GitHub importer, GITHUB_TOKEN permissions, auto-merge and everything shipped since #32 (#45)

		@@ -109,15 +109,13 @@
109	109	- An entry only has an effect for a name that is also in `requiredChecks`.
110	110	- Binding a check to an agent's login makes it impossible to satisfy, because agents' reports never count.
111	111
112		-`requiredCheckSources` can only be set through the API. The Branch protection page does not show it.
	112	+`requiredCheckSources` can only be set through the API. The Branch protection page does not show it, but saving a rule there keeps the bindings of every check that is still listed in Required status checks, also when you change the rule's pattern. A binding for a check you remove from Required status checks is dropped with it; to require and bind that check again, send the rule with `PUT .../protection`.
113	113
114		-> Important: Saving a rule from the Branch protection page in the web UI replaces the whole rule with the form's fields, which removes `requiredCheckSources`. After editing a rule in the web UI, send the binding again with `PUT .../protection`.
115		-
116	114	### Approvals
117	115
118	116	Diffinery counts each reviewer's most recent approving or "request changes" review:
119	117
120		-- Only approvals from people count. Agent approvals are advisory and never count.
	118	+- Only approvals from people count. Approvals from agents and from a workflow's `GITHUB_TOKEN` are advisory and never count. (A job token can approve at all only when the repository allows workflows to approve pull requests; see [Pull requests and workflow tokens](/docs/collaboration/pull-requests#pull-requests-and-workflow-tokens).)
121	119	- You cannot approve your own pull request, and approving requires the write role.
122	120	- With `dismissStaleReviews`, only approvals given on the pull request's current head commit count.
123	121	- If a pull request was opened by an agent, it needs at least one approval from a person even when `requiredApprovals` is `0`.
		@@ -145,7 +143,7 @@
145	143	- A workflow's `GITHUB_TOKEN` is held to the same rule as agents (and needs `contents: write`), even when the run's code didn't come from an agent.
146	144	- The agent's access is checked again when the merge happens, and auto-merge turns itself off, with a comment saying why, if the rule no longer allows it, or if someone else pushes to the pull request's branch.
147	145
148		-Turning on auto-merge, turning it off and the merge itself are audited (`pull_request.auto_merge_enabled`, `pull_request.auto_merge_disabled`, `pull_request.auto_merged`).
	146	+Turning on auto-merge, turning it off and the merge itself are audited (`pull_request.auto_merge_enabled`, `pull_request.auto_merge_disabled`, `pull_request.auto_merged`, or `pull_request.auto_merge_enqueued` when it joins a merge queue). How to turn auto-merge on and off in the web UI, the API and MCP, and when it turns itself off, is in [Auto-merge](/docs/collaboration/pull-requests#auto-merge).
149	147
150	148	#### Waiving approvals for agents
151	149
		@@ -156,6 +154,16 @@
156	154	- A person's requested changes still block the merge, and a pull request that changes a workflow file still needs a person to merge it.
157	155	- It is set per branch rule, only by people with the admin role, and never comes in with an import. Turning `allowAgentAutoMerge` off turns this off too. Every change is audited as `repo.protection.agent_approval_waiver`.
158	156
	157	+### Workflow tokens
	158	+
	159	+A workflow job's `GITHUB_TOKEN` is held to branch protection like a person with the write role:
	160	+
	161	+- It never has more than the write role, whatever its `permissions:` say, so it can't bypass any rule as an admin, and it can't read or change branch protection rules (`this endpoint is not available to a workflow's GITHUB_TOKEN`).
	162	+- Pushes and merges with it need `contents: write`.
	163	+- It can't create, change or delete files under `.github/workflows/` or `.diffinery/workflows/`, by push, API commit or merge: the update is rejected with ``refusing to allow a GitHub App to create or update workflow `<path>` without `workflows` permission``.
	164	+- In a run whose code came from an agent (an agent started the run, pushed the branch last, or opened the pull request, and re-runs of such runs and `workflow_run` runs that follow them), the token acts as an agent: the agent rules above apply to it.
	165	+- Its approvals never count toward `requiredApprovals`.
	166	+
159	167	### Merge queue settings
160	168
161	169	`mergeQueue` turns on a merge queue for matching branches. Pull requests are then added to the queue instead of being merged directly, and each is tested on top of the base branch and the pull requests ahead of it. See [Merge queue](/docs/collaboration/merge-queue) for how the queue works.
		@@ -177,13 +185,13 @@
177	185	\| Action \| Admin bypass (when `enforceAdmins` is off) \|
178	186	\|---\|---\|
179	187	\| Direct push, force push or deletion on a protected branch \| Automatic for admins. An agent with the admin role gets this only on branches where `agentsMayPush` is on. \|
180		-\| Merging a pull request that has blockers \| Only on request, and only for admins who are people, when the pull request has no merge conflicts and is not a draft. In the web UI the button reads Merge without waiting for requirements (bypass) and asks for confirmation. Through the API send `"bypass_rules": true` on `PUT /repos/{owner}/{repo}/pulls/{number}/merge`; with the CLI use `diffinery pr merge 12 --admin`. Without the flag the merge fails with `405`, and the message ends with `(as an admin you can bypass with bypass_rules)`. \|
181		-\| A merge commit on a branch that requires linear history \| Refused with `405` and `main requires linear history; use squash or rebase`, unless the admin asks for a bypass as above. \|
	188	+\| Merging a pull request that has blockers \| Only on request, and only for admins who are people, when the pull request has no merge conflicts and is not a draft. In the web UI the button reads Merge without waiting for requirements (bypass) and asks for confirmation; it isn't shown when the rule sets `enforceAdmins`. Through the API send `"bypass_rules": true` on `PUT /repos/{owner}/{repo}/pulls/{number}/merge`; with the CLI use `diffinery pr merge 12 --admin`. Without the flag the merge fails with `405`, and the message ends with `(as an admin you can bypass with bypass_rules)`. \|
	189	+\| A merge commit on a branch that requires linear history \| Refused with `405` and `main requires linear history; use squash or rebase`, unless the admin sends `bypass_rules`. The web merge form doesn't offer Create a merge commit on such a branch at all. \|
182	190	\| Merging directly when a merge queue is required \| Only on request: Merge now (bypass the queue) in the web UI, `"bypass_merge_queue": true` on `PUT /repos/{owner}/{repo}/pulls/{number}/merge`, or `diffinery pr merge 12 --admin`. This skips only the queue: a pull request that doesn't meet the rules also needs `"bypass_rules": true`. In the web UI the button then reads Merge now (bypass the queue and the unmet requirements) and sends both. \|
183	191	\| Deleting the default branch \| Never allowed. \|
184	192	\| Agent rules \| Never bypassed by admin status for merges. \|
185	193
186		-A merge that bypassed unmet blockers is recorded in the [audit log](/docs/security/audit-log#git-and-pull-requests) as `pull_request.merge_bypassed`, with the pull request (`acme/website#42`) as the target and the `blockers` and `base` branch in the detail. See [Admin bypass](/docs/collaboration/pull-requests#admin-bypass).
	194	+A merge that bypassed anything is recorded in the [audit log](/docs/security/audit-log#git-and-pull-requests) as `pull_request.merge_bypassed`, with the pull request (`acme/website#42`) as the target and the `base` branch and bypassed `blockers` in the detail: the unmet rules, `linear history required` for a merge commit on a linear-history branch, and `merge queue` for a skipped queue. See [Admin bypass](/docs/collaboration/pull-requests#admin-bypass).
187	195
188	196	With `enforceAdmins` on, admins follow the same rules as everyone else.
189	197
		@@ -198,8 +206,10 @@
198	206	5. To use a merge queue, check Require a merge queue and choose the Merge method, Build concurrency and Check timeout (minutes).
199	207	6. Select Create rule.
200	208
201		-Existing rules are listed above the form with a summary such as `PR required · 1 approval · 2 required checks`. Click a rule to expand and edit it, then select Save rule. If you change the pattern of an existing rule, the old pattern's rule is replaced, and the rule counts as newly created when several rules match a branch (see [Which rule applies](#which-rule-applies)). Select Delete next to a rule to remove it.
	209	+Existing rules are listed above the form with a summary such as `PR required · 1 approval · 2 required checks`. Click a rule to expand and edit it, then select Save rule. You see `Branch protection saved.` Saving keeps the rule's `requiredCheckSources` bindings for the checks that are still required. If you change the pattern of an existing rule, the old pattern's rule is replaced, and the rule counts as newly created when several rules match a branch (see [Which rule applies](#which-rule-applies)). Select Delete next to a rule to remove it.
202	210
	211	+Changes are recorded in the [audit log](/docs/security/audit-log) as `repo.protection.set` and `repo.protection.delete`, whether they come from the web UI or the API (API changes carry `"via": "api"` in the detail). On an archived repository, rules can't be changed (`repository is archived (read-only)`).
	212	+
203	213	The repository's branches list marks protected branches with a protected badge, and `GET /api/v3/repos/{owner}/{repo}/branches` returns `"protected": true` for them.
204	214
205	215	## Managing rules with the API
		@@ -321,6 +331,8 @@
321	331	9. A non-fast-forward update needs `allowForcePush`.
322	332	10. With `requireLinearHistory`, new commits must not include merge commits (the first 1,000 new commits are checked).
323	333
	334	+A workflow's `GITHUB_TOKEN` is also refused, right after step 2, when the update creates, changes or deletes a file under `.github/workflows/` or `.diffinery/workflows/`. A new branch is compared with where it branched off the default branch.
	335	+
324	336	A rejected ref shows the reason in git's output:
325	337
326	338	```text
		@@ -342,6 +354,7 @@
342	354	\| `merge queue branches are read-only` \| `gh-readonly-queue/...` branches belong to the merge queue. \|
343	355	\| `refs/pull/ is managed by Diffinery for pull requests` \| Pull request refs cannot be pushed. \|
344	356	\| `missing objects` \| The update points at a commit the server doesn't have. Push the commits too, or fetch the full history first. \|
	357	+\| ``refusing to allow a GitHub App to create or update workflow `<path>` without `workflows` permission`` \| A workflow's `GITHUB_TOKEN` tried to add, change or delete a workflow file. Push it as a person or with a personal token. \|
345	358
346	359	## Merge blockers
347	360
		@@ -361,8 +374,9 @@
361	374	\| `required check '<name>' <conclusion>` \| The check finished with a conclusion other than success, skipped or neutral, for example `required check 'ci / test' failure`. A commit status in the `failure` or `error` state shows as `failure`. \|
362	375	\| `branch is behind its base; update it (linear history required)` \| With `requireLinearHistory`, the head branch must contain the latest base commit. \|
363	376	\| `write access is required to merge` \| Your role is below write. \|
364		-\| `agents may not merge into this branch; a human must merge` \| An agent tried to merge into the default branch or a protected branch without `agentsMayMerge`. Agents can [land changes through auto-merge](#agents-landing-changes) instead. \|
	377	+\| `agents may not merge into this branch; a human must merge` \| An agent (or a workflow token in a run whose code came from an agent) tried to merge into the default branch or a protected branch without `agentsMayMerge`. Agents can [land changes through auto-merge](#agents-landing-changes) instead. \|
365	378	\| `the pull request changes workflow file <path>; a person must merge it` \| An agent's auto-merge or merge queue entry relies on `allowAgentAutoMerge`, and the pull request changes a workflow. \|
	379	+\| ``refusing to allow a GitHub App to create or update workflow `<path>` without `workflows` permission`` \| A workflow's `GITHUB_TOKEN` tried to merge a pull request that changes a workflow file. \|
366	380
367	381	Example response from `GET /api/v3/repos/acme/website/pulls/42`, trimmed:
368	382
		@@ -418,7 +432,7 @@
418	432	- Required Actions check names include the workflow name: `ci / test`.
419	433	- Rules have no options for restricting pushes to specific users or teams, requiring signed commits, requiring conversation resolution or requiring code owner reviews.
420	434	- A "changes requested" review blocks merging even on branches without a rule.
421		-- An admin's merge past unmet rules must be asked for with `bypass_rules` (or `bypass_merge_queue`) and is written to the audit log as `pull_request.merge_bypassed`.
	435	+- An admin's merge past unmet rules must be asked for with `bypass_rules`, and skipping a merge queue with `bypass_merge_queue`; each covers only what it names, and both are written to the audit log as `pull_request.merge_bypassed`.
422	436	- When several rules match, the choice follows GitHub: a rule naming the branch exactly wins, then the oldest rule.
423	437
424	438	## Troubleshooting
		@@ -429,7 +443,7 @@
429	443	\| A required check never turns green \| The name does not match. Compare it with the checks list on the pull request, including the `workflow / ` prefix. \|
430	444	\| A check shows as passed on the pull request but the merge says `has not run` \| The passing report doesn't count: it came from an agent, or from an account other than the one bound in `requiredCheckSources`, or Diffinery Actions also reported a check with the same name. Report the check from the bound account, or change the binding. \|
431	445	\| `invalid source for required check '<name>'` \| A value in `requiredCheckSources` is not a valid login. Use the reporter's login or `diffinery-actions`. \|
432		-\| `requiredCheckSources` disappeared \| The rule was saved from the web UI, which doesn't keep it. Send it again with `PUT .../protection`. \|
	446	+\| A `requiredCheckSources` binding disappeared \| The check was removed from Required status checks when the rule was saved in the web UI, which drops the bindings of checks that are no longer required. Send the rule again with `PUT .../protection`. \|
433	447	\| An agent's pull request needs an approval even with `requiredApprovals: 0` \| Agent-authored pull requests always need one approval from a person. \|
434	448	\| An approval disappeared after a push \| `dismissStaleReviews` is on. Ask the reviewer to approve the new commits. \|
435	449	\| Your admin push was rejected \| The rule sets `enforceAdmins`, or your token has the `write` scope instead of `admin`. \|

		@@ -175,6 +175,8 @@
175	175	\| `enter a valid file path` \| The path is empty or contains `..` or `.git`. \|
176	176	\| `invalid path "<path>": ...` \| A part of the path is a name Git reserves (such as `.GIT` or `git~1`), contains `\`, or is longer than 255 characters. Choose another name. \|
177	177	\| `a commit message is required` \| Fill in the commit message. \|
	178	+\| `push protection: possible secret detected (<kind>) in <path>. Remove it, or rotate it and ask an admin.` \| The new content looks like a credential, such as an API key or private key. Remove it and commit again. See [Push protection](/docs/security/push-protection). \|
	179	+\| `repository is archived (read-only)` \| The repository is archived; nothing can be committed until an admin unarchives it. \|
178	180
179	181	Without a browser or a Git client, you can change files with the REST API:
180	182
		@@ -182,8 +184,10 @@
182	184	- `DELETE /api/v3/repos/{owner}/{repo}/contents/{path}` deletes one file, with `message` and the file's `sha`.
183	185	- `POST /api/v3/repos/{owner}/{repo}/diffinery/commits` (or the MCP `commit_files` tool) changes several files in one commit.
184	186
185		-Branch protection and agent guardrails apply to all of them, as for a `git push`. `PUT .../contents` (and `POST .../git/blobs`) also scan the new content for credentials and refuse it with `push protection: possible secret detected (...)` (HTTP 422). See [REST API](/docs/reference/rest-api) and [MCP](/docs/agents/mcp).
	187	+Branch protection and agent guardrails apply to all of them, as for a `git push`. Push protection does too: the web editor, `PUT .../contents`, `POST .../diffinery/commits`, MCP `commit_files` (and `POST .../git/blobs`) scan the new content for credentials before anything is written, and refuse it with HTTP 422 and `push protection: possible secret detected (...)`. A repository admin who is a person can commit a flagged file anyway through `POST .../diffinery/commits` by adding `"allow_secrets": "<reason>"`; the bypass is recorded in the audit log and emailed to the repository's admins. See [Push protection](/docs/security/push-protection), [REST API](/docs/reference/rest-api) and [MCP](/docs/agents/mcp).
186	188
	189	+A workflow's `GITHUB_TOKEN` can use these endpoints when the job has `contents: write`, but it can't create, change or delete files under `.github/workflows/` or `.diffinery/workflows/`: that fails with ``refusing to allow a GitHub App to create or update workflow `<path>` without `workflows` permission``.
	190	+
187	191	## Commits
188	192
189	193	`/acme/website/commits/<ref>` lists the commits reachable from a branch, tag or commit, 30 per page, grouped by day ("Commits on October 13, 2026"), with Newer and Older buttons. Add `?path=src/app.ts` (the History button does this) to see only commits that changed that file or folder; the file history looks at the most recent 2,000 commits.

		@@ -37,19 +37,22 @@
37	37
38	38	LFS uses the same credentials as Git: a personal access token as the password, through your credential helper or `diffinery auth setup-git` (see [Git over HTTPS](/docs/repositories/git#authentication)).
39	39
	40	+If you also pass the token with `http.extraHeader` (as `actions/checkout` does when it keeps credentials), `git-lfs` sends that header and the batch response's `Authorization` header together on each transfer. Diffinery accepts the repeated header and uses the first value, so this works. A `Basic` credential that isn't valid base64 gets `401 malformed basic credentials`.
	41	+
40	42	\| Operation \| Needs \|
41	43	\| --- \| --- \|
42	44	\| Download from a public repository \| Nothing \|
43	45	\| Download from a private repository \| A token with at least the `read` scope, for an account with read access \|
44	46	\| Upload \| A token with the `write` or `admin` scope, for an account with write access. The repository must not be archived. \|
45	47
46		-The batch request is always a `POST`, but a batch request for `download` counts as a read, so anonymous callers (on public repositories), `read`-scoped tokens and job tokens can download LFS files. A batch request for `upload` and the `PUT` that sends the file are writes:
	48	+The batch request is always a `POST`, but a batch request for `download` counts as a read, so anonymous callers (on public repositories), `read`-scoped tokens and job tokens with `contents: read` can download LFS files. A batch request for `upload` and the `PUT` that sends the file are writes:
47	49
48	50	\| Caller \| Upload refused with \|
49	51	\| --- \| --- \|
50	52	\| No credentials \| `401 authentication required` (the `git-lfs` client then asks for credentials) \|
51	53	\| A `read`-scoped token \| `403 this token needs the write scope` \|
52		-\| A token whose account has less than write access, or a job token \| `403 write access required` \|
	54	+\| A token whose account has less than write access \| `403 write access required` \|
	55	+\| A workflow's job token without `contents: write` \| `403 Resource not accessible by integration (the workflow's GITHUB_TOKEN needs permissions: contents: write)` \|
53	56	\| Anyone, on an archived repository \| `403 repository is archived (read-only)` \|
54	57
55	58	Agents can upload LFS objects like any account with write access. Branch protection applies to the commits that reference the objects, not to the LFS upload itself.
		@@ -129,26 +132,26 @@
129	132
130	133	## Use LFS files in workflows
131	134
132		-The `actions/checkout` step in Diffinery workflows doesn't download LFS files: with `lfs: true` it prints the warning `Git LFS is not supported by the Diffinery checkout built-in; LFS pointers will not be resolved.` and leaves pointer files in the workspace.
	135	+As on GitHub, `actions/checkout` downloads LFS files when you set `lfs: true` (the default is `false`, which leaves pointer files in the workspace). With `submodules: true` or `recursive`, it also pulls the submodules' LFS files. Hosted runners have `git-lfs` installed:
133	136
134		-Download them in a step after the checkout. Hosted runners have `git-lfs` installed, and the checkout leaves the job's token configured for the repository's URL (unless you set `persist-credentials: false`), so this works without extra credentials:
135		-
136	137	```yaml
137	138	name: Build
138	139	on: push
139	140	jobs:
140	141	build:
141	142	runs-on: ubuntu-latest
	143	+ permissions:
	144	+ contents: read
142	145	steps:
143	146	- uses: actions/checkout@v4
144		- - name: Download LFS files
145		- run: git lfs pull
	147	+ with:
	148	+ lfs: true
146	149	- run: ls -lh assets/
147	150	```
148	151
149		-To download only some files, use `git lfs pull --include="assets/video/**"`. The job token can read the repository but not upload LFS objects; use a secret holding a personal or agent token to push from a workflow. On self-hosted runners, install `git-lfs` on the machine first.
	152	+You can also download them in a later step. The checkout leaves the job's token configured for the repository's URL (unless you set `persist-credentials: false`), so `git lfs pull` works without extra credentials. To download only some files, use `git lfs pull --include="assets/video/**"`.
150	153
151		-Other differences in the checkout step: `sparse-checkout` is also ignored with a warning (a full checkout is done). See [Compatibility with GitHub Actions](/docs/actions/compatibility).
	154	+The job token reads LFS files with `contents: read` (the default for new repositories) and uploads them with `contents: write`, as on GitHub. On self-hosted runners, install `git-lfs` on the machine first. See [Compatibility with GitHub Actions](/docs/actions/compatibility).
152	155
153	156	## Moving LFS files from GitHub
154	157
		@@ -184,5 +187,7 @@
184	187	\| Upload fails with HTTP 403 \| Your token is `read`-scoped (`this token needs the write scope`), your role is below write (`write access required`), or the repository is archived (`repository is archived (read-only)`). Use a token with the `write` scope for an account with write access. \|
185	188	\| Upload fails with HTTP 401 \| The upload had no credentials (`authentication required`). Configure a credential helper or `diffinery auth setup-git`, as in [Endpoint and authentication](#endpoint-and-authentication). \|
186	189	\| Upload fails for a very large file \| Files over 100 MB can't be uploaded. Split the file, or keep it outside the repository. \|
187		-\| Workflow sees small text files instead of the real files \| The checkout step doesn't fetch LFS files. Add a `git lfs pull` step. \|
	190	+\| Workflow sees small text files instead of the real files \| The checkout step ran without `lfs: true`. Add `with: lfs: true` to `actions/checkout`, or a `git lfs pull` step after it. \|
	191	+\| Upload from a workflow fails with HTTP 403 `Resource not accessible by integration` \| The job's token has no `contents: write`. Add `permissions: contents: write` to the job. \|
	192	+\| Upload fails with HTTP 401 `malformed basic credentials` \| The `Authorization: Basic` value isn't valid base64. Check how the credential is built, or send `Authorization: Bearer dfy_...`. \|
188	193	\| `content does not match oid` \| The uploaded bytes didn't match the object ID, usually a corrupted local object. Run `git lfs fsck` and push again. \|

		@@ -72,7 +72,7 @@
72	72
73	73	The empty entry resets the helper list for this host, so a generic helper such as your OS keychain doesn't answer first. The helper answers only for the configured Diffinery host and protocol, with username `x-token` and the token from the config file or the `DIFFINERY_TOKEN` environment variable. It never stores anything (`store` and `erase` are no-ops), so revoking or replacing the token takes effect at once. The `diffinery` command must be on your `PATH` for Git to run it.
74	74
75		-> Note: Git only asks a credential helper (or you) for a token when the server answers `401`. Private repositories do that. When you push to a public repository without credentials, the server answers `403` (`write access required`) instead, so Git never asks and the push fails with `The requested URL returned error: 403`. Pass the token with the push itself, for example `git -c http.extraHeader="Authorization: Bearer $DIFFINERY_TOKEN" push`, as shown in [Other ways to pass the token](#other-ways-to-pass-the-token).
	75	+Git only asks a credential helper (or you) for a token when the server answers `401`. Diffinery answers `401 authentication required` with a `WWW-Authenticate: Basic realm="Diffinery"` challenge to every anonymous push, to public repositories too, and to every anonymous clone or fetch of a private repository. So you can clone a public repository without credentials and push to it later: Git asks the helper for the token at the first push.
76	76
77	77	`diffinery repo clone acme/website` clones with the token passed as a one-off HTTP header that is never written to `.git/config`.
78	78
		@@ -84,7 +84,7 @@
84	84	\| Header for one command \| `git -c http.extraHeader="Authorization: Bearer $DIFFINERY_TOKEN" clone https://diffinery.com/acme/website.git` \| Good for CI. Nothing is saved. \|
85	85	\| Token in the URL \| `https://x-token:dfy_...@diffinery.com/acme/website.git` \| Works, but the token ends up in `.git/config` and shell history. Avoid outside throwaway jobs. \|
86	86
87		-Inside Diffinery Actions, `actions/checkout` authenticates with the job's own token automatically. That token can read the repository but not push to it (see [Job tokens](#job-tokens)).
	87	+Inside Diffinery Actions, `actions/checkout` authenticates with the job's own token automatically. Whether that token can push depends on the workflow's `permissions:` (see [Job tokens](#job-tokens)).
88	88
89	89	### Token scopes and roles
90	90
		@@ -100,8 +100,29 @@
100	100
101	101	### Job tokens
102	102
103		-Each Actions job gets a token (`GITHUB_TOKEN`, starting with `djt_`). It works for Git and the REST API on the job's own repository only, with read access, and stops working when the job completes. A workflow can clone and fetch its repository but can't push to it with this token. To push from a workflow, store a personal or agent token as a secret and use that. This differs from GitHub, where `GITHUB_TOKEN` can push when the workflow has `contents: write`.
	103	+Each Actions job gets a token (`GITHUB_TOKEN`, starting with `djt_`) that works for Git and the REST API and stops working when the job completes. As on GitHub, what it may do over Git follows the workflow's `permissions:`:
104	104
	105	+\| `contents` permission \| Git with the job token \|
	106	+\| --- \| --- \|
	107	+\| `read` \| Clone and fetch the job's repository \|
	108	+\| `write` \| Also push to it \|
	109	+\| `none` \| Nothing on a private repository; a public one can still be cloned, as anyone can \|
	110	+
	111	+Without `permissions:` in the workflow, the job gets the repository's default: `contents: read` for repositories created now, write for repositories created before the setting existed. A repository admin changes the default with `PUT /api/v3/repos/{owner}/{repo}/actions/permissions/workflow`; see [Workflow permissions](/docs/actions/workflow-permissions). To push from a workflow, ask for it:
	112	+
	113	+```yaml
	114	+permissions:
	115	+ contents: write
	116	+```
	117	+
	118	+Pushes with a job token have these limits:
	119	+
	120	+- The token acts with at most the write role, so branch protection always applies to it.
	121	+- It can never create, change or delete files under `.github/workflows/` or `.diffinery/workflows/`. Git rejects the ref with the reason: refusing to allow a GitHub App to create or update workflow `<path>` without `workflows` permission. Use a personal token for that.
	122	+- If the run's code came from an agent (an agent triggered the run, pushed the branch last, or opened the pull request, or the run re-runs or follows through `workflow_run` such a run), the token acts as an agent: it can't push to the default branch or a protected branch (`agents may not push to protected or default branches; open a pull request`).
	123	+- A push made with a job token starts no new `push` workflows, as on GitHub.
	124	+- The token can also clone other public repositories (for example public submodules), but no other private repository.
	125	+
105	126	## Protocol versions
106	127
107	128	\| Operation \| Protocol \| Notes \|
		@@ -194,7 +215,7 @@
194	215
195	216	Every push goes through these steps, in this order. If an earlier step fails, nothing after it happens.
196	217
197		-1. Authorization. You must send a token: pushes without credentials are refused. Your account needs write access, your token the `write` or `admin` scope, and the repository must not be archived. Otherwise the server answers HTTP 401 (`authentication required`, when a private repository gets no credentials, which makes Git ask for them) or HTTP 403 (`write access required` when your role or a `read`-scoped token only allows reading, or `repository is archived (read-only)`). Git shows these as `Authentication failed` or `The requested URL returned error: 403`.
	218	+1. Authorization. You must send a token: a push without credentials gets HTTP 401 (`authentication required`) with a `WWW-Authenticate` challenge, for public and private repositories alike, which makes Git ask for credentials and retry. Your account needs write access, your token the `write` or `admin` scope, and the repository must not be archived. Otherwise the server answers HTTP 403 (`write access required` when your role only allows reading, `this token needs the write scope` for a `read`-scoped token, or `repository is archived (read-only)`), or HTTP 404 if the account can't see the repository at all. Git shows these as `Authentication failed` or `The requested URL returned error: 403`.
198	219	2. Size check. A push larger than 100 MB is refused. Git shows `remote unpack failed: push exceeds 100 MB; split it into smaller pushes`, or an HTTP error if the request is stopped before it reaches Diffinery.
199	220	3. Unpacking. The pack is parsed and every object checked.
200	221	4. Push protection. New text files under 1 MB are scanned for credentials such as AWS keys, GitHub and Diffinery tokens, Slack and Stripe keys, Google, Anthropic and OpenAI API keys, and private keys. If any are found, the whole push is rejected, nothing from it is stored, and the output lists each finding:
		@@ -294,7 +315,7 @@
294	315	\| `--deepen` \| Behaves like `--depth`. \|
295	316	\| Packs sent to clients \| Sent without deltas, so clones and fetches download more bytes than from GitHub. \|
296	317	\| Signed pushes \| Not supported. Signed commits push normally. \|
297		-\| `GITHUB_TOKEN` in workflows \| Read-only; can't push. \|
	318	+\| `GITHUB_TOKEN` in workflows \| Follows `permissions:` as on GitHub (`contents: write` to push), but new repositories default to read-only, it never changes workflow files, and code from an agent is held to the agent rules. \|
298	319	\| Repository rename or transfer \| The old URL keeps working, as on GitHub: clones, fetches and pushes are served under the old name, and a push prints `This repository moved. Please use the new location:` with the new URL. Update remotes anyway. \|
299	320	\| `refs/pull/*` \| Same as GitHub: fetchable, not pushable, hidden from `push --mirror`. \|
300	321	\| Ref names \| Must start with `refs/` and follow Git's ref name rules, otherwise `invalid ref name`. \|
		@@ -308,8 +329,10 @@
308	329	\| `The requested URL returned error: 400` on clone or fetch \| Git is older than 2.26 or protocol v2 is turned off. The server's message is `Diffinery requires Git protocol v2 (git 2.26 or newer, or run: git config --global protocol.version 2)`. \| Update Git, or run `git config --global protocol.version 2`. \|
309	330	\| `Authentication failed` after entering a password \| You entered a password instead of a token, the token expired or was revoked (`invalid, expired or revoked token`), or it isn't a `dfy_` token (`unrecognised token; create one under Settings → Access tokens`). \| Create a token under Settings → Access tokens and use it as the password. Clear the old one from your credential helper (for example `git credential reject`, or your keychain). \|
310	331	\| `repository '...' not found` for a repository you can see in the browser \| The token belongs to another account, is restricted to other repositories, or Git sent stale credentials. \| Check with `diffinery whoami` and `diffinery token list`. \|
311		-\| `The requested URL returned error: 403` on push \| Your role or your token's scope only allows reading (`write access required`), or the repository is archived (`repository is archived (read-only)`). \| Ask an admin for write access, use a `write` token, or unarchive the repository. \|
312		-\| `The requested URL returned error: 403` when pushing to a public repository, and Git never asked for a token \| Git sent no credentials. For a public repository the server answers an anonymous push with `403` (`write access required`), not `401`, so neither Git nor your credential helper offers a token. \| Send the token with the push: `git -c http.extraHeader="Authorization: Bearer $DIFFINERY_TOKEN" push origin main`. \|
	332	+\| `The requested URL returned error: 403` on push \| Your role or your token's scope only allows reading (`write access required`, `this token needs the write scope`), or the repository is archived (`repository is archived (read-only)`). \| Ask an admin for write access, use a `write` token, or unarchive the repository. \|
	333	+\| Git asks for a username and password when you push to a public repository you cloned without credentials \| Expected: anonymous pushes get `401`, so Git asks for credentials. \| Enter any username and your token as the password, or set up a credential helper with `diffinery auth setup-git`. \|
	334	+\| `The requested URL returned error: 403` on push from a workflow \| The job's token has no `contents: write` (`Resource not accessible by integration`). \| Add `permissions: contents: write` to the workflow or job, or have an admin change the repository's default workflow permissions. \|
	335	+\| `[remote rejected] ... (refusing to allow a GitHub App to create or update workflow ...)` \| A workflow's job token tried to push a change to a workflow file. \| Push workflow changes with a personal or agent token instead. \|
313	336	\| `remote unpack failed: push exceeds 100 MB; split it into smaller pushes` \| The pack for this push is larger than 100 MB. \| Push history in steps, oldest first, for example `git push origin <older-commit>:refs/heads/main`, then later commits. Move large binaries to Git LFS. \|
314	337	\| `[remote rejected] ... (secret detected (push protection))` \| A pushed file contains something that looks like a credential. \| Remove it from every commit in the push (`git commit --amend`, or `git rebase -i`), rotate the credential, and push again. See [Push protection](/docs/security/push-protection). \|
315	338	\| `[remote rejected] ... (fetch first (stale info))` \| The branch moved since you fetched. \| `git pull --rebase` (or fetch and merge), then push. \|

		@@ -19,14 +19,14 @@
19	19	\| Event \| Sent when \| Actions \|
20	20	\|---\|---\|---\|
21	21	\| `push` \| A branch or tag is created, updated or deleted, by `git push`, the web editor, the contents or Git data API, MCP, a merge, the merge queue, or a release that creates its tag \| none \|
22		-\| `pull_request` \| A pull request is opened, updated, edited, closed, merged, reopened, assigned, gets a review request, is marked ready for review or converted to a draft, or enters or leaves the merge queue \| `opened`, `synchronize`, `edited`, `closed`, `reopened`, `assigned`, `review_requested`, `ready_for_review`, `converted_to_draft`, `enqueued`, `dequeued` \|
	22	+\| `pull_request` \| A pull request is opened, updated, edited, closed, merged, reopened, assigned, gets a review request, is marked ready for review or converted to a draft, enters or leaves the merge queue, or has auto-merge turned on or off \| `opened`, `synchronize`, `edited`, `closed`, `reopened`, `assigned`, `review_requested`, `ready_for_review`, `converted_to_draft`, `enqueued`, `dequeued`, `auto_merge_enabled`, `auto_merge_disabled` \|
23	23	\| `pull_request_review` \| A review is submitted \| `submitted` \|
24	24	\| `issues` \| An issue is opened, edited (title or body), closed, reopened or assigned \| `opened`, `edited`, `closed`, `reopened`, `assigned` \|
25	25	\| `issue_comment` \| A comment is added to an issue or a pull request \| `created` \|
26	26	\| `workflow_run` \| A workflow run is created or finishes \| `requested`, `completed` \|
27	27	\| `release` \| A release is created, published, edited, unpublished or deleted, including drafts \| `created`, `published`, `released`, `prereleased`, `edited`, `unpublished`, `deleted` \|
28	28	\| `status` \| A commit status is posted \| none \|
29		-\| `deployment` \| A deployment is created with the REST API \| `created` \|
	29	+\| `deployment` \| A deployment is created, with the REST API or by a workflow job with `environment:` \| `created` \|
30	30	\| `deployment_status` \| A deployment gets a new status, from the REST API or from a workflow job with `environment:` \| `created` \|
31	31	\| `repository_dispatch` \| Someone calls `POST /repos/{owner}/{repo}/dispatches` \| the `event_type` that was sent \|
32	32	\| `workflow_dispatch` \| Someone starts a workflow by hand (web UI, CLI, REST API or MCP) \| none \|
		@@ -170,7 +170,7 @@
170	170	\| `X-GitHub-Delivery` \| A unique id for this delivery: 32 hexadecimal characters \|
171	171	\| `X-Hub-Signature-256` \| `sha256=` followed by the hex HMAC-SHA256 of the raw body, keyed with the webhook's secret \|
172	172
173		-The body is compact JSON (no extra whitespace). Every payload has `repository` and `sender` objects; `repository.id` is a number, like GitHub's. See [Webhook events](/docs/reference/webhook-events).
	173	+The body is compact JSON (no extra whitespace). Every payload has `repository` and `sender` objects. `repository` is GitHub's full repository object, the same one `GET /api/v3/repos/{owner}/{repo}` returns: its `id` is a number, and `private` and `visibility` give the repository's real visibility (`false` and `public` for a public repository). See [Webhook events](/docs/reference/webhook-events#the-repository-object).
174	174
175	175	### Timeouts, redirects and retries
176	176
		@@ -180,7 +180,7 @@
180	180	\| Redirects \| Not followed. A `3xx` response is recorded as that status and counts as failed. Use the final URL. \|
181	181	\| Success \| Any `2xx` status. The response body is ignored. \|
182	182	\| Failed deliveries \| Recorded (the status, or `0` for a timeout, DNS or connection error). Network errors, timeouts, `408`, `429` and `5xx` are retried; see [Retries](#retries). Other statuses are not. \|
183		-\| Duplicates \| A retry repeats the same delivery with the same `X-GitHub-Delivery` id, so your endpoint can see a delivery again if it processed it but answered too slowly or with an error. Separately, if Diffinery's own processing of an event fails, the event is processed again (up to 8 times, with a growing delay of up to 5 minutes), which delivers it again with a new `X-GitHub-Delivery` id. Make your handler idempotent, for example by remembering delivery ids. \|
	183	+\| Duplicates \| A retry repeats the same delivery with the same `X-GitHub-Delivery` id, so your endpoint can see a delivery again if it processed it but answered too slowly or with an error. Diffinery's own failures don't cause new deliveries: webhooks and notifications for an event are handled separately, and a step that fails before any webhook was called (for example while loading the repository's webhooks) is tried again on its own after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 1 hour. Still, make your handler idempotent, for example by remembering delivery ids. \|
184	184	\| Order \| Deliveries are not guaranteed to arrive in the order the events happened. Use the `at` timestamp in the payload, or the `created_at` and `updated_at` fields of the GitHub-shaped events. \|
185	185
186	186	Respond quickly with a `2xx` and do slow work afterwards, so that deliveries don't time out.
		@@ -301,7 +301,7 @@
301	301	- The same headers: `X-GitHub-Event`, `X-GitHub-Delivery` and `X-Hub-Signature-256`, plus `X-Diffinery-Event`.
302	302	- The same signature scheme (HMAC-SHA256, `sha256=` prefix, hex).
303	303	- The same event names and the same `action` values for the actions Diffinery sends.
304		-- Payloads have GitHub-style `repository` (with a numeric `id` and a `node_id`), `sender`, `pull_request` and `issue` objects, and `pull_request.merged` on `closed`.
	304	+- Payloads have GitHub's full `repository` object (numeric `id`, `node_id`, `owner`, `private`, `visibility`, `default_branch`, URLs and so on), a `sender`, GitHub-style `pull_request` and `issue` objects, and `pull_request.merged` on `closed`.
305	305	- `release`, `status`, `deployment`, `deployment_status` and `repository_dispatch` payloads have GitHub's structure, with the release, status and deployment fields GitHub receivers read. `workflow_dispatch` has GitHub's `inputs`, `ref` and `workflow` fields.
306	306	- The hooks API returns GitHub's hook object (`type`, `name`, `config`, `last_response`, ...).
307	307
		@@ -328,7 +328,9 @@
328	328	- Payload URLs must use HTTPS.
329	329	- The secret is stored with the webhook and is shown only once in the web UI (and returned once by the create API). Use a long random value, and keep it in your receiver's secret store.
330	330	- Verify the signature on every request, and reject requests without one.
331		-- Creating a webhook from the web UI is recorded in the [audit log](/docs/security/audit-log) as `repo.webhook.create`, and deleting one as `repo.webhook.delete`.
	331	+- Creating a webhook is recorded in the [audit log](/docs/security/audit-log) as `repo.webhook.create`, and deleting one as `repo.webhook.delete`, both from the web UI and from the API (API changes carry `"via": "api"` in the detail).
	332	+- On an archived repository, webhooks can't be created or deleted: the request fails with `403` and `repository is archived (read-only)`.
	333	+- Payloads from a private repository say so (`"private": true`, `"visibility": "private"`), so a receiver can decide what it may show or forward.
332	334	- Payloads never contain Actions secrets, tokens or file contents.
333	335
334	336	## Troubleshooting
		@@ -344,6 +346,6 @@
344	346	\| No `edited` event after changing labels \| `edited` is sent only when the title or body changes. Label changes send no webhook event. \|
345	347	\| No `release`, `status` or `deployment` deliveries \| The webhook was created in the web UI with individual events checked, which can't include these. Recreate it with Everything checked, or with the API listing the events. \|
346	348	\| Three `release` deliveries for one new release \| Publishing a release sends `created`, `published` and `released` (or `prereleased`), like GitHub. Act on the one you need, usually `published`. \|
347		-\| No `deployment` event for a workflow job with `environment:` \| Jobs record their deployment without a `deployment` event; they send `deployment_status` events (`in_progress` when the job starts, then `success`, `failure` or `inactive`). \|
	349	+\| A `deployment` and a `deployment_status` delivery for one workflow job \| A job with `environment:` creates a deployment when it starts (`deployment` with `created`) and reports its progress as `deployment_status` events (`in_progress` when the job starts, then `success`, `failure` or `inactive`), as on GitHub. \|
348	350	\| `config.url is required` \| Send the payload URL as `config.url`, not as a top-level `url`. \|
349	351	\| A webhook stopped receiving events \| Check that it still exists on the Webhooks page and that the events it subscribes to are the ones you expect. \|

		@@ -1,9 +1,9 @@
1	1	---
2	2	title: Push protection
3		-description: How Diffinery scans git pushes and API file writes for leaked credentials, what a blocked push looks like, and how to opt out or bypass the check.
	3	+description: How Diffinery scans git pushes, imported history, web editor commits and API and MCP writes for leaked credentials, and how to opt out or bypass.
4	4	---
5	5
6		-Push protection scans the files in every `git push` for credentials such as cloud keys, API tokens and private keys, and rejects the whole push if it finds one. It also scans files written through the REST API's contents and git data endpoints. It is always on for every repository: there is nothing to enable, and nothing from a blocked push or write is stored.
	6	+Push protection scans the files in every `git push` for credentials such as cloud keys, API tokens and private keys, and rejects the whole push if it finds one. The same scan runs on every commit made without a Git client: the web editor, `POST /repos/{owner}/{repo}/diffinery/commits`, the contents API and the MCP `commit_files` tool, and on files written through the git data API. It is always on for every repository: there is nothing to enable, and nothing from a blocked push or write is stored. History brought in by an [import from GitHub](/docs/migrate-from-github) is scanned too (see [Imported history](#imported-history)).
7	7
8	8	## How it works
9	9
		@@ -45,17 +45,17 @@
45	45	\| Scanned \| Not scanned \|
46	46	\|---\|---\|
47	47	\| Blobs (file contents) contained in the packfile of a `git push` \| Commits, trees and tags themselves (commit messages are not scanned) \|
48		-\| In a push, text files smaller than 1 MiB (1,048,576 bytes) \| In a push, blobs of 1 MiB or more \|
	48	+\| In a push, text files smaller than 1 MiB (1,048,576 bytes) \| In a push or a commit made without Git, files of 1 MiB or more \|
49	49	\| Every ref in the push: branches and tags \| Binary files: any blob that contains a NUL byte anywhere \|
50		-\| Files written with `PUT /repos/{owner}/{repo}/contents/{path}` \| Files that contain the text `diffinery:allow-secret` (see [Opting a file out](#opting-a-file-out)) \|
51		-\| Blobs created with `POST /repos/{owner}/{repo}/git/blobs`, and inline `content` in `POST /repos/{owner}/{repo}/git/trees` \| Objects the server already has, which git does not send again \|
52		-\| \| Git LFS objects, which are uploaded separately from the push \|
53		-\| \| Release assets \|
54		-\| \| The web editor, `POST /repos/{owner}/{repo}/diffinery/commits` and the MCP `commit_files` tool \|
	50	+\| Files you add or change in the web editor \| Files that contain the text `diffinery:allow-secret` (see [Opting a file out](#opting-a-file-out)) \|
	51	+\| Files in a commit made with `POST /repos/{owner}/{repo}/diffinery/commits` or the MCP `commit_files` tool \| Objects the server already has, which git does not send again \|
	52	+\| Files written with `PUT /repos/{owner}/{repo}/contents/{path}` \| Git LFS objects, which are uploaded separately from the push \|
	53	+\| Blobs created with `POST /repos/{owner}/{repo}/git/blobs`, and inline `content` in `POST /repos/{owner}/{repo}/git/trees` \| Release assets \|
	54	+\| \| Deleted files \|
55	55
56	56	Pushes larger than 100 MB are refused before scanning with `push exceeds 100 MB; split it into smaller pushes`.
57	57
58		-> Important: Push protection is a safety net, not a guarantee. It finds only the formats listed above, and changes made through the web editor, `POST /repos/{owner}/{repo}/diffinery/commits` or MCP are not scanned. Never rely on it as your only defense: keep secrets in [Actions secrets](/docs/actions/secrets-and-variables) and out of your repository.
	58	+> Important: Push protection is a safety net, not a guarantee. It finds only the formats listed above, in text files under 1 MiB. Never rely on it as your only defense: keep secrets in [Actions secrets](/docs/actions/secrets-and-variables) and out of your repository.
59	59
60	60	## When a push is blocked
61	61
		@@ -114,29 +114,58 @@
114	114
115	115	4. Push again.
116	116
117		-## Writes through the REST API
	117	+## Commits and writes without Git
118	118
119		-The GitHub-compatible file endpoints run the same scan on each file they write:
	119	+Commits made without a Git client run the same scan before anything is written. This covers:
120	120
121		-\| Endpoint \| What is scanned \|
	121	+\| Where \| What is scanned \|
122	122	\|---\|---\|
	123	+\| The web editor (Commit changes on a new or edited file) \| The file's new content \|
	124	+\| `POST /repos/{owner}/{repo}/diffinery/commits` \| Every file in `files` that isn't a delete \|
	125	+\| The MCP `commit_files` tool \| Every file in `files` \|
123	126	\| `PUT /repos/{owner}/{repo}/contents/{path}` \| The new file content \|
124	127	\| `POST /repos/{owner}/{repo}/git/blobs` \| The blob \|
125	128	\| `POST /repos/{owner}/{repo}/git/trees` \| Each tree entry given with inline `content`; entries given by `sha` refer to blobs already stored and are not scanned again \|
126	129
127		-The patterns, the binary-file rule and the `diffinery:allow-secret` opt-out are the same as for pushes. The 1 MiB limit does not apply: every text file is scanned, whatever its size.
	130	+The patterns, the binary-file rule and the `diffinery:allow-secret` opt-out are the same as for pushes. Commits (the first four rows) skip files of 1 MiB or more, as pushes do. The git data endpoints (`git/blobs` and `git/trees`) scan every text file, whatever its size.
128	131
129		-When a file matches, the request fails with `422` and nothing is stored:
	132	+### When a commit is refused
130	133
	134	+A commit that contains a credential fails with `422` and nothing is stored. For the web editor, the commits API, the contents API and MCP, the message names the types and up to 10 paths:
	135	+
131	136	```json
132	137	{
133		- "message": "push protection: possible secret detected (AWS access key)",
	138	+ "message": "push protection: possible secret detected (AWS access key) in config/deploy.env. Remove it, or rotate it and ask an admin.",
134	139	"documentation_url": "https://docs.github.com/rest"
135	140	}
136	141	```
137	142
138		-There is no bypass for API writes, not even for repository admins. If the file really must contain the value, add the `diffinery:allow-secret` marker to it, or push it with git and use [the bypass](#bypassing-push-protection). Each refused write is recorded in the [audit log](/docs/security/audit-log) as `api.blocked_secret` with the repository as the target and the detected types as detail. No email is sent for it.
	143	+The web editor shows the same message above the form and keeps your edit, so you can remove the value and commit again. If you sent `allow_secrets` but aren't allowed to bypass, the message ends with `Only repository admins (people, not agents) can bypass push protection.`
139	144
	145	+The git data endpoints answer `422` with the shorter `push protection: possible secret detected (AWS access key)`.
	146	+
	147	+Each refused write is recorded in the [audit log](/docs/security/audit-log) as `api.blocked_secret`, against the person or agent who made the request, with the repository as the target and the detected types and paths (or, for the git data API, the blob id) as detail. No email is sent for it.
	148	+
	149	+### Bypassing with the commits API
	150	+
	151	+A repository admin who is a person can commit a flagged file anyway through `POST /repos/{owner}/{repo}/diffinery/commits` by giving a reason in `allow_secrets`, the API counterpart of `git push -o allow-secrets=`:
	152	+
	153	+```sh
	154	+curl -X POST https://diffinery.com/api/v3/repos/acme/website/diffinery/commits \
	155	+ -H "Authorization: Bearer dfy_..." \
	156	+ -H "Content-Type: application/json" \
	157	+ -d '{
	158	+ "branch": "main",
	159	+ "message": "Add migration test fixture",
	160	+ "allow_secrets": "revoked key kept in a migration test",
	161	+ "files": [{ "path": "test/fixtures/old-key.txt", "content": "AKIA..." }]
	162	+ }'
	163	+```
	164	+
	165	+The same [requirements](#who-can-bypass) apply as for a push: the admin role on the repository, a person rather than an agent, a token with the `admin` scope, and a non-empty reason (trimmed and cut to 200 characters). A bypassed commit is recorded in the audit log as `api.secret_bypassed`, with the detected types, the paths and your reason, and the `[acme/website] Push protection was bypassed` email goes to you and to the repository's admins.
	166	+
	167	+The web editor, the contents API, the git data API and MCP have no bypass. If a file really must contain the value, add the `diffinery:allow-secret` marker to it, commit it with `allow_secrets` through the commits API, or push it with git and use [the bypass](#bypassing-push-protection).
	168	+
140	169	## Opting a file out
141	170
142	171	Test fixtures sometimes need values that look like real keys. To let such a file through, put the text `diffinery:allow-secret` anywhere in it, usually in a comment:
		@@ -152,7 +181,7 @@
152	181
153	182	## Bypassing push protection
154	183
155		-A repository admin who is a person can push a flagged change anyway by giving a reason with a git push option:
	184	+A repository admin who is a person can push a flagged change anyway by giving a reason with a git push option (for commits made through the API, see [Bypassing with the commits API](#bypassing-with-the-commits-api)):
156	185
157	186	```sh
158	187	git push -o allow-secrets="revoked key kept in a migration test" origin main
		@@ -182,6 +211,39 @@
182	211
183	212	Bypassing does not make a real credential safe: anyone who can read the repository can read it. Rotate real credentials even after a bypass.
184	213
	214	+## Imported history
	215	+
	216	+An [import from GitHub](/docs/migrate-from-github) copies a repository's Git history by pushing it into Diffinery in chunks, and push protection scans every one of those pushes like any other: each new blob under 1 MiB, with the same patterns and the same `diffinery:allow-secret` opt-out. Git LFS objects and release assets are not scanned, as for any push. Old history often holds credentials that were committed and removed later, so every import has a setting for what happens when push protection finds one:
	217	+
	218	+\| Web form choice (under Secrets found in old history (push protection)) \| API, CLI and MCP value \| What happens \|
	219	+\|---\|---\|---\|
	220	+\| Import with an audited bypass (the default) \| `"options": {"secrets": "bypass"}` \| The import pushes with a bypass whose reason is `Imported from GitHub <owner>/<name>`. It works only when the import may bypass (see below); otherwise the import fails. \|
	221	+\| Stop the import \| `"options": {"secrets": "stop"}` \| The import fails at the first push with a finding, so you can rewrite the history on GitHub first. \|
	222	+
	223	+### Who can import past a finding
	224	+
	225	+An import pushes as the person or agent who started it, with the token scope they started it with (a browser session counts as `admin`). So the bypass follows the same rules as a `git push -o allow-secrets=...`:
	226	+
	227	+- The import was started by a person, not an agent. Agents never bypass push protection: an import an agent starts always uses `stop`, whatever it asks for.
	228	+- That person has the admin role on the new repository: it is in their own account, or in an organization they own or administer (site admins have it everywhere).
	229	+- They started the import in the web UI or with an `admin`-scoped token. With a `write` token the bypass is refused.
	230	+
	231	+When a finding stops an import, the import fails with one of these errors, and the import page and `GET /api/v3/diffinery/imports/{id}` show it:
	232	+
	233	+\| Error \| Why \|
	234	+\|---\|---\|
	235	+\| `Push protection found possible secrets in the history (<types>). The import was set to stop on secrets. Rotate them, then start a NEW import with the secrets option set to bypass (as a person who administers the target); a retry cannot change the options.` \| The import used `stop`, or an agent started it. \|
	236	+\| `Push protection found possible secrets in the history (<types>). Only a person who administers the target can import them with an audited bypass (agents and write-scoped tokens cannot); start a new import as such a person.` \| The import used `bypass`, but whoever started it can't bypass. \|
	237	+
	238	+The Git transfer isn't tried again after such a failure, and retrying the import doesn't help, because a retry keeps the options and runs as the same person or agent. Rotate the credentials, then start a new import (as a person who administers the target, with `bypass`), or rewrite the history on GitHub and import again. The failed import's repository stays, so delete it or give the new import another `name`.
	239	+
	240	+### What an imported bypass records
	241	+
	242	+- Each bypassed push writes a `push.secret_bypassed` entry to the [audit log](/docs/security/audit-log), with the person who started the import as the actor, the reason `Imported from GitHub <owner>/<name>`, and in its detail the import's id and up to 50 blob ids.
	243	+- The person who started the import and the repository's admins get the `[acme/website] Push protection was bypassed` email.
	244	+- The import's summary lists every finding with its type, the file path when the import agent saw one, and the blob id: on the import page under Possible secrets in history (rotate these), and as `summary.findings` in the API. Rotate these credentials. They are readable by anyone who can read the repository, and were already readable on GitHub.
	245	+- A push that push protection blocks during an import is recorded as `push.blocked_secret`, and the person who started the import (or the agent's owner) gets the `Your push was blocked: possible secrets` email.
	246	+
185	247	## Differences from GitHub push protection
186	248
187	249	Diffinery's push protection follows the same idea as GitHub's: scan at push time, block before anything is stored, and allow an audited bypass. The differences:
		@@ -190,10 +252,10 @@
190	252	\|---\|---\|---\|
191	253	\| Patterns \| A large catalog of provider patterns, plus custom patterns \| The nine types listed above; no custom patterns \|
192	254	\| Enabling \| A repository or organization setting \| Always on for every repository; cannot be turned off \|
193		-\| Bypass \| A link in the push output where you pick a reason, then push again \| `git push -o allow-secrets=<reason>` in the same push; repository admins who are people only \|
	255	+\| Bypass \| A link in the push output where you pick a reason, then push again \| `git push -o allow-secrets=<reason>` in the same push, or `allow_secrets` on `POST /repos/{owner}/{repo}/diffinery/commits`; repository admins who are people only \|
194	256	\| Excluding files \| Paths in `.github/secret_scanning.yml` \| A `diffinery:allow-secret` marker inside each file \|
195	257	\| Notification \| Secret scanning alerts in the repository \| Audit log entries and email to the pusher (and to admins on a bypass) \|
196		-\| Existing history \| Secret scanning can also scan existing content \| Only new blobs in each push (and each file written through the contents and git data APIs) are scanned \|
	258	+\| Existing history \| Secret scanning can also scan existing content \| Only new blobs in each push, and each file written through the web editor, the commits, contents and git data APIs and MCP, are scanned. History imported from GitHub is scanned as it is pushed in. \|
197	259
198	260	## Troubleshooting
199	261
		@@ -203,6 +265,8 @@
203	265	\| The push is still blocked after you deleted the file in a new commit \| The secret is still in an earlier commit you are pushing. Rewrite the commit that added it instead of adding a commit on top. \|
204	266	\| `Only repository admins (people, not agents) can bypass push protection.` \| You used `-o allow-secrets=...` without being allowed. Check your role, that you are not using an agent's token, and that your token has the `admin` scope. \|
205	267	\| `-o allow-secrets=` seems to be ignored \| The reason is empty. Give a non-empty reason, for example `-o allow-secrets="test fixture"`. \|
206		-\| A real key was not caught \| It is not one of the formats above, it is in a binary file or in a pushed file of 1 MiB or more, the file contains `diffinery:allow-secret`, or the change was made with the web editor, `diffinery/commits` or MCP. Rotate the key and remove it. \|
207		-\| `push protection: possible secret detected (...)` (422) from the API \| A file you wrote with the contents or git data API matched. Remove the value, or mark a test fixture with `diffinery:allow-secret`. API writes have no bypass. \|
	268	+\| A real key was not caught \| It is not one of the formats above, it is in a binary file or in a pushed or committed file of 1 MiB or more, or the file contains `diffinery:allow-secret`. Rotate the key and remove it. \|
	269	+\| `push protection: possible secret detected (...)` (422) from the API, MCP or the web editor \| A file you committed or wrote matched. Remove the value, or mark a test fixture with `diffinery:allow-secret`. A repository admin who is a person can commit it anyway with `allow_secrets` on `POST /repos/{owner}/{repo}/diffinery/commits`; the other endpoints have no bypass. \|
	270	+\| `... Only repository admins (people, not agents) can bypass push protection.` (422) from the commits API \| You sent `allow_secrets` without being allowed. Check your role, that you are not using an agent's token, and that your token has the `admin` scope. \|
	271	+\| An import from GitHub failed with `Push protection found possible secrets in the history (...)` \| The source's history contains credentials and the import couldn't bypass. See [Imported history](#imported-history). \|
208	272	\| `push exceeds 100 MB; split it into smaller pushes` \| The pack is over the push size limit. Push fewer commits at a time, or move large files to [Git LFS](/docs/repositories/git-lfs). \|

		@@ -22,6 +22,8 @@
22	22	/** The least token scope that may call it, and whether the token must cover every repository. */
23	23	scope: Scope;
24	24	accountWide: boolean;
	25	+ /** No token may call it: only a browser session. */
	26	+ sessionOnly: boolean;
25	27	}
26	28
27	29	const METHOD_ORDER = ["GET", "POST", "PUT", "PATCH", "DELETE"];
		@@ -35,9 +37,9 @@
35	37	const TAGS: Array<[string, RegExp]> = [
36	38	["Meta", /^\/(meta\|rate_limit)?$/],
37	39	["Users", /^\/users?(\/\{login\})?$\|^\/user\/(orgs\|avatar)$/],
38		- ["Organizations", /^\/orgs\/\{org\}\/(members\|invitations\|avatar)\|^\/invitations$/],
	40	+ ["Organizations", /^\/orgs\/\{org\}(\/(members\|invitations(\/\{id\})?\|avatar))?$\|^\/invitations(\/\{id\})?$/],
39	41	["Search", /^\/search\//],
40		- ["Repositories", /^\/(user\|users\/\{login\}\|orgs\/\{org\})\/repos$\|^\/repos\/\{owner\}\/\{repo\}$\|\/(collaborators\|assignees\|languages\|topics\|dispatches)(\/\|$)/],
	42	+ ["Repositories", /^\/(user\|users\/\{login\}\|orgs\/\{org\})\/repos$\|^\/repos\/\{owner\}\/\{repo\}(\/(collaborators\|invitations\|assignees\|languages\|topics\|dispatches)(\/\|$)\|$)/],
41	43	["Contents", /\/(contents\|raw\|readme\|tarball\|zipball\|diffinery\/commits)(\/\|$)/],
42	44	["Releases", /\/releases(\/\|$)/],
43	45	["Git database", /\/git\/(blobs\|trees\|commits\|tags\|refs\|ref\|matching-refs)(\/\|$)/],
		@@ -46,15 +48,17 @@
46	48	["Checks", /\/check-(runs\|suites)/],
47	49	["Commits", /\/(commits\|compare)(\/\|$)/],
48	50	["Branch protection", /\/protection$/],
49		- ["Issues", /\/(issues\|labels)(\/\|$)/],
	51	+ ["Issues", /\/(issues\|labels\|milestones)(\/\|$)/],
50	52	["Pull requests", /\/pulls(\/\|$)(?!.*merge-queue)/],
51	53	["Merge queue", /\/merge-queue/],
52	54	["Deployments", /\/deployments(\/\|$)/],
53	55	["Environments", /\/environments(\/\|$)/],
54	56	["Actions secrets and variables", /\/actions\/(secrets\|variables)/],
	57	+ ["Actions artifacts and caches", /\/actions\/(artifacts\|caches?)(\/\|$)\|\/actions\/runs\/\{runId\}\/artifacts$/],
55	58	["Actions", /\/actions\//],
56	59	["Webhooks", /\/hooks(\/\|$)/],
57	60	["Packages", /\/packages(\/\|$)/],
	61	+ ["Imports", /^\/diffinery\/(imports\|user\/linked-accounts\|admin\/linked-accounts)(\/\|$)/],
58	62	["Notifications and email", /^\/notifications$\|\/subscription$\|\/diffinery\/(notification-settings\|emails\|admin)/],
59	63	["Tokens and agents", /\/diffinery\/(tokens\|agents)/],
60	64	["Sandboxes", /\/diffinery\/sandboxes/],
		@@ -116,6 +120,7 @@
116	120	// A token's scope also caps its repository role (write → maintain), so admin endpoints need an admin token.
117	121	scope: ACCOUNT_SCOPES[key]?.scope ?? (doc?.access === "admin" ? "admin" : r.method === "GET" ? "read" : "write"),
118	122	accountWide: !!ACCOUNT_SCOPES[key] && !ACCOUNT_SCOPES[key]!.anyToken,
	123	+ sessionOnly: !!ACCOUNT_SCOPES[key]?.sessionOnly,
119	124	});
120	125	}
121	126	ops.sort((a, b) => TAG_ORDER.indexOf(a.tag) - TAG_ORDER.indexOf(b.tag) \|\| a.path.localeCompare(b.path) \|\| METHOD_ORDER.indexOf(a.method) - METHOD_ORDER.indexOf(b.method));
		@@ -133,12 +138,14 @@
133	138	maintain: "Maintain access to the repository.",
134	139	admin: "Admin access to the repository (or to the package).",
135	140	"org-admin": "An owner or admin of the organization (or a site admin).",
	141	+ "org-owner": "An owner of the organization (or a site admin).",
136	142	"site-admin": "A site administrator.",
137	143	};
138	144
139	145	/** What a personal access token needs; browser sessions always have full scope. */
140		-export function scopeText(op: Pick<ApiOperation, "scope" \| "accountWide" \| "doc">): string {
	146	+export function scopeText(op: Pick<ApiOperation, "scope" \| "accountWide" \| "sessionOnly" \| "doc">): string {
141	147	if (op.doc.access === "public") return "";
	148	+ if (op.sessionOnly) return "No token can call it: it needs a browser session.";
142	149	return `Tokens need the \`${op.scope}\` scope${op.accountWide ? " and access to all repositories" : ""}.`;
143	150	}
144	151
		@@ -156,10 +163,12 @@
156	163	name: "Name.",
157	164	type: "Package type: `container`.",
158	165	workflow: "Workflow file path (URL-encoded) or file name.",
	166	+ runId: "Workflow run id, or the run number (`github.run_id`).",
	167	+ format: "Archive format: `zip`.",
159	168	action: "Action to take.",
160	169	};
161	170
162		-const EXAMPLE: Record<string, string> = { owner: "acme", repo: "website", org: "acme", login: "diffy", number: "42", branch: "main", ref: "main", path: "README.md", spec: "main...feature", type: "container", name: "website", workflow: "ci.yml", action: "exec" };
	171	+const EXAMPLE: Record<string, string> = { owner: "acme", repo: "website", org: "acme", login: "diffy", number: "42", branch: "main", ref: "main", path: "README.md", spec: "main...feature", type: "container", name: "website", workflow: "ci.yml", action: "exec", runId: "42", format: "zip" };
163	172
164	173	function curl(origin: string, op: ApiOperation): string {
165	174	const url = `${origin}${API_BASE}${op.path === "/" ? "" : op.path.replace(/\{(\w+)\}/g, (_, p: string) => EXAMPLE[p] ?? (p === "id" ? "1" : p))}`;
		@@ -200,6 +209,9 @@
200	209	"- Authenticate with a personal access token: `Authorization: Bearer dfy_...` (`token dfy_...` and HTTP Basic with the token as the password work too). Create one under Settings → Access tokens.",
201	210	"- Send and receive JSON. Errors are JSON objects with a `message` and a `documentation_url`, unknown paths included (404).",
202	211	"- Reads of public repositories need no token. Every write needs a signed-in caller (401 otherwise) and, from a token, the `write` scope (403 otherwise). A token's scope also caps its role on a repository: `read` reads, `write` acts up to maintain, `admin` acts as admin. Each endpoint below says which scope it needs.",
	212	+ "- A private repository you can't see is a 404, whatever the method, so a read token's write to it doesn't reveal that it exists.",
	213	+ "- An archived repository refuses every write with 403 `repository is archived (read-only)`, except unarchiving it (`PATCH` with `archived: false`), deleting it and watching it.",
	214	+ "- A workflow job's `GITHUB_TOKEN` follows the job's `permissions:` instead of token scopes: each endpoint needs its permission (`contents`, `issues`, `pull-requests`, `actions` and so on), and settings, secrets, variables, webhooks and branch protection are out of its reach. See [Workflow permissions](/docs/actions/workflow-permissions).",
203	215	"- Paths, field names and status codes follow GitHub's REST API wherever Diffinery has the same feature, so most GitHub clients work with `baseUrl` set to the URL above.",
204	216	`- ${ops.length} endpoints in ${byTag.size} groups.`,
205	217	"",
		@@ -243,7 +255,7 @@
243	255	["POST /{owner}/{repo}.git/git-receive-pack", "Git smart HTTP: push."],
244	256	["POST /{owner}/{repo}.git/info/lfs/objects/batch", "Git LFS batch API. See [Git LFS](/docs/repositories/git-lfs)."],
245	257	["GET, PUT /{owner}/{repo}.git/info/lfs/objects/{oid}", "Git LFS object download and upload."],
246		- ["GET /{owner}/{repo}/actions/runs/{run_id}/artifacts/{name}", "Download a workflow artifact as `.tar.gz`."],
	258	+ ["GET /{owner}/{repo}/actions/runs/{run_id}/artifacts/{name}", "Download a workflow artifact by name or numeric id, for browsers (the run page links here). Serves a zip, the file itself for an artifact uploaded as a single unzipped file, or a `.tar.gz` for an artifact from an older runner. Expired artifacts aren't served."],
247	259	["POST /mcp", "The MCP server (Streamable HTTP, JSON-RPC). See [MCP](/docs/agents/mcp) and the [MCP tool reference](/docs/reference/mcp-tools)."],
248	260	["/v2/...", "The OCI container registry (Docker Registry HTTP API v2). See [Container registry](/docs/packages/container-registry)."],
249	261	["GET /.well-known/openid-configuration", "OIDC discovery for workflow ID tokens. See [OIDC](/docs/actions/oidc)."],
		@@ -308,7 +320,7 @@
308	320	...(body ? { requestBody: body } : {}),
309	321	...(access === "public" ? { security: [] } : {}),
310	322	"x-diffinery-access": access,
311		- "x-diffinery-token-scope": op.scope,
	323	+ "x-diffinery-token-scope": op.sessionOnly ? "none" : op.scope,
312	324	responses: {
313	325	[ok]: { description: ok === "204" ? "No content" : "Success", ...(ok === "204" \|\| ok === "205" ? {} : { content: { "application/json": { schema: {} } } }) },
314	326	default: { description: "Error", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } },
		@@ -359,6 +371,7 @@
359	371	["Issues", /issue\|comment\|label/],
360	372	["Actions", /workflow\|run\|job\|artifact/],
361	373	["Releases", /release/],
	374	+ ["Imports", /import/],
362	375	["Sandboxes", /sandbox/],
363	376	["Docs", /docs/],
364	377	];