Docs: importer rules after #51 (#52)
The repository lock covers every write (423 outside git), agents import where their owner may, a person who administers the target takes over an agent's retry, release imports don't duplicate, and the CLI prints a working command for environment secrets. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL
Canberk Demirci authored · GitHub committed signed1 parent ff1416ccommit c6be1859bf754665ef722f9b7459872134431ffaBrowse files
6 files changed+30−29
Files (6)
modifiedapps/diffinery/docs/admin/site-administration.md+1−1View file
| @@ -112,7 +112,7 @@ | ||
| 112 | 112 | |
| 113 | 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 | 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. | |
| 115 | +- **Retrying stays with the starter, except for agents' imports.** A person's import can be retried only by that person, even by a site administrator. An import an agent started can also be retried by any person who may import into the target, which includes site administrators. | |
| 116 | 116 | |
| 117 | 117 | ### Clear a GitHub link |
| 118 | 118 |
modifiedapps/diffinery/docs/agents/mcp.md+4−4View file
| @@ -280,19 +280,19 @@ | ||
| 280 | 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 | 281 | ``` |
| 282 | 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`. | |
| 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 other write to the new repository is refused: pushes with `repository is locked by an import in progress`, and tools such as `create_issue` with `repository is locked by an import in progress; try again when it finishes, or cancel the import`. | |
| 284 | 284 | |
| 285 | 285 | Who can start one: |
| 286 | 286 | |
| 287 | 287 | - The token needs the `write` or `admin` scope (`starting an import needs a token with write or admin scope`). |
| 288 | 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`). | |
| 289 | +- An agent can import only where its owner may: a person's agent into the owner's own account or an organization the owner owns or administers, an organization's agent into that organization (`agents can import only where their owner may: the owner's own account or an organization the owner administers, not <owner>`). Its maximum role must be at least `write` (`this agent's policy does not allow writing; an import needs at least write`). | |
| 290 | 290 | |
| 291 | 291 | Rules for imports an agent starts: |
| 292 | 292 | |
| 293 | 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 | 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. | |
| 295 | +- **No retry once the repository exists.** An agent's retry (through the REST API) is refused after the repository was created; a person who administers the target retries it instead. | |
| 296 | 296 | - The agent sees only the imports it started (`get_import`, `list_imports`). |
| 297 | 297 | |
| 298 | 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. |
| @@ -476,6 +476,6 @@ | ||
| 476 | 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. | |
| 477 | 477 | | `make_latest must be true, false or legacy` | Pass `make_latest` as one of those strings, not as a boolean. | |
| 478 | 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. | | |
| 479 | +| `agents can import only where their owner may: ...` | Pass as `owner` the owner's own account or an organization the owner administers (for an organization's agent, that organization). | | |
| 480 | 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`). | |
| 481 | 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`. | |
modifiedapps/diffinery/docs/agents/overview.md+6−6View file
| @@ -139,10 +139,10 @@ | ||
| 139 | 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. | |
| 140 | 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. | |
| 141 | 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. | | |
| 142 | +| Imports from GitHub only where the owner may import | A person's agent imports into the owner's own account or an organization the owner owns or administers; an organization's agent imports into that organization (`agents can import only where their owner may: ...`). Its maximum role must be at least `write`. | None. | | |
| 143 | 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 | 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. | | |
| 145 | +| No import retry once the repository exists | `an agent cannot retry an import after the repository was created; a person who administers <owner> must retry it` | A person who administers the target retries it. | | |
| 146 | 146 | |
| 147 | 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. |
| 148 | 148 | |
| @@ -192,14 +192,14 @@ | ||
| 192 | 192 | |
| 193 | 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 | 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. | |
| 195 | +- The target must be somewhere the agent's owner may import: for a person's agent, the owner's own account or an organization the owner owns or administers; for an organization's agent, that organization. | |
| 196 | 196 | - The agent's maximum role must be at least `write`, and its token needs the `write` scope. |
| 197 | 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 | 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. | |
| 199 | +- Once the repository exists, the agent can't retry a failed import; a person who administers the target retries it. | |
| 200 | 200 | - The agent sees only the imports it started. |
| 201 | 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). | |
| 202 | +Everything the import writes fires no workflows, webhooks or notifications, and the repository is locked against other writes 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 | 203 | |
| 204 | 204 | ## Disable an agent |
| 205 | 205 | |
| @@ -299,7 +299,7 @@ | ||
| 299 | 299 | | `name already taken` | Pick another login; agents share the namespace with people and organizations. | |
| 300 | 300 | | `not your agent` | Only the owner, or an owner or admin of the owning organization, can manage it. | |
| 301 | 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. | | |
| 302 | +| `agents can import only where their owner may: ...` | Import into the owner's own account or an organization the owner administers; an organization's agent imports only into that organization. | | |
| 303 | 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 | 304 | | `skipped (agents cannot manage variables)` on an import | Expected for an agent's import. A person sets variables, environments and secrets afterwards. | |
| 305 | 305 | | `invalid, expired or revoked token` | The token expired or was revoked, or the agent is disabled. Create a new token. | |
modifiedapps/diffinery/docs/migrate-from-github.md+16−15View file
| @@ -28,8 +28,8 @@ | ||
| 28 | 28 | Things to know: |
| 29 | 29 | |
| 30 | 30 | - **Nothing the import writes fires events.** No workflow runs start, no webhooks are delivered and nobody is notified about imported issues, comments or pushes. Your first push after the import starts workflows as usual. |
| 31 | -- **The repository is locked while the import runs.** Every push from anyone else is refused with `repository is locked by an import in progress` until the import finishes, fails or is cancelled. | |
| 32 | -- **Every write is keyed by GitHub's ids**, so a retried step or a retried import never duplicates issues, pull requests, comments, reviews, labels, milestones or branch protection rules. | |
| 31 | +- **The repository is locked while the import runs.** Until the import finishes, fails or is cancelled, only the import writes to it. A push from anyone else is refused with `repository is locked by an import in progress`, and any other change through the REST API, the web UI or MCP (an issue, a comment, a label, a setting, a transfer) gets `423 repository is locked by an import in progress; try again when it finishes, or cancel the import`. Reading the repository and watching it work as usual. | |
| 32 | +- **Every write is keyed by GitHub's ids**, so a retried step or a retried import never duplicates issues, pull requests, comments, reviews, labels, milestones, branch protection rules or releases (a release is matched by its tag and creation date, and assets already copied are kept). | |
| 33 | 33 | - **The import keeps running if you close the page or stop the CLI.** You get an entry in your notifications list when it succeeds (`Imported acme/website into acme/website`) or fails, linking to its page. |
| 34 | 34 | - **Every import is audited:** `import.create`, `import.push`, `import.finish`, `import.fail`, `import.cancel` and `import.retry` appear in the audit log. See [Audit log](/docs/security/audit-log). |
| 35 | 35 | |
| @@ -66,7 +66,7 @@ | ||
| 66 | 66 | | Organization variables and secret names (organization imports) | Admin access to the GitHub organization | |
| 67 | 67 | | Private repositories of a GitHub organization or user (organization imports) | Access to those repositories; the list includes private ones only when the token can see them | |
| 68 | 68 | |
| 69 | -When the token can't read something optional, the import carries on and records a warning, for example `Branch protection of main could not be read (the GitHub token needs admin access to the repository); set it up under Settings → Branches.` (on Diffinery the page is **Settings → Branch protection**). | |
| 69 | +When the token can't read something optional, the import carries on and records a warning, for example `Branch protection of main could not be read (the GitHub token needs admin access to the repository); set it up under Settings → Branch protection.` | |
| 70 | 70 | |
| 71 | 71 | How the token is handled: |
| 72 | 72 | |
| @@ -219,14 +219,15 @@ | ||
| 219 | 219 | |
| 220 | 220 | Imported acme/website → acme/website |
| 221 | 221 | |
| 222 | -GitHub does not reveal secret values. Set these 2 secrets by hand: | |
| 222 | +GitHub does not reveal secret values. Set these 3 secrets by hand: | |
| 223 | 223 | diffinery secret set NPM_TOKEN -R acme/website |
| 224 | 224 | diffinery secret set SENTRY_DSN -R acme/website |
| 225 | + diffinery api PUT /repos/acme/website/environments/production/secrets/DEPLOY_KEY -f value=... | |
| 225 | 226 | |
| 226 | 227 | https://diffinery.com/acme/website |
| 227 | 228 | ``` |
| 228 | 229 | |
| 229 | -Warnings are printed to standard error. Environment secret names are listed as `<environment>/<NAME>`, for example `production/DEPLOY_KEY`; set those with the environments API, not `diffinery secret set` (see [Environments and their secrets](#environments-and-their-secrets)). | |
| 230 | +Warnings are printed to standard error. Repository secrets get a `diffinery secret set` line. Environment secrets (`production/DEPLOY_KEY` in the summary) have no `secret set` option, so they get a `diffinery api PUT .../environments/<environment>/secrets/<NAME>` line instead (see [Environments and their secrets](#environments-and-their-secrets)). Replace `...` with the value, or pipe it in. | |
| 230 | 231 | |
| 231 | 232 | Stopping the command (Ctrl-C) stops following, not the import. Check on it at `https://diffinery.com/imports` or with `GET /api/v3/diffinery/imports`. |
| 232 | 233 | |
| @@ -392,7 +393,7 @@ | ||
| 392 | 393 | | `POST /api/v3/diffinery/imports/{id}/retry` | Run a failed or cancelled import again; body `{"github_token": "ghp_..."}` (optional) | `202` with the import | |
| 393 | 394 | | `POST /api/v3/diffinery/imports/{id}/selection` | Choose the repositories of a draft organization import (created in the web form) and start it; body `{"repositories": ["website", "docs"]}` | `202` with the import | |
| 394 | 395 | |
| 395 | -You can read an import if you started it, if you are a person who administers the account it imports into, or if you are a site administrator. The same people can cancel it. Only the person or agent who started it can retry it (see [Retries, cancelling and the repository lock](#retries-cancelling-and-the-repository-lock)). | |
| 396 | +You can read an import if you started it, if you are a person who administers the account it imports into, or if you are a site administrator. The same people can cancel it. Only whoever started it can retry it, except that a person who may import into the target can take over the retry of an agent's import (see [Retries, cancelling and the repository lock](#retries-cancelling-and-the-repository-lock)). | |
| 396 | 397 | |
| 397 | 398 | Poll an import until it finishes: |
| 398 | 399 | |
| @@ -583,24 +584,24 @@ | ||
| 583 | 584 | |
| 584 | 585 | **Retry** a failed or cancelled import with **Retry this import** on its page, or `POST /api/v3/diffinery/imports/{id}/retry`: |
| 585 | 586 | |
| 586 | -- Only the person or agent who started the import can retry it. Others get `404 import not found`, even admins of the target. | |
| 587 | +- Whoever started the import can retry it. The one exception is an import an agent started: a person who may import into the target (its owner, an owner or admin of the target organization, or a site administrator) can retry it too, and should once the repository exists. Anyone else gets `404 import not found`. | |
| 587 | 588 | - Give the GitHub token again for a private repository (or for LFS, variables and protection): the first run's token was deleted when it ended. Leave it out for a public repository. |
| 588 | 589 | - Retry the whole organization import, not one of its repositories (`retry the organization import this repository belongs to`). Its failed and cancelled repositories are retried; those that failed because the name already existed are not. |
| 589 | 590 | - The options can't change on a retry. |
| 590 | 591 | - Finished work isn't repeated or duplicated: steps write by GitHub id, and the Git transfer only sends what the repository doesn't have yet. |
| 591 | -- An agent can't retry once the repository was created (`an agent cannot retry an import after the repository was created; a person must retry it`). Because retry is limited to whoever started the import, a person then starts a new import instead. | |
| 592 | +- An agent can't retry once the repository was created (`an agent cannot retry an import after the repository was created; a person who administers acme must retry it`). A person who administers the target retries it with **Retry this import** or the API, giving the GitHub token again if the source is private. | |
| 592 | 593 | |
| 593 | -**The repository lock.** From the moment the import creates the repository until it finishes, fails or is cancelled, only the import may push to it; any other push gets `repository is locked by an import in progress`. The import itself may only create refs or move refs it wrote. A retry claims the repository again only when it holds nothing the import didn't write. If anyone pushed a branch, opened an issue, added a label or a protection rule in the meantime, the retry fails with `repository already holds content not written by this import; start a new import`. A failed or cancelled import leaves the partly imported repository in place; delete it before importing again under the same name. | |
| 594 | +**The repository lock.** From the moment the import creates the repository until it finishes, fails or is cancelled, only the import may write to it. Any other push gets `repository is locked by an import in progress`, and any other write through the REST API, the web UI or MCP gets `423 repository is locked by an import in progress; try again when it finishes, or cancel the import`. Watching the repository still works. The import itself may only create refs or move refs it wrote. A retry claims the repository again only when it holds nothing the import didn't write. If anyone pushed a branch, opened an issue, added a label, a protection rule or a release in the meantime (for example after the import failed and released the lock), the retry fails with `repository already holds content not written by this import; start a new import`. A failed or cancelled import leaves the partly imported repository in place; delete it before importing again under the same name. | |
| 594 | 595 | |
| 595 | 596 | ## Agents and imports |
| 596 | 597 | |
| 597 | 598 | Agents can start imports over MCP, the REST API or the CLI, with these rules: |
| 598 | 599 | |
| 599 | -- **Only into organizations**: the organization that owns the agent, or one where the agent's owner is an owner or admin. Otherwise `agents can import only into organizations they or their owner administer`. | |
| 600 | +- **Only where its owner may import.** An agent owned by a person imports into that person's own account or an organization the person owns or administers (anywhere, if the person is a site administrator). An agent owned by an organization imports into that organization. Otherwise `agents can import only where their owner may: the owner's own account or an organization the owner administers, not <owner>`. | |
| 600 | 601 | - **The agent's maximum role must be at least `write`** (`this agent's policy does not allow writing; an import needs at least write`), and its token needs the `write` scope. |
| 601 | 602 | - **Never a push protection bypass.** The `secrets` option is forced to `stop`. |
| 602 | 603 | - **No variables, secret names or environments.** The **Variables and secret names** step, and an organization import's **Organization variables and secret names** step, are skipped with `skipped (agents cannot manage variables)`. A person imports or sets those afterwards. For people, the right to manage variables is checked again when that step runs. |
| 603 | -- **No retry after the repository exists.** | |
| 604 | +- **No retry after the repository exists.** A person who administers the target takes the retry over. | |
| 604 | 605 | - **No secret values**, ever. Agents can't set secrets anywhere; a person with admin access sets them. |
| 605 | 606 | - An agent sees and lists only the imports it started. |
| 606 | 607 | |
| @@ -968,7 +969,7 @@ | ||
| 968 | 969 | | `acme has no repositories to import` | The account has none the token can see, or the filters excluded all of them. | |
| 969 | 970 | | `acme/website already exists; choose another name` | Pick another `name` (or **New repository name**), or delete the existing repository. | |
| 970 | 971 | | `you can import only into your own account or organizations you administer, not acme` | Ask an owner of `acme` to make you an admin, or to run the import. | |
| 971 | -| `agents can import only into organizations they or their owner administer` | An agent can't import into a user account, or into an organization its owner doesn't administer. | | |
| 972 | +| `agents can import only where their owner may: ...` | The target isn't the owner's own account or an organization the owner administers (or, for an organization's agent, that organization). | | |
| 972 | 973 | | `starting an import needs a token with write or admin scope` | Use a `write` or `admin` token. | |
| 973 | 974 | | `this token needs the write scope` or `this token is limited to repositories and can't change account settings` | Cancelling, retrying and choosing repositories need a `write` token that isn't restricted to repositories. | |
| 974 | 975 | | `too many repository imports are already running (at most 3 at a time); wait for one to finish` | Wait for one to finish, or cancel one. | |
| @@ -988,7 +989,7 @@ | ||
| 988 | 989 | | `the Git transfer did not finish within 6 hours` | The repository is too large or GitHub was too slow. Retry, or split the repository. | |
| 989 | 990 | | `the import container stopped before finishing (exit code ...)` | The transfer is retried once automatically; after that, retry the import. | |
| 990 | 991 | | `The Git transfer failed and is being retried: ...` (warning) | The first transfer failed and a second one started. Nothing to do. | |
| 991 | -| `repository is locked by an import in progress` | You pushed to a repository an import is still filling. Wait for the import to finish. | | |
| 992 | +| `repository is locked by an import in progress` (on a push), or `423 repository is locked by an import in progress; try again when it finishes, or cancel the import` | You wrote to a repository an import is still filling. Wait for the import to finish, or cancel it. | | |
| 992 | 993 | | `repository already holds content not written by this import; start a new import` | Someone changed the repository between attempts. Start a new import under another name, or delete the repository first. | |
| 993 | 994 | | `skipped (agents cannot manage variables)` | An agent started the import. A person sets variables and secrets afterwards. | |
| 994 | 995 | | `skipped (you no longer administer the target)` | You lost admin rights on the target before the variables step ran. | |
| @@ -1001,10 +1002,10 @@ | ||
| 1001 | 1002 | |
| 1002 | 1003 | | Message | Cause and fix | |
| 1003 | 1004 | | --- | --- | |
| 1004 | -| `import not found` | You didn't start the import (only the starter can retry), or you can't see it. | | |
| 1005 | +| `import not found` | You didn't start the import (only the starter can retry, or for an agent's import a person who administers the target), or you can't see it. | | |
| 1005 | 1006 | | `only failed or cancelled imports can be retried` | The import is still running or succeeded. | |
| 1006 | 1007 | | `retry the organization import this repository belongs to` | Retry the parent import. | |
| 1007 | -| `an agent cannot retry an import after the repository was created; a person must retry it` | A person starts a new import instead. | | |
| 1008 | +| `an agent cannot retry an import after the repository was created; a person who administers <owner> must retry it` | A person who administers the target retries it. | | |
| 1008 | 1009 | | `the import already succeeded` (or `failed`, `cancelled`) | Only drafts and queued or running imports can be cancelled. | |
| 1009 | 1010 | |
| 1010 | 1011 | ### Linking a GitHub account |
modifiedapps/diffinery/docs/self-hosting/configuration.md+1−1View file
| @@ -28,7 +28,7 @@ | ||
| 28 | 28 | | `ACCESS_AUD` | Empty (filled in on deploy) | For email sign-in | The audience tag of the Access application that guards `/auth/access`. | |
| 29 | 29 | | `ARTIFACT_QUOTA_BYTES` | Not set | No | Workflow artifact storage per repository, in bytes: artifacts that haven't expired plus uploads in progress. Default `10737418240` (10 GB). Anything that isn't a positive whole number counts as not set. Add it under `vars` in `wrangler.jsonc`; the deploy keeps it. When a repository reaches it, uploads fail with `413 the repository's artifact storage quota (N bytes) is used up; delete artifacts or wait for them to expire`. See [Caches and artifacts](/docs/reference/limits#caches-and-artifacts). | |
| 30 | 30 | | `DEV_AUTH` | Not set in production; `dev@diffinery.local` in the `dev` environment | Never in production | Local development only. See [DEV_AUTH](#dev_auth). | |
| 31 | -| `IMPORT_MAX_REPO_KB` | Not set | No | The largest GitHub repository a one-repository import accepts, in KB as GitHub reports a repository's `size`. Default `10485760` (10 GB). An empty value, `0` or text that isn't a number counts as not set. A larger source is refused before the import starts with `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`. See [GitHub imports](#github-imports). | | |
| 31 | +| `IMPORT_MAX_REPO_KB` | Not set | No | The largest GitHub repository a one-repository import accepts, in KB as GitHub reports a repository's `size`. Default `10485760` (10 GB). An empty value, `0`, a negative number or text that isn't a number counts as not set. A larger source is refused before the import starts with `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`. See [GitHub imports](#github-imports). | | |
| 32 | 32 | | `IMPORT_GHE_HOST` | Not set | No | The host name of a GitHub Enterprise Server (like `ghe.example.com`) that imports may download release assets from. Without it, imports download release assets only from github.com and its asset hosts, and assets of an Enterprise import are skipped with a warning. | |
| 33 | 33 | | `GITHUB_OAUTH_CLIENT_ID` | Not set | No | The client ID of a GitHub OAuth app, for linking GitHub accounts with a GitHub sign-in instead of a gist. Needs `GITHUB_OAUTH_CLIENT_SECRET` too. See [GitHub imports](#github-imports). | |
| 34 | 34 | | `IMPORT_GIT_AGENT` | Not set in production; `external` in the `dev` environment | Never in production | With `external`, an import's Git transfer doesn't start a container: it waits for an import agent started by hand (see [The dev environment](#the-dev-environment)). | |
modifiedapps/diffinery/src/docs/api-meta.ts+2−2View file
| @@ -1336,7 +1336,7 @@ | ||
| 1336 | 1336 | "POST /diffinery/imports": { |
| 1337 | 1337 | summary: "Start a GitHub import", |
| 1338 | 1338 | description: |
| 1339 | - "Imports one GitHub repository (`source`), or many repositories of a GitHub organization or user (`source_owner`), on the server, and returns the import (`status: queued`). Git history with LFS objects is copied in a container; issues and pull requests (with their numbers), comments, reviews, labels, milestones, branch protection, Actions variables, deployment environments and releases come through GitHub's REST API. Secret values are never read: only secret names are listed in `summary`, for a person to set by hand. People can import into their own account or an organization they own or administer (site administrators: any user or organization). An agent can import only into an organization that owns it or that its owner owns or administers, and only when its policy allows `write`; its imports always use `secrets: stop` and skip Actions variables and environments. Needs a `write` or `admin` token (403 `starting an import needs a token with write or admin scope`), or a browser session. At most one organization import and three repository imports run at a time per account and per target (429), and a `source` repository larger than `IMPORT_MAX_REPO_KB` (default 10 GB, by GitHub's reported size) is refused with 422. Other errors: 422 `<owner>/<name> already exists; choose another name`, 422 `GitHub repository <source> was not found or the token cannot read it`, 422 `GitHub rejected the token (expired or revoked?)`, 429 when GitHub's rate limit is reached, 502 `could not reach GitHub: ...`. Audited as `import.create`. See [Migrate from GitHub](/docs/migrate-from-github).", | |
| 1339 | + "Imports one GitHub repository (`source`), or many repositories of a GitHub organization or user (`source_owner`), on the server, and returns the import (`status: queued`). Git history with LFS objects is copied in a container; issues and pull requests (with their numbers), comments, reviews, labels, milestones, branch protection, Actions variables, deployment environments and releases come through GitHub's REST API. Secret values are never read: only secret names are listed in `summary`, for a person to set by hand. People can import into their own account or an organization they own or administer (site administrators: any user or organization). An agent can import only where its owner may (the owner's own account or an organization the owner owns or administers; an organization's agent, only into that organization), and only when its policy allows `write`; its imports always use `secrets: stop` and skip Actions variables and environments. Needs a `write` or `admin` token (403 `starting an import needs a token with write or admin scope`), or a browser session. At most one organization import and three repository imports run at a time per account and per target (429), and a `source` repository larger than `IMPORT_MAX_REPO_KB` (default 10 GB, by GitHub's reported size) is refused with 422. Other errors: 422 `<owner>/<name> already exists; choose another name`, 422 `GitHub repository <source> was not found or the token cannot read it`, 422 `GitHub rejected the token (expired or revoked?)`, 429 when GitHub's rate limit is reached, 502 `could not reach GitHub: ...`. Audited as `import.create`. See [Migrate from GitHub](/docs/migrate-from-github).", | |
| 1340 | 1340 | access: "account", |
| 1341 | 1341 | status: 201, |
| 1342 | 1342 | body: { |
| @@ -1374,7 +1374,7 @@ | ||
| 1374 | 1374 | "POST /diffinery/imports/{id}/retry": { |
| 1375 | 1375 | summary: "Retry an import", |
| 1376 | 1376 | description: |
| 1377 | - "Runs a `failed` or `cancelled` import again as a new `attempt` (409 `only failed or cancelled imports can be retried` otherwise), with the same options. Only whoever started it can retry it (404 for anyone else). A repository import inside an organization import can't be retried on its own (422 `retry the organization import this repository belongs to`); retrying the organization import re-runs its failed and cancelled repositories, except those that failed because the target name was taken. The GitHub token was deleted when the import ended, so send `github_token` again for a private source. The retry resumes into the repository the import created, and fails if someone else has written to it since (`repository already holds content not written by this import; start a new import`). An agent can't retry once the repository exists (403). Audited as `import.retry`.", | |
| 1377 | + "Runs a `failed` or `cancelled` import again as a new `attempt` (409 `only failed or cancelled imports can be retried` otherwise), with the same options. Only whoever started it can retry it (404 for anyone else), except that a person who may import into the target can also retry an import an agent started. A repository import inside an organization import can't be retried on its own (422 `retry the organization import this repository belongs to`); retrying the organization import re-runs its failed and cancelled repositories, except those that failed because the target name was taken. The GitHub token was deleted when the import ended, so send `github_token` again for a private source. The retry resumes into the repository the import created, and fails if someone else has written to it since (`repository already holds content not written by this import; start a new import`). An agent can't retry once the repository exists (403 `an agent cannot retry an import after the repository was created; a person who administers <owner> must retry it`). Audited as `import.retry`.", | |
| 1378 | 1378 | access: "account", |
| 1379 | 1379 | status: 202, |
| 1380 | 1380 | body: { github_token: ["string", "A GitHub token for this attempt (optional; at most 400 characters)."] }, |