Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(ci): retry failed depot jobs from a /depot retry comment (#118592)

Raúl Negrón-Oteroc9ac057d9f5d
diff --git a/.agents/skills/debugging-ci-failures/SKILL.md b/.agents/skills/debugging-ci-failures/SKILL.md
index 9b7b77ce49b9..aae74caaed10 100644
--- a/.agents/skills/debugging-ci-failures/SKILL.md
+++ b/.agents/skills/debugging-ci-failures/SKILL.md
@@ -249,20 +249,26 @@ history, hand off to `fixing-flaky-tests`, which covers the `search-test` and
#### Backend tests that ran on Depot CI
-A PR can route its backend tests to Depot CI.
-Then the GitHub Actions run holds only the relay: `Django Tests Pass` fails with "Backend tests on Depot CI concluded failure", and the GitHub run logs show nothing more.
-A re-run of that job is not read-only: it retries the failed and cancelled Depot jobs and reports the new verdict, so the rule against re-running CI applies to it.
-A run that Depot still shows as running past its job timeouts is stuck. A re-run waits on it, so cancel it with `depot ci cancel` first.
-The log of the `Relay the Depot verdict` step prints the Depot run URL, each failed step with its log lines, and the label that sends the PR back to GitHub Actions.
-
-Read more of the failure from Depot with the `depot` CLI, which the flox environment installs.
-Run `depot ci diagnose --org <org> --workflow <workflow>` with the two ids from the Depot run URL in the relay log.
+Depot CI runs the backend tests of every same-repo PR.
+The required check is `Backend CI on Depot / Django Tests Pass on Depot`, and the `Backend CI on Depot / Test results` check lists each failed step with its log lines.
+`Django Tests Pass` on GitHub Actions only prints a notice on a PR.
+
+GitHub's Re-run button does nothing on a Depot check.
+A `/depot retry` comment on the PR from an organization member or collaborator retries the failed and cancelled jobs of the newest run, also while the rest of the run still goes.
+With the user's permission, post that comment.
+With a Depot login, `depot ci retry <run-id> --failed --workflow <workflow-id>` does the same without a comment.
+The flox environment installs the `depot` CLI. Outside an activated flox shell, run it as `flox activate -- depot ...`.
+A run that Depot still shows as running past its job timeouts is stuck. Cancel the stuck job with `depot ci cancel` before you retry.
+
+Read more of the failure from Depot with the `depot` CLI.
+Run `depot ci diagnose --org <org> --workflow <workflow>` with the two ids from the details link of a Depot check.
For logs, artifacts, and test results, load the `depot-ci` skill.
-Its `references/posthog-check-run-semantics.md` gets Depot ids from a commit's check runs when you have no relay log.
+Its `references/posthog-check-run-semantics.md` gets Depot ids from a commit's check runs.
If a `depot` command fails to authenticate, check `DEPOT_TOKEN` first: it overrides the saved login, so a wrong one fails every command.
Without it, ask the user to run `! depot login --clear`.
Do not run it yourself: it waits on a browser sign-in.
-If the user has no access to the Depot org, report the relay log's no-Depot retry options instead.
+Every PostHog engineer gets an invite to the Depot org. A user without access checks their email for it, or requests one in #team-devex.
+Until then, retry with the `/depot retry` comment.
## Classification
diff --git a/.agents/skills/depot-ci/SKILL.md b/.agents/skills/depot-ci/SKILL.md
index c6ac424966f8..7dd4ba03e589 100644
--- a/.agents/skills/depot-ci/SKILL.md
+++ b/.agents/skills/depot-ci/SKILL.md
@@ -18,7 +18,7 @@ description: >
Depot CI is a programmable CI system for engineers and agents. Workflows in Depot CI run entirely on Depot compute with built-in job visibility, debuggability, and control. GitHub Actions is the first syntax Depot CI supports: migrate your existing GitHub Actions workflows, and get fast, reliable runs on optimized infrastructure.
-This SKILL.md covers the core workflow plus the most common commands. Detailed flag tables, JSON output shapes, and less-common commands live in three reference files under `references/`, pointed to from the relevant sections below. Load a reference file only when you need detail it points to.
+This SKILL.md covers the core workflow plus the most common commands. Detailed flag tables, JSON output shapes, and less-common commands live in focused files under `references/`, pointed to from the relevant sections below. Load a reference file only when you need the detail it contains.
<!-- PostHog-local section. Keep it when resyncing from upstream; see UPSTREAM.md. -->
@@ -117,7 +117,7 @@ Treat credentials as sensitive input and never echo them back in outputs.
- For non-interactive flows, pipe secret values via stdin (for example `printf '%s' "$NPM_TOKEN" | depot ci secrets set SECRET_NAME --from-stdin`), not command-line literals.
- Prefer interactive prompts over passing secret values as command arguments. Don't hardcode secrets or tokens in commands, scripts, workflow YAML, logs, or examples.
-- Use CI secret stores for `DEPOT_TOKEN` and other credentials; pass at runtime only.
+- In external CI systems, pass Depot credentials from the CI secret store at runtime. Depot CI reserves `DEPOT_TOKEN` and injects a job token for builds in trusted jobs. Do not create a Depot CI secret named `DEPOT_TOKEN`.
- Avoid force/non-interactive destructive flags unless explicitly requested. Before running credential-affecting commands, confirm scope (org, repo, workflow) and intended target.
## Running Workflows
@@ -143,9 +143,16 @@ depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3
# Override the auto-detected repository (multiple remotes or no origin)
depot ci run --workflow .depot/workflows/ci.yml --repo owner/repo
+
+# Select Depot Code explicitly for a mirrored repository
+depot ci run --workflow .depot/workflows/ci.yml --forge depot
```
-The CLI auto-detects the GitHub repository from git remotes (preferring `origin`); pass `--repo owner/repo` to override. It also auto-detects uncommitted changes vs. the default branch, uploads a patch to Depot Cache, and injects a step to apply it after checkout, so your local working state runs without needing a push. Use `--ssh` / `--ssh-after-step` to start a debug session when launching a new run; use `depot ci ssh` to connect to an already-running job. Pass `--follow` (or `-f`) to stream the triggered run's logs as soon as it starts: it follows the single `--job` you request, or auto-selects when the run has one job and prompts when several are running. `--follow` cannot be combined with `--ssh` / `--ssh-after-step`.
+The CLI detects GitHub, Origin, and Depot Code from git remotes. Depot Code is automatic only when all supported remotes use Depot Code; mirrored checkouts default to GitHub or Origin. Set `--forge` to `github`, `origin`, or `depot` to select a forge. Use `--repo <name>` to select a repository. When no matching remote exists, specify `--forge origin` or `--forge depot` for those forges.
+
+Local patches contain unpushed changes relative to the branch's remote state, or changes relative to the default branch for local-only branches. The CLI uploads the patch to Depot Cache and injects an application step after `actions/checkout`. Jobs that call reusable workflows have no steps for patch injection and run the merge-base code without local changes; the CLI warns about them.
+
+Use `--ssh` / `--ssh-after-step` to start a debug session when launching a new run; both require exactly one `--job` and cannot be combined. Use `depot ci ssh` to connect to an already-running job. Pass `--follow` to stream the triggered run's logs: it follows the single requested job, or selects the only job and prompts when several are running. `--follow` cannot be combined with `--ssh` / `--ssh-after-step`.
## Dispatching Workflows
@@ -160,6 +167,8 @@ depot ci dispatch --repo depot/cli --workflow deploy.yml --ref main --output jso
`--workflow` takes the workflow file's **basename** (for example `deploy.yml`), not the full path `.depot/workflows/deploy.yml`, matching GitHub's `workflow_dispatch` API convention. Required flags: `--repo <owner/repo>`, `--workflow <filename>`, `--ref <branch-or-tag>`. `--input <key>=<value>` is repeatable.
+The `depot.actor` context identifies who created the run; `depot.triggering_actor` identifies who started the current attempt, including retries and reruns. Both expose `kind`, `id`, `email`, and `name`. Actor kinds are `user`, `organization_token`, `service`, and `github`; only users have an email. The corresponding environment variables are `DEPOT_ACTOR_KIND`, `DEPOT_ACTOR_ID`, `DEPOT_ACTOR_EMAIL`, `DEPOT_ACTOR_NAME`, `DEPOT_TRIGGERING_ACTOR_KIND`, `DEPOT_TRIGGERING_ACTOR_ID`, `DEPOT_TRIGGERING_ACTOR_EMAIL`, and `DEPOT_TRIGGERING_ACTOR_NAME`. GitHub actor contexts retain their GitHub meaning.
+
## Custom Images
Build a custom image once and reuse it across jobs to skip repeated setup steps. A custom image is a snapshot of a Depot CI sandbox, stored in your org's Depot registry, that any job in any workflow can reference by name.
@@ -322,6 +331,10 @@ Depot CI issues a signed JWT to each job so workflows can authenticate to cloud
For provider trust-policy setup, the `sub` spiffe claim format and wildcards, the full token claim reference, and migrating an existing GitHub Actions OIDC trust policy, read `references/oidc.md`.
+## Datadog CI Visibility
+
+Enable Datadog CI Visibility in the Depot organization settings, then add a Depot CI secret named `DD_API_KEY`. Add `DD_SITE` when the Datadog account uses a region other than `datadoghq.com`. Depot sends each workflow run as a pipeline, with its jobs and steps, directly to Datadog. Reporting is best-effort, so a Datadog failure does not fail the CI run.
+
## Running, Monitoring, and Debugging Runs
Common triage and inspection commands:
@@ -335,6 +348,9 @@ depot ci run list --repo depot/api --status failed --pr 42
# Inspect a run's full workflow -> job -> attempt hierarchy
depot ci status <run-id>
+# Wait for completion; exit 1 if the run fails or is cancelled
+depot ci status <run-id> --wait --output json
+
# Pull logs (accepts run, job, or attempt ID; auto-selects the job if only one)
depot ci logs <run-id>
depot ci logs <run-id> --job build
@@ -365,10 +381,22 @@ Full command index, all in `references/runs-and-debugging.md`:
| `depot ci ssh` | Interactive terminal into a running job's sandbox |
| `depot ci cancel` | Cancel a whole run, a workflow, or a single job |
| `depot ci rerun` | Re-run every terminal-state job in a workflow |
-| `depot ci retry` | Retry a single failed/cancelled job, or all of them with `--failed` |
+| `depot ci retry` | Retry one failed/cancelled job; `--failed` also reruns downstream jobs |
Read `references/runs-and-debugging.md` when you need a complete flag table, JSON output shape, or any command not shown in the triage examples above.
+## Test Results and Timing-Based Splitting
+
+Use `depot tests` to inspect parsed JUnit results.
+
+<!-- PostHog-local section. Keep it when resyncing from upstream; see UPSTREAM.md. -->
+
+PostHog does not use `depot tests split`, `depot tests run` or `depot tests report`.
+Backend shards come from `.test_durations`, and Trunk Flaky Tests tracks flaky and quarantined tests.
+See `/fixing-flaky-tests` and `/debugging-ci-failures`.
+
+<!-- End PostHog-local section. -->
+
## Compatibility with GitHub Actions
Depot CI executes GitHub Actions YAML workflows. There are a few limitations where compatibility isn't 1:1. The full support and compatibility list is in `references/github-actions-compatibility.md`.
@@ -376,13 +404,14 @@ Depot CI executes GitHub Actions YAML workflows. There are a few limitations whe
Read the compatibility reference when you need to answer or act on any of the following or similar questions:
- Whether a specific workflow-, job-, or step-level field is supported, for example `concurrency`, `jobs.<id>.environment`, `jobs.<id>.snapshot`, `jobs.<id>.container`, `jobs.<id>.services`, `jobs.<id>.strategy.matrix`, `steps[*].shell`.
-- Whether a trigger event is accepted: the supported list (`push`, `pull_request`, `pull_request_target`, `pull_request_review`, `deployment_status`, `repository_dispatch`, `schedule`, `workflow_call`, `workflow_dispatch`, `workflow_run`, `merge_group`) and the GitHub-only events Depot CI rejects (for example, `release`, `issues`, `deployment`, `branch_protection_rule`).
-- Which expression contexts (`github`, `env`, `vars`, `secrets`, `needs`, `strategy`, `matrix`, `steps`, `job`, `runner`, `inputs`) and functions (`always()`, `success()`, `failure()`, `cancelled()`, `case()`, `contains()`, `startsWith()`, `endsWith()`, `format()`, `join()`, `toJSON()`, `fromJSON()`, `hashFiles()`) are available.
-- Which `permissions` scopes work (`actions`, `checks`, `contents`, `id-token`, `metadata`, `pull_requests`, `statuses`, `workflows`).
+- Whether a trigger event is accepted: the supported list (`push`, `pull_request`, `pull_request_target`, `pull_request_review`, `issue_comment`, `deployment_status`, `repository_dispatch`, `schedule`, `workflow_call`, `workflow_dispatch`, `workflow_run`, `merge_group`) and the GitHub-only events Depot CI rejects (for example, `release`, `issues`, `deployment`, `branch_protection_rule`).
+- Which expression contexts (`github`, `env`, `vars`, `secrets`, `needs`, `strategy`, `matrix`, `steps`, `job`, `runner`, `inputs`, `depot`) and functions (`always()`, `success()`, `failure()`, `cancelled()`, `case()`, `contains()`, `startsWith()`, `endsWith()`, `format()`, `join()`, `toJSON()`, `fromJSON()`, `hashFiles()`) are available.
+- Which `permissions` scopes work (`actions`, `checks`, `code-quality`, `contents`, `id-token`, `issues`, `packages`, `pull-requests`, `security-events`, `statuses`). Request `code-quality` explicitly because `read-all` and `write-all` do not include it.
- Which action types run (JavaScript Node 12/16/20/24, Composite, Docker).
- Which `runs-on` Depot runner labels and sandbox sizes Depot CI supports (x86_64 and Arm only, no macOS nor Windows), and how unrecognized labels are treated.
- Diagnosing why `depot ci migrate` auto-disabled a job, stripped a trigger from `on:`, or remapped a `runs-on` label.
-- Recommending workarounds for known unsupported features (cross-repo reusable workflows, fork-triggered PRs, deployment environments).
+- Calling cross-repository reusable workflows with supported refs and repository access.
+- Recommending workarounds for known unsupported features (fork-triggered PRs, deployment environments).
For routine migrate, run, secrets, or debug tasks that don't depend on a specific GHA feature, you don't need to load `references/github-actions-compatibility.md`.
@@ -400,11 +429,11 @@ your-repo/
## Common Mistakes
-| Mistake | Fix |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| Removing `.github/workflows/` after migration | Keep them during transition to verify Depot CI parity |
-| Using cross-repo reusable workflows | Not supported yet, inline the workflow or copy it locally |
-| Expecting branch/env variants need the dashboard | The CLI manages variants directly via `--repo`/`--env`/`--branch`/`--workflow` selectors |
-| Running in the wrong org context | Check `depot org show`, list with `depot org list`, then switch org or pass `--org <id>` |
-| Forgetting `--org` flag with multiple orgs | Migration or run commands may miss the expected repo/workflow; specify `--org <id>` |
-| Workflows with `runs-on: windows-latest` | Treated as `depot-ubuntu-latest`, may fail |
+| Mistake | Fix |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Removing `.github/workflows/` after migration | Keep them during transition to verify Depot CI parity |
+| Using a branch ref for a cross-repo reusable workflow | Use a full commit SHA or supported version tag; see the compatibility reference |
+| Expecting branch/env variants need the dashboard | The CLI manages variants directly via `--repo`/`--env`/`--branch`/`--workflow` selectors |
+| Running in the wrong org context | Check `depot org show`, list with `depot org list`, then switch org or pass `--org <id>` |
+| Forgetting `--org` flag with multiple orgs | Migration or run commands may miss the expected repo/workflow; specify `--org <id>` |
+| Workflows with Windows or macOS runner labels | Depot CI supports Ubuntu sandboxes; select a compatible job and runner before migration |
diff --git a/.agents/skills/depot-ci/UPSTREAM.md b/.agents/skills/depot-ci/UPSTREAM.md
index 51f4cd086875..3d6357e4a668 100644
--- a/.agents/skills/depot-ci/UPSTREAM.md
+++ b/.agents/skills/depot-ci/UPSTREAM.md
@@ -3,16 +3,18 @@
Vendored from [depot/skills](https://github.com/depot/skills) — used by the Depot CI workflows this repo keeps under `.depot/workflows/`.
- Source: `skills/depot-ci/SKILL.md` and `skills/depot-ci/references/`
-- Commit: [`81795ab`](https://github.com/depot/skills/tree/81795abf98f81fb112cda35720e19b2aa3efa640/skills/depot-ci) (2026-09-01)
+- Commit: [`71f008d`](https://github.com/depot/skills/tree/71f008de4dbfa8625ece3df85019bc914b9399a0/skills/depot-ci) (2026-10-15)
- License: none in upstream at this commit; README documents `cp SKILL.md` install.
-Upstream also ships `agents/openai.yaml` and `assets/` icons in this directory. Neither is vendored: we do not run the OpenAI agent definition, and the icons are branding for Depot's own docs.
+Upstream also ships `agents/openai.yaml`, `assets/` icons and `references/test-splitting.md` in this directory. None is vendored: we do not run the OpenAI agent definition, the icons are branding for Depot's own docs, and PostHog does not use Depot test splitting.
## Local additions
- `references/posthog-check-run-semantics.md`, which upstream has no equivalent of.
-- In `SKILL.md`, the two paragraphs between PostHog-local comment markers (one under the intro, one under "Parallel Steps" recording that GitHub Actions now has its own `parallel:` keyword), and the two sentences appended to the frontmatter `description`.
+- In `SKILL.md`, the three sections between PostHog-local comment markers (one under the intro, one under "Parallel Steps" recording that GitHub Actions now has its own `parallel:` keyword, and one under "Test Results and Timing-Based Splitting" that replaces upstream's splitting sentences and its link to `references/test-splitting.md`), and the two sentences appended to the frontmatter `description`.
+- In `references/oidc.md`, the trust policy JSON as reflowed by the repo formatter.
- Three code fences tagged `text` to satisfy markdownlint MD040, which the pre-commit hook enforces: the directory tree in `SKILL.md` and `references/migration.md`, and the SPIFFE id in `references/oidc.md`. Upstream leaves them untagged, so a resync reintroduces the error.
+- One of two consecutive blank lines after the runner label table in `references/github-actions-compatibility.md`, which markdownlint MD012 rejects.
## Resync
diff --git a/.agents/skills/depot-ci/references/github-actions-compatibility.md b/.agents/skills/depot-ci/references/github-actions-compatibility.md
index 014463fd46e3..7d7733bf456e 100644
--- a/.agents/skills/depot-ci/references/github-actions-compatibility.md
+++ b/.agents/skills/depot-ci/references/github-actions-compatibility.md
@@ -10,10 +10,26 @@ Depot CI runs GitHub Actions YAML on Depot's own orchestrator and compute, so mo
### Triggers
-`push` (branches, tags, paths), `pull_request` (branches, paths), `pull_request_target`, `pull_request_review`, `deployment_status`, `repository_dispatch` (with `types`), `schedule`, `workflow_call`, `workflow_dispatch` (with inputs), `workflow_run`, `merge_group`
+`push` (branches, tags, paths), `pull_request` (branches, paths), `pull_request_target`, `pull_request_review`, `issue_comment` (created, edited, deleted), `deployment_status`, `repository_dispatch` (with `types`), `schedule`, `workflow_call`, `workflow_dispatch` (with inputs), `workflow_run`, `merge_group`
+
+`issue_comment` covers comments on issues and pull requests. The workflow runs from the repository's default branch. Use `github.event.issue.pull_request` to distinguish pull request comments. Issue edits and label changes use the separate unsupported `issues` trigger; inline pull request review comments use the separate unsupported `pull_request_review_comment` trigger.
`repository_dispatch` lets you trigger runs from outside GitHub via the GitHub API; the custom event type and `client_payload` are available through `github.event.action` and `github.event.client_payload`. GitHub delivers these events only against the default branch, so the default-branch workflow runs.
+For scheduled GitHub workflows, add `on.schedule` to `.depot/workflows/` and merge the workflow into the default branch. Depot evaluates cron expressions in UTC and runs the default branch independently of GitHub's scheduler. Per-entry `timezone` fields are ignored. Depot Code scheduled runs are not supported.
+
+Depot CI supports native GitHub stacked pull requests for `pull_request` workflows. Depot evaluates the `branches` filter against the stack's ultimate base branch, then runs the workflow for each pull request using its own merge ref. `github.event.pull_request.stack` provides `number`, `size`, `position`, `base.ref`, and `base.sha`; the value is `null` for an ordinary pull request.
+
+For `workflow_run`, the `on.workflow_run.workflows` filter accepts a YAML workflow name, Depot filename, or repository path. In `github.event.workflow_run`, `name` is the YAML name (or the repository path when unnamed), `path` is the repository-relative path such as `.depot/workflows/ci.yml`, and the Depot-only `basepath` is the filename such as `ci.yml`. `name` does not use `run-name`.
+
+### Cross-repository reusable workflows
+
+Use job-level `uses: owner/repo/.github/workflows/build.yml@v1`. Depot resolves authored `.github/workflows/` paths to `.depot/workflows/` in the source repository; direct `.depot/workflows/` references also work. Nested calls, matrix jobs, inputs, and outputs are supported.
+
+Pin a full 40-character commit SHA or a version tag such as `v1`, `v1.2`, or `v1.2.3`. Branch refs and abbreviated SHAs are unsupported. Version-looking refs must resolve to tags.
+
+For private or internal sources, the caller must be a trusted private repository in the same GitHub organization, and the Depot Code Access app needs source-repository access. External workflows require a GitHub caller. External jobs cannot use deployment environments, snapshots, or custom runner images. Cross-repository `secrets: inherit` requires an eligible trusted private caller in the same GitHub organization; prefer explicit secret mappings when inheritance is not needed.
+
### Job level
`name`, `needs`, `if`, `permissions`, `outputs`, `env`, `defaults`, `timeout-minutes`, `concurrency`, `strategy` (matrix, fail-fast, max-parallel), `continue-on-error`, `container`, `services`, `uses` (reusable workflows), `with`, `secrets`, `secrets.inherit`, `steps`, `snapshot` (custom images from sandbox snapshots)
@@ -24,11 +40,17 @@ Depot CI runs GitHub Actions YAML on Depot's own orchestrator and compute, so mo
### Permissions
-`actions`, `checks`, `contents`, `id-token`, `metadata`, `pull_requests`, `statuses`, `workflows`
+`actions`, `checks`, `code-quality`, `contents`, `id-token`, `issues`, `packages`, `pull-requests`, `security-events`, `statuses`
+
+Use the hyphenated `pull-requests` key. Unknown permission keys are ignored when configuring `GITHUB_TOKEN`; operations that need those permissions can still fail.
+
+For `issues: read` or `issues: write`, approve the corresponding Issues permission on the Depot Code Access installation. Without that grant, job tokens can omit `issues`, and issue operations fail.
+
+Request `code-quality` explicitly. The `read-all` and `write-all` shorthands do not include it, which preserves compatibility with older Depot Code Access GitHub App installations.
### Expressions
-Contexts: `github`, `env`, `vars`, `secrets`, `needs`, `strategy`, `matrix`, `steps`, `job`, `runner`, `inputs`.
+Contexts: `github`, `env`, `vars`, `secrets`, `needs`, `strategy`, `matrix`, `steps`, `job`, `runner`, `inputs`, `depot`.
Functions: `always()`, `success()`, `failure()`, `cancelled()`, `case()`, `contains()`, `startsWith()`, `endsWith()`, `format()`, `join()`, `toJSON()`, `fromJSON()`, `hashFiles()`.
@@ -36,13 +58,20 @@ Functions: `always()`, `success()`, `failure()`, `cancelled()`, `case()`, `conta
JavaScript (Node 12/16/20/24), Composite, Docker.
+Actions declaring Node 12, 16, or 20 run on Node.js 24 by default. `ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: 'true'` temporarily selects Node.js 20 for those actions; actions declaring Node 24 remain on Node 24. The action runtime is separate from `node` on `PATH` in `run:` steps.
+
## Not Supported
-- **Cross-repo reusable workflows**: `uses` referencing workflows in other repositories is not supported. Local reusable workflows work.
- **Fork-triggered PRs**: `pull_request` and `pull_request_target` from forks not supported yet.
-- **Non-Ubuntu runner labels**: all non-Depot labels silently treated as `depot-ubuntu-latest` (no error, runs on Ubuntu).
+- **Non-Ubuntu runners**: Depot CI has no Windows or macOS sandboxes. Do not assume a migrated runner label preserves the original operating system.
- **Deployment environments**: the `environment` field is not supported.
-- **GitHub-specific event triggers**: `branch_protection_rule`, `check_run`, `check_suite`, `create`, `delete`, `deployment`, `discussion`, `discussion_comment`, `fork`, `gollum`, `image_version`, `issue_comment`, `issues`, `label`, `milestone`, `page_build`, `public`, `pull_request_comment`, `pull_request_review_comment`, `registry_package`, `release`, `status`, `watch`.
+- **GitHub-specific event triggers**: `branch_protection_rule`, `check_run`, `check_suite`, `create`, `delete`, `deployment`, `discussion`, `discussion_comment`, `fork`, `gollum`, `image_version`, `issues`, `label`, `milestone`, `page_build`, `public`, `pull_request_comment`, `pull_request_review_comment`, `registry_package`, `release`, `status`, `watch`.
+
+### GitHub Packages authentication
+
+`secrets.GITHUB_TOKEN` is a GitHub App token in Depot CI, and GitHub Packages does not accept GitHub App tokens for package access. This limitation applies to every GitHub Packages registry, including GHCR.
+
+For container images, prefer Depot Registry. When GitHub Packages is required, authenticate with a GitHub personal access token that has the required package scope and store it as a Depot CI secret. A personal access token is a long-lived user credential, so account lifetime, rotation, and least-privilege scope require explicit consideration.
## Runner labels
@@ -61,13 +90,13 @@ Supported labels:
| `depot-ubuntu-24.04-64` | `64x256` | 64 | 256 GB |
| `depot-ubuntu-latest-arm` | `2x8` | 2 | 8 GB |
| `depot-ubuntu-24.04-arm` | `2x8` | 2 | 8 GB |
-| `depot-ubuntu-24.04-4-arm` | `4x16` | 4 | 16 GB |
-| `depot-ubuntu-24.04-8-arm` | `8x32` | 8 | 32 GB |
-| `depot-ubuntu-24.04-16-arm` | `16x64` | 16 | 64 GB |
-| `depot-ubuntu-24.04-32-arm` | `32x128` | 32 | 128 GB |
-| `depot-ubuntu-24.04-64-arm` | `64x256` | 64 | 256 GB |
+| `depot-ubuntu-24.04-arm-4` | `4x16` | 4 | 16 GB |
+| `depot-ubuntu-24.04-arm-8` | `8x32` | 8 | 32 GB |
+| `depot-ubuntu-24.04-arm-16` | `16x64` | 16 | 64 GB |
+| `depot-ubuntu-24.04-arm-32` | `32x128` | 32 | 128 GB |
+| `depot-ubuntu-24.04-arm-64` | `64x256` | 64 | 256 GB |
-Any label Depot CI can't parse is silently treated as `depot-ubuntu-latest`.
+Jobs without a `depot-*` label fall back to `depot-ubuntu-latest`. Check migration warnings and choose a supported label instead of relying on fallback behavior.
## Migration behavior
@@ -76,6 +105,9 @@ Any label Depot CI can't parse is silently treated as `depot-ubuntu-latest`.
- **Unsupported triggers** are removed from the `on:` block.
- **Jobs that depend on unsupported features** are commented out and labeled `DISABLED`.
- **`runs-on` labels** are remapped to Depot equivalents (for example, `ubuntu-latest` → `depot-ubuntu-latest`).
+- **Unavailable GitHub runner labels** remain unchanged with a warning. Custom or conflicting labels also produce warnings in the migration summary. Choose a supported Depot runner before activating the workflow.
- **`.github/` path references** in copied files are rewritten to their `.depot/` equivalents.
If a user reports an auto-disabled job or a stripped trigger after migration, cross-reference the "Not Supported" list above to explain why.
+
+The CLI migration analyzer can still report external reusable workflows as unsupported even though the backend supports them. Check the supported reference and access rules above before replacing an external workflow with an inline copy.
diff --git a/.agents/skills/depot-ci/references/migration.md b/.agents/skills/depot-ci/references/migration.md
index 99bb67eaeaff..e7da58e44685 100644
--- a/.agents/skills/depot-ci/references/migration.md
+++ b/.agents/skills/depot-ci/references/migration.md
@@ -2,7 +2,9 @@
Detail for `depot ci migrate` and its subcommands, the transformations migration applies, and manual setup. SKILL.md keeps the high-level "Getting Started" flow; load this file for the subcommand flag tables and the exact set of changes migration makes to your workflows.
-**Common flags:** `depot ci migrate` and its subcommands accept `--org <id>` (required when the user belongs to multiple organizations) and `--token <token>`.
+**Common flags:** `depot ci migrate` and its subcommands accept `--forge <github|origin>` (default `github`), `-y` / `--yes`, `--org <id>` (required when the user belongs to multiple organizations), and `--token <token>`.
+
+Use the default `--forge=github` for repositories that use GitHub as the source of truth. Use `--forge=origin` for Origin-hosted repositories. The Origin flow detects an `origin.cursor.com` remote and checks that Depot can access the repository.
## Migrate subcommands
@@ -11,12 +13,15 @@ Detail for `depot ci migrate` and its subcommands, the transformations migration
```bash
# Validate auth, detect the repo, check the Depot Code Access GitHub App is installed
depot ci migrate preflight
+depot ci migrate preflight --forge=origin
# Copy and transform workflows from .github/workflows/ to .depot/workflows/
depot ci migrate workflows
+depot ci migrate workflows --forge=origin
# Import GitHub Actions secrets and variables into Depot CI
depot ci migrate secrets-and-vars
+depot ci migrate secrets-and-vars --forge=origin
```
### `depot ci migrate workflows` steps
@@ -24,16 +29,20 @@ depot ci migrate secrets-and-vars
1. Discovers all workflow files in `.github/workflows/`.
2. Analyzes each workflow for Depot CI compatibility.
3. Prompts you to select which workflows to migrate.
-4. Copies selected workflows to `.depot/workflows/` and any local actions from `.github/actions/` to `.depot/actions/`.
-5. Applies compatibility fixes and adds inline comments documenting each change.
-6. Disables jobs that use unsupported features, with a `DISABLED` comment noting the reason.
-7. Reports any secrets and variables detected in the migrated workflows.
+4. With `--forge=origin`, sends the selected workflow contents to Depot for Origin compatibility analysis.
+5. Copies selected workflows to `.depot/workflows/` and any local actions from `.github/actions/` to `.depot/actions/`.
+6. Applies compatibility fixes and adds inline comments documenting each change.
+7. Disables jobs that use unsupported features, with a `DISABLED` comment noting the reason.
+8. Reports any secrets and variables detected in the migrated workflows.
+
+Origin compatibility findings identify actions that fail or have reduced functionality because Origin does not expose an equivalent GitHub API. Findings do not block migration.
### What gets transformed
The command applies these changes, each documented with inline comments, and writes a header comment to every migrated file summarizing them:
- **`runs-on` labels** are remapped from GitHub runner labels (like `ubuntu-latest`) to their Depot equivalents (like `depot-ubuntu-latest`).
+- **Unavailable GitHub runner labels** remain unchanged and produce a warning. Custom or conflicting labels also produce migration-summary warnings. Select a supported Depot Ubuntu runner before activating the workflow.
- **Unsupported triggers** (like `release` or `issues`) are removed from the `on:` block with a comment explaining why.
- **Jobs with unsupported features** are commented out entirely, with a `DISABLED` comment.
- **`.github/` path references** in copied workflow and action files are rewritten to their `.depot/` equivalents.
@@ -44,23 +53,26 @@ For the full compatibility matrix, see `github-actions-compatibility.md` in this
### `depot ci migrate` and `depot ci migrate workflows`
-| Flag | Description |
-| ------------- | ----------------------------------------------------------- |
-| `-y, --yes` | Non-interactive: migrate all discovered workflows |
-| `--overwrite` | Overwrite an existing `.depot/` directory without prompting |
+| Flag | Description |
+| ------------- | ------------------------------------------------------------------------------ |
+| `-y, --yes` | Migrate all workflows and overwrite matching `.depot/` files without prompting |
+| `--overwrite` | Overwrite matching files in an existing `.depot/` directory without prompting |
+
+For an agent or other non-interactive caller, `--yes` is required because workflow selection otherwise needs a terminal. Check the existing `.depot/` files before using `--yes`, because the flag also enables overwrite behavior.
(`depot ci migrate preflight` takes only the common flags.)
### `depot ci migrate secrets-and-vars`
-Creates a one-shot GitHub Actions workflow on a temporary branch that reads your existing GitHub secrets and variables and imports them into Depot CI. In interactive mode you can preview the generated workflow first; the branch is safe to delete afterward. You can also add secrets and variables manually with `depot ci secrets add` / `depot ci vars add` (see `secrets-and-variables.md`).
+Creates a one-shot GitHub Actions workflow on a temporary branch that reads your existing GitHub secrets and variables and imports them into Depot CI. The command creates the commit without changing your worktree, then prints the `git push` command. Push the branch within five minutes before the migration intent expires. The branch is safe to delete afterward. You can also add secrets and variables manually with `depot ci secrets add` / `depot ci vars add` (see `secrets-and-variables.md`).
+
+`--yes` is accepted but has no effect on `secrets-and-vars`; the subcommand does not show a preview or confirmation prompt.
-| Flag | Description |
-| ------------------ | ---------------------------------------------------------- |
-| `-y, --yes` | Skip preview and confirmation prompts |
-| `--branch <name>` | Override the branch name used for the migration workflow |
-| `--secrets <name>` | Secret name to include; repeatable. Omit to include all. |
-| `--vars <name>` | Variable name to include; repeatable. Omit to include all. |
+| Flag | Description |
+| -------------------------- | -------------------------------------------------------------------- |
+| `--branch-prefix <prefix>` | Prefix for the temporary migration branch; the intent ID is appended |
+| `--secrets <name>` | Secret name to include; repeatable. Omit to include all. |
+| `--vars <name>` | Variable name to include; repeatable. Omit to include all. |
## Manual setup (without the migrate command)
diff --git a/.agents/skills/depot-ci/references/oidc.md b/.agents/skills/depot-ci/references/oidc.md
index 6b1c7e4f137c..20249565c68e 100644
--- a/.agents/skills/depot-ci/references/oidc.md
+++ b/.agents/skills/depot-ci/references/oidc.md
@@ -71,18 +71,22 @@ The general steps are the same for any OIDC-compatible provider:
## The `sub` claim and wildcards
-Scope trust policies by matching the `sub` claim. Full form:
+Scope trust policies by matching the `sub` claim from left to right. Full form:
```text
spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/<ref>/sandbox/<sandboxID>
```
+Match the stable segments you need, then wildcard the remainder. The trust domain, organization ID, repository owner and name, and full Git ref are stable for their respective resources. Depot creates a new sandbox ID for every job, so never pin the final `sandbox/<sandboxID>` segment.
+
Wildcard matches:
- Everything in a GitHub org: `spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/*`
- A specific repository: `spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/*`
- A specific branch: `spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/<ref>/sandbox/*`
+AWS IAM exposes standard OIDC claims such as `aud` and `sub`, but it does not expose Depot's GitHub-compatible custom claims as condition keys. On AWS, match `identity.depot.dev:sub` with `StringLike`. Providers that map arbitrary claims into trust conditions can instead match flat claims such as `repository`, `repository_owner`, and `ref`.
+
## Migrating from GitHub Actions OIDC
`permissions: id-token: write` is required just as in GitHub Actions. What changes on the cloud-provider side:
@@ -91,7 +95,7 @@ Wildcard matches:
| ------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Issuer (`iss`) | `https://token.actions.githubusercontent.com` | `https://identity.depot.dev` |
| Subject (`sub`) | `repo:owner/repo:ref:refs/heads/main` | `spiffe://identity.depot.dev/org/<orgID>/ci/github/<owner>/<repo>/ref/<ref>/sandbox/<sandboxID>` |
-| Repo/branch scoping | `sub` (encoded in the subject) | `sub`, or `repository` + `ref` claims (separate conditions) |
+| Repo/branch scoping | `sub` (encoded in the subject) | `sub`; match stable segments and wildcard the per-job sandbox suffix |
| JWKS endpoint | `https://token.actions.githubusercontent.com/.well-known/jwks.json` | `https://identity.depot.dev/keys` |
Add `https://identity.depot.dev` as a new identity provider and create a new trust policy rather than modifying the existing GitHub Actions one, so both providers work in parallel during the transition.
@@ -103,3 +107,5 @@ Standard claims: `iss`, `sub`, `aud` (set by the workload request, for example `
GitHub Actions-compatible claims: `repository`, `repository_owner`, `repository_id`, `repository_owner_id`, `repository_visibility`, `ref`, `ref_type`, `sha`, `actor`, `actor_id`, `event_name`, `head_ref`, `base_ref`, `workflow`, `workflow_ref`, `workflow_sha`, `run_id`, `run_number`, `run_attempt`.
Depot-specific claims: `org_id` (Depot organization ID), `job_id` (Depot CI job ID).
+
+Use the exact organization ID from Depot settings for `org_id` and the `/org/<orgID>/` subject segment. Do not add an `org_` prefix.
diff --git a/.agents/skills/depot-ci/references/posthog-check-run-semantics.md b/.agents/skills/depot-ci/references/posthog-check-run-semantics.md
index 864a47222778..6cdc0680c353 100644
--- a/.agents/skills/depot-ci/references/posthog-check-run-semantics.md
+++ b/.agents/skills/depot-ci/references/posthog-check-run-semantics.md
@@ -60,6 +60,10 @@ Depot creates a job's check run when it resolves the job, not when it creates th
## Reruns
+GitHub's Re-run button on a Depot check does nothing. GitHub's [checks guide](https://docs.github.com/en/rest/guides/using-the-rest-api-to-interact-with-checks) says the request goes to the GitHub App that created the check run, and Depot's app does not act on it: measured 2026-10-16, GitHub reported the rerun as requested and Depot started no attempt.
+A `/depot retry` comment on the pull request starts the retry instead. `.depot/workflows/retry-on-comment.yml` runs `depot ci retry --failed` on the pull request's newest run.
+That command works while other jobs of the workflow still run, and it reruns the jobs downstream of each retried job, so the gate reads the new attempt.
+
Retrying a failed Depot job created a new check run with the same name and left the failed one behind in the measured 2026-09-17 run `jb7zh5rvnk`: the retried cell got check run `105270302262` while `105262890457` stayed `completed/failure`; only `filter=all` on the check-runs API listed both. GitHub Actions does the same per attempt, which is why a superseded run can show a stale red check beside a green one of the same name. Read the latest check run per name when you script against either engine: the API's default `filter=latest` returns only the newest, and `max_by(.id)` does the same on a full listing. Two details matter when the read decides something: a GitHub Actions rerun queues a fresh check run for every job before any of them runs, so a script that wants the last verdict filters on `status == "completed"` before it takes the newest; and the check-runs API lists every pull request's checks for a head SHA, so a script that acts for one pull request filters on `pull_requests[].number` when it is present.
Depot's list can still be empty. The [check suites API](https://docs.github.com/en/rest/checks/suites) says a suite is created when code is pushed and an app usually receives one suite event per commit SHA even if that SHA is pushed to multiple branches. On commit `f786b640f2f0`, Depot's suite `97293642167` names a `posthog/rewrite-tmp/` branch and has `pull_requests: []`, while GitHub Actions suites on the same commit name PR 104868's branch and list that PR. Commit `749f24dd5b7a` shows the same split with a `-rebase-1` branch. This is consistent with the suite retaining an earlier push branch, but the suite records do not establish push order. Filtering those Depot checks by `pull_requests[].number` finds no check for the PR.
diff --git a/.agents/skills/depot-ci/references/runs-and-debugging.md b/.agents/skills/depot-ci/references/runs-and-debugging.md
index 73b525b422be..802c177a2e9a 100644
--- a/.agents/skills/depot-ci/references/runs-and-debugging.md
+++ b/.agents/skills/depot-ci/references/runs-and-debugging.md
@@ -136,11 +136,17 @@ depot ci status <run-id>
# JSON output (full workflow/job/attempt tree, including SSH and log download metadata)
depot ci status <run-id> --output json
+
+# Wait for the final result
+depot ci status <run-id> --wait --output json
```
-| Flag | Description |
-| -------------- | ---------------------------------------------------- |
-| `-o, --output` | Output as JSON instead of the hierarchical text view |
+| Flag | Description |
+| -------------- | ---------------------------------------------------------------------- |
+| `-o, --output` | Output as JSON instead of the hierarchical text view |
+| `--wait` | Poll every five seconds until the run finishes, fails, or is cancelled |
+
+With `--wait`, progress goes to stderr and the final status goes to stdout. Exit code is `0` for a finished run and `1` for a failed or cancelled run.
In the JSON tree, `download_available` becomes `true` and `download_command` appears once an attempt reaches `finished`. `ssh_available` and `ssh_command` appear only while an attempt is running with a sandbox.
@@ -279,6 +285,8 @@ depot ci artifacts download <artifact-id> --output-file coverage.zip
Diagnoses a failed run, workflow, job, or attempt using bounded stored failure context. The command groups similar failures across attempts and, where available, surfaces a diagnosis and a possible fix for each group, with evidence lines and drill-down commands. Exactly one of `--run`, `--workflow`, `--job`, or `--attempt` is required; positional target IDs aren't accepted.
+The diagnosis and possible fix are AI-generated. Verify each suggestion against the evidence and job logs before changing code.
+
```bash
depot ci diagnose --run <run-id>
depot ci diagnose --workflow <workflow-id>
@@ -417,7 +425,7 @@ depot ci rerun <run-id> --output json
## `depot ci retry`
-Retries a single failed or cancelled job with `--job <job-id>`, or every failed/cancelled job in a workflow with `--failed`. Exactly one of `--job` or `--failed` must be set. With `--job` the containing workflow is resolved automatically; with `--failed` on a multi-workflow run, `--workflow <id>` is required. Each retry creates a new attempt; previous attempts remain visible in `depot ci status`.
+Retries a single failed or cancelled job with `--job <job-id>`, or every failed/cancelled job and all downstream jobs in a workflow with `--failed`. Downstream jobs include succeeded and skipped jobs. Exactly one of `--job` or `--failed` must be set. With `--job` the containing workflow is resolved automatically; with `--failed` on a multi-workflow run, `--workflow <id>` is required. Each retry creates a new attempt; previous attempts remain visible in `depot ci status`.
```bash
# Retry a single job
@@ -433,12 +441,12 @@ depot ci retry <run-id> --failed --workflow <workflow-id>
depot ci retry <run-id> --job <job-id> --output json
```
-| Flag | Description |
-| ----------------- | ---------------------------------------------------------------------------------- |
-| `--job <id>` | Job ID to retry (mutually exclusive with `--failed`) |
-| `--failed` | Retry every failed/cancelled job in the workflow (mutually exclusive with `--job`) |
-| `--workflow <id>` | Workflow ID; required with `--failed` when the run has multiple workflows |
-| `--output json` | Output the RPC response as JSON |
+| Flag | Description |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `--job <id>` | Job ID to retry (mutually exclusive with `--failed`) |
+| `--failed` | Retry failed/cancelled jobs and all downstream jobs (mutually exclusive with `--job`) |
+| `--workflow <id>` | Workflow ID; required with `--failed` when the run has multiple workflows |
+| `--output json` | Output the RPC response as JSON |
---
diff --git a/.agents/skills/depot-ci/references/secrets-and-variables.md b/.agents/skills/depot-ci/references/secrets-and-variables.md
index 4c3ea6803030..f8306e8415a4 100644
--- a/.agents/skills/depot-ci/references/secrets-and-variables.md
+++ b/.agents/skills/depot-ci/references/secrets-and-variables.md
@@ -22,6 +22,10 @@ Variants are managed from the CLI (selectors on `add`, `set`, `bulk`, `get`, `li
Selector flags are repeatable, and `--branch`/`--workflow` accept glob patterns. On `add`/`set`/`bulk` they scope where a variant applies; on `get`/`list`/`remove` they select or filter existing variants.
+For `add` and `set`, omit the variant name or use `default` to update the variant with exactly the supplied selectors. If none matches, Depot creates a variant. New repository variants use repository-derived names, with numeric suffixes to avoid collisions. Use a non-default name to select a named variant.
+
+Repository variants follow GitHub repositories through renames and transfers. A new repository under an old name does not inherit the original repository's values. The server resolves repository selectors, including previous repository names.
+
## Access rule kinds
Limit when a variant is selected by combining one or more rules:
@@ -53,7 +57,7 @@ Secrets are referenced in workflows as `${{ secrets.SECRET_NAME }}`. Secret valu
### `depot ci secrets add`
-Adds a secret variant. Three modes: interactive prompt (`depot ci secrets add NAME`), piped stdin (`printf '%s' "$V" | depot ci secrets add NAME`), or bulk `KEY=VALUE` pairs (`depot ci secrets add FOO=bar BAZ=qux`, `--description` not allowed in this mode). An optional second positional names the variant; without it the value writes to the `default` variant.
+Adds a secret variant. Three modes: interactive prompt (`depot ci secrets add NAME`), piped stdin (`printf '%s' "$V" | depot ci secrets add NAME`), or bulk `KEY=VALUE` pairs (`depot ci secrets add FOO=bar BAZ=qux`, `--description` not allowed in this mode). An optional second positional names the variant; omit the name to select by the supplied selectors.
| Flag | Description |
| ---------------------- | ------------------------------------------------------------- |
diff --git a/.agents/skills/depot-container-builds/SKILL.md b/.agents/skills/depot-container-builds/SKILL.md
index 50620542d3f3..78fdb3c34c65 100644
--- a/.agents/skills/depot-container-builds/SKILL.md
+++ b/.agents/skills/depot-container-builds/SKILL.md
@@ -7,19 +7,19 @@ description: >
failures, optimizing Dockerfile layer caching, using docker-bake.hcl or docker-compose builds,
or migrating from `docker build` / `docker buildx build` to Depot. Also use when the user
mentions depot build, depot bake, container builds, image builds, or asks about Depot's
- build cache, build parallelism, or ephemeral registry.
+ build cache, build parallelism, build autoscaling, or ephemeral registry.
---
# Depot Container Builds
+Depot runs Docker image builds on remote high-performance builders (16 CPU, 32 GB RAM, NVMe SSD cache). `depot build` is a drop-in replacement for `docker build` / `docker buildx build`. `depot bake` replaces `docker buildx bake`.
+
<!-- PostHog-local section. Keep it when resyncing from upstream; see UPSTREAM.md. -->
Before you propose a change to CI, check [things already tried](../../../docs/internal/ci-things-already-tried.md) for the idea. It records what was measured, and why some good-sounding changes were reverted or rejected.
<!-- End PostHog-local section. -->
-Depot runs Docker image builds on remote high-performance builders (16 CPU, 32 GB RAM, NVMe SSD cache). `depot build` is a drop-in replacement for `docker build` / `docker buildx build`. `depot bake` replaces `docker buildx bake`.
-
## Project Selection for Multi-Org Users
Container build commands target a specific project, not an organization. If expected projects aren't visible or a build unexpectedly prompts to select a project, the current default org may be wrong:
@@ -107,12 +107,14 @@ Drop-in replacement for `docker buildx bake`. Builds multiple images in parallel
depot bake # Default file lookup
depot bake -f docker-bake.hcl # Specific HCL file
depot bake -f docker-compose.yml --load # Build compose services + load locally
-depot bake --save --save-tag myrepo/app:v1 # Save to Depot Registry
+depot bake --save --save-tag v1 # Save as v1-<target-name> in Depot Registry
depot bake --print # Print resolved config without building
```
**Default file lookup order:** compose.yaml → compose.yml → docker-compose.yml → docker-compose.yaml → docker-bake.json → docker-bake.hcl → docker-bake.override.json → docker-bake.override.hcl
+Without target arguments, `depot bake` builds the `default` group. Saved tags use `<build-id>-<target-name>`; `--save-tag v1` adds `v1-<target-name>`. Use `--save --push` to save in Depot Registry and push the configured target tags. Set `project_id` in an HCL target to select its Depot project.
+
### HCL Bake File Example
```hcl
@@ -211,6 +213,14 @@ docker build . # Routes through Depot (look for [depot] prefix in logs)
Billed per-second. Large and Extra Large builders consume your included build minutes faster (via the multiplier) in addition to costing more per minute.
+## Build Autoscaling
+
+Autoscaling is disabled by default, so Depot routes a project's builds for each architecture to one builder. Enable horizontal autoscaling in the project settings when concurrent builds need separate builders. The settings form preselects 16 builds per instance; Depot starts another builder when concurrent builds reach the configured limit.
+
+Each builder has an independent cache. Heavy autoscaling can reduce cache efficiency, so try a larger builder first when one build needs more CPU or memory. Autoscaling is available on all plans without an additional fee.
+
+One `depot bake` invocation counts as one build for autoscaling, regardless of its target count. Separate project IDs create separate build requests.
+
## Depot Registry
An OCI-compliant registry that works both as a lightweight ephemeral store for build output and as a full primary registry for all your images (including ones not built with Depot). Each org gets its own subdomain `{orgId}.registry.depot.dev`, backed by a global CDN, and stores images and OCI artifacts (Helm charts, AI models) up to 50 GB. Browse repositories, tags, and attestations in the Registry Explorer in the dashboard.
@@ -222,28 +232,41 @@ depot build --save -t myapp .
# Push any image to Depot Registry as a primary registry
docker push {orgId}.registry.depot.dev/your/app:v1
-# Pull a saved image (by build ID or by tag)
+# Pull a saved project image (by build ID or by tag)
depot pull --project <id> <build-id>
depot pull --project <id> my-image:tag
depot pull --project <id> --platform linux/arm64 <build-id> # pull a specific platform
-# Generate a short-lived (1-hour) read-only token to pull from the Depot Registry
+# Generate a 1-hour read-only token for the project's registry paths
depot pull-token --project <id>
depot pull-token --project <id> <build-id> # scoped to a specific build
# Push saved image to another registry
depot push --project <id> -t registry/image:tag <build-id>
+# List saved images as JSON
+depot image list --project <id> --output json
+
+# Delete selected image tags only when requested
+depot image rm --project <id> app:old app:staging
+
# Docker auth for Depot Registry (each org has its own subdomain)
-docker login {orgId}.registry.depot.dev -u x-token -p <depot-token>
+docker login {orgId}.registry.depot.dev -u x-token
+# Enter a scoped registry access token at the password prompt.
# Registry URL: {orgId}.registry.depot.dev/your/app:tag
# (the legacy registry.depot.dev/<project-id>:<build-id> form still works for existing usage)
```
Image retention defaults to 7 days but is configurable per repository from the Registry Explorer, either by age (1, 7, 14, or 30 days) or by tag count (5, 10, 25, 50, or 100 tags).
+For custom image names, use a registry access token. Organization owners create tokens in Registry Settings → Registry access tokens. Select Pull or Push permission; Push includes pull access. Scope tokens to exact paths (`frontend`), one level (`team/*`), any depth (`team/**`), or all repositories (`**`). Exclude registry hostnames and image tags from scopes.
+
+Use `depot pull` for saved project builds and tags, and `docker pull` for custom or pull-through repositories. CLI pull tokens cover only `<project-id>` and its descendant paths. Use a registry access token with Pull permission for other names.
+
**Pull-through cache:** Depot Registry can proxy an external registry and cache its layers on the CDN, so repeat pulls skip the upstream hop (faster CI pulls, global distribution, simpler auth for registries like Google Artifact Registry). Configure an upstream in Registry Settings; supported providers are Docker Hub, GitHub Container Registry, GitLab Container Registry, Quay.io, AWS ECR, Google Artifact Registry, Azure Container Registry, and custom registries. Pull-through must be set when the repository is created, it can't be added to an existing repository.
+Cached mutable tags such as `latest` are not refreshed from upstream on every pull. Use a new immutable tag or digest to select updated content. Missing or reclaimed content still requires the upstream registry, so caching does not guarantee availability during an upstream outage.
+
## Special Output Formats
```bash
diff --git a/.agents/skills/depot-container-builds/UPSTREAM.md b/.agents/skills/depot-container-builds/UPSTREAM.md
index 9919a1c44362..5c55c1b0d4f1 100644
--- a/.agents/skills/depot-container-builds/UPSTREAM.md
+++ b/.agents/skills/depot-container-builds/UPSTREAM.md
@@ -3,7 +3,7 @@
Vendored from [depot/skills](https://github.com/depot/skills) — used by PostHog's container-image CI/CD (`depot/build-push-action`, `depot/setup-action`).
- Source: `skills/depot-container-builds/SKILL.md`
-- Commit: [`81795ab`](https://github.com/depot/skills/tree/81795abf98f81fb112cda35720e19b2aa3efa640/skills/depot-container-builds) (2026-09-01)
+- Commit: [`71f008d`](https://github.com/depot/skills/tree/71f008de4dbfa8625ece3df85019bc914b9399a0/skills/depot-container-builds) (2026-10-15)
- License: none in upstream at this commit; README documents `cp SKILL.md` install.
## Local additions
diff --git a/.agents/skills/depot-github-runners/SKILL.md b/.agents/skills/depot-github-runners/SKILL.md
index ea28adf8ea67..6acd97831489 100644
--- a/.agents/skills/depot-github-runners/SKILL.md
+++ b/.agents/skills/depot-github-runners/SKILL.md
@@ -55,12 +55,12 @@ Use a single label. Format: `depot-{os}-{version}[-{arch}][-{size}]`
| Label | CPUs | RAM | Disk | $/min | Minutes multiplier |
| ----------------------- | ---- | ------ | ------ | ------ | ------------------ |
-| `depot-ubuntu-24.04` | 2 | 8 GB | 100 GB | $0.004 | 1x |
-| `depot-ubuntu-24.04-4` | 4 | 16 GB | 130 GB | $0.008 | 2x |
-| `depot-ubuntu-24.04-8` | 8 | 32 GB | 150 GB | $0.016 | 4x |
-| `depot-ubuntu-24.04-16` | 16 | 64 GB | 180 GB | $0.032 | 8x |
-| `depot-ubuntu-24.04-32` | 32 | 128 GB | 200 GB | $0.064 | 16x |
-| `depot-ubuntu-24.04-64` | 64 | 256 GB | 250 GB | $0.128 | 32x |
+| `depot-ubuntu-24.04` | 2 | 8 GB | 100 GB | $0.006 | 1x |
+| `depot-ubuntu-24.04-4` | 4 | 16 GB | 130 GB | $0.012 | 2x |
+| `depot-ubuntu-24.04-8` | 8 | 32 GB | 150 GB | $0.024 | 4x |
+| `depot-ubuntu-24.04-16` | 16 | 64 GB | 180 GB | $0.048 | 8x |
+| `depot-ubuntu-24.04-32` | 32 | 128 GB | 200 GB | $0.096 | 16x |
+| `depot-ubuntu-24.04-64` | 64 | 256 GB | 250 GB | $0.192 | 32x |
The minutes multiplier is the billing driver: billed minutes = elapsed minutes × multiplier, so larger runners consume your included minutes faster.
@@ -86,15 +86,15 @@ Windows Server 2022 also available: `depot-windows-2022`, etc.
| Label | CPUs | RAM | Disk | $/min |
| --------------------------------------- | ---- | ----- | ------ | ----- |
-| `depot-macos-26` | 8 | 24 GB | 400 GB | $0.08 |
-| `depot-macos-15` / `depot-macos-latest` | 8 | 24 GB | 400 GB | $0.08 |
+| `depot-macos-26` / `depot-macos-latest` | 8 | 24 GB | 400 GB | $0.08 |
+| `depot-macos-15` | 8 | 24 GB | 400 GB | $0.08 |
| `depot-macos-14` | 8 | 24 GB | 400 GB | $0.08 |
macOS is NOT fully elastic — fixed pool with FIFO queuing.
### Aliases
-`depot-ubuntu-latest` → Ubuntu 24.04, `depot-windows-latest` → Windows 2025, `depot-macos-latest` → macOS 15
+`depot-ubuntu-latest` → Ubuntu 24.04, `depot-windows-latest` → Windows 2025, `depot-macos-latest` → macOS 26
## Migration Example
@@ -127,19 +127,22 @@ Actions using the GitHub Actions cache API automatically use **Depot Cache** —
**Pre-configured build tool caches** (zero config on Depot runners):
-| Tool | What's pre-configured |
-| --------- | -------------------------------------------------------------- |
-| Turborepo | `TURBO_API` env var set — just run `turbo build` |
-| Bazel | `~/.bazelrc` pre-populated — just run `bazel build //...` |
-| sccache | `SCCACHE_WEBDAV_ENDPOINT` set — use `RUSTC_WRAPPER: 'sccache'` |
-| Maven | `settings.xml` pre-populated (cache id `depot-cache`) |
-| Pants | `pants.toml` pre-configured — just run `pants package ::` |
-| moonrepo | Env vars set — just run `moon run build` |
+| Tool | What's pre-configured |
+| --------- | ------------------------------------------------------------------------- |
+| Turborepo | `TURBO_API` env var set — just run `turbo build` |
+| Bazel | `~/.bazelrc` pre-populated — just run `bazel build //...` |
+| sccache | `SCCACHE_WEBDAV_ENDPOINT` set — use `RUSTC_WRAPPER: 'sccache'` |
+| Maven | `settings.xml` pre-populated (cache id `depot-cache`) |
+| Pants | `pants.toml` pre-configured — just run `pants package ::` |
+| moonrepo | Env vars set — just run `moon run build` |
+| Xcode 26+ | Compilation caching uses Depot Cache automatically on Depot macOS runners |
Cache behavior: repository-scoped, no branch isolation, encrypted, up to 1000 MiB/s throughput, configurable retention (7/14/30 days).
To disable auto-cache: org settings → turn off "Allow Actions jobs to automatically connect to Depot Cache."
+For Xcode, the runner sets `XCODE_XCCONFIG_FILE` only when the job does not supply its own configuration file. Set `DEPOT_XCODE_CACHE_ENABLED: '0'` to opt out for a job or workflow. Add `depot/xcode-compilation-cache-summary@v1` after the build to report cache statistics. Xcode compilation caching is not supported on local workstations. See https://depot.dev/docs/cache/integrations/xcode for build settings and troubleshooting.
+
## Dagger Integration
**Deprecated:** Dagger Engine support on Depot GitHub Actions Runners is being deprecated and will be removed in a future update. Don't recommend this integration for new workflows.
diff --git a/.agents/skills/depot-github-runners/UPSTREAM.md b/.agents/skills/depot-github-runners/UPSTREAM.md
index ee10c736208e..ef5c310c1c46 100644
--- a/.agents/skills/depot-github-runners/UPSTREAM.md
+++ b/.agents/skills/depot-github-runners/UPSTREAM.md
@@ -3,7 +3,7 @@
Vendored from [depot/skills](https://github.com/depot/skills) — used by PostHog workflows pinning `depot-ubuntu-*` runners.
- Source: `skills/depot-github-runners/SKILL.md`
-- Commit: [`81795ab`](https://github.com/depot/skills/tree/81795abf98f81fb112cda35720e19b2aa3efa640/skills/depot-github-runners) (2026-09-01)
+- Commit: [`71f008d`](https://github.com/depot/skills/tree/71f008de4dbfa8625ece3df85019bc914b9399a0/skills/depot-github-runners) (2026-10-15)
- License: none in upstream at this commit; README documents `cp SKILL.md` install.
## Local additions
diff --git a/.depot/workflows/ci-backend.yml b/.depot/workflows/ci-backend.yml
index 0e68e44ffd2f..9f7d3e72d23d 100644
--- a/.depot/workflows/ci-backend.yml
+++ b/.depot/workflows/ci-backend.yml
@@ -4353,11 +4353,12 @@ jobs:
# can answer 404, because GitHub does not always find a check it just created.
# GitHub rejects a summary over 65535 characters, and the byte budget below stays
# under that however the characters are encoded.
+ # The retry hint goes first, because the byte budget trims the summary from the end.
touch "$GATE_SUMMARY"
jq -n --arg name "$GATE_CHECK" --arg sha "$SHA" --arg conclusion "$CONCLUSION" --arg url "$DEPOT_JOB_URL" \
--arg title "$title" --rawfile summary "$GATE_SUMMARY" \
'{name: $name, head_sha: $sha, status: "completed", conclusion: $conclusion, details_url: $url,
- output: {title: $title, summary: ($summary | if utf8bytelength > 60000 then until(utf8bytelength <= 60000; .[:-1000]) + "\n\n(truncated)" else . end)}}' \
+ output: {title: $title, summary: ((if $conclusion == "failure" then "To retry the failed jobs without a new push, comment `/depot retry` on this pull request.\n\n" else "" end) + $summary | if utf8bytelength > 60000 then until(utf8bytelength <= 60000; .[:-1000]) + "\n\n(truncated)" else . end)}}' \
| gh api "repos/$REPO/check-runs" --method POST --input - --silent && exit 0
# A rejected output must not lose the check.
echo "::warning::Could not post the gate check with its summary. Posting it without."
diff --git a/.depot/workflows/retry-on-comment.yml b/.depot/workflows/retry-on-comment.yml
new file mode 100644
index 000000000000..64fa625f4a27
--- /dev/null
+++ b/.depot/workflows/retry-on-comment.yml
@@ -0,0 +1,36 @@
+# A `/depot retry` comment on a pull request retries the failed and cancelled jobs of its newest Depot CI
+# run, without waiting for the rest of the run and without a push that reruns every workflow.
+#
+# Depot CI runs issue_comment workflows from the default branch, so pull request code never runs here.
+name: Retry Depot CI from a comment
+on:
+ issue_comment:
+ types: [created]
+permissions:
+ contents: read
+jobs:
+ retry:
+ name: Retry failed Depot CI jobs
+ # The repository is public, so only organization members and collaborators can start a retry.
+ if: >
+ github.event.issue.pull_request
+ && startsWith(github.event.comment.body, '/depot retry')
+ && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
+ # On the job, not the workflow, so a skipped run for any other comment cannot cancel a queued retry.
+ # A second retry waits for the first, then finds its jobs requeued and retries nothing.
+ concurrency:
+ group: ${{ github.workflow }}-pr-${{ github.event.issue.number }}
+ cancel-in-progress: false
+ runs-on: depot-ubuntu-24.04
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ sparse-checkout: .github/scripts
+ - uses: depot/setup-action@15c09a5f77a0840ad4bce955686522a257853461 # v1.7.1
+ - name: Retry this PR's failed Depot jobs
+ env:
+ DEPOT_TOKEN: ${{ secrets.DEPOT_CI_CANCEL_TOKEN }}
+ REPO: ${{ github.repository }}
+ PR_NUMBER: ${{ github.event.issue.number }}
+ run: python3 .github/scripts/retry_depot_pr_run.py
diff --git a/.github/scripts/cancel_superseded_depot_runs.py b/.github/scripts/cancel_superseded_depot_runs.py
index ea8bddc07c1a..a8dd9ce36cd6 100644
--- a/.github/scripts/cancel_superseded_depot_runs.py
+++ b/.github/scripts/cancel_superseded_depot_runs.py
@@ -21,6 +21,7 @@ import subprocess
from collections.abc import Sequence
from dataclasses import dataclass
from datetime import datetime
+from typing import Any
WORKFLOW_PATH = "ci-backend.yml"
ACTIVE = ("queued", "running")
@@ -64,18 +65,18 @@ def superseded(own_workflow_id: str, active_workflows: Sequence[Workflow], runs:
]
-def depot(*args: str) -> list[dict[str, str]]:
+def depot(*args: str) -> Any:
# stderr passes through, so a failed call explains itself in the job log.
result = subprocess.run(
["depot", "ci", *args], check=True, stdout=subprocess.PIPE, text=True, timeout=CLI_TIMEOUT_SECONDS
)
- # `depot ci run list` prints `null` when nothing matches.
- return json.loads(result.stdout) or []
+ return json.loads(result.stdout)
def list_pr(noun: str, repo: str, pr_number: str, statuses: Sequence[str]) -> list[dict[str, str]]:
scope = ["--repo", repo, "--pr", pr_number, "--trigger", "pull_request", "-n", "200", "-o", "json"]
- return depot(noun, "list", *scope, *(flag for status in statuses for flag in ("--status", status)))
+ # `depot ci run list` prints `null` when nothing matches.
+ return depot(noun, "list", *scope, *(flag for status in statuses for flag in ("--status", status))) or []
def main() -> int:
diff --git a/.github/scripts/retry_depot_pr_run.py b/.github/scripts/retry_depot_pr_run.py
new file mode 100644
index 000000000000..c936f5b01f55
--- /dev/null
+++ b/.github/scripts/retry_depot_pr_run.py
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Retry the failed and cancelled jobs of a pull request's newest Depot CI run.
+
+.depot/workflows/retry-on-comment.yml runs this for a `/depot retry` comment.
+See "Reruns" in .agents/skills/depot-ci/references/posthog-check-run-semantics.md.
+
+Standard library only: the job runs this with the runner's python3 before any install.
+"""
+
+import os
+import sys
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any
+
+from cancel_superseded_depot_runs import ALL, depot, list_pr
+
+RETRYABLE = ("failed", "cancelled")
+
+
+def newest_run_id(runs: Sequence[dict[str, str]]) -> str | None:
+ # Run ids are random, so they cannot break a same-second tie. max() keeps the first of equal
+ # times, and `depot ci run list` lists the newest run first.
+ newest = max(runs, key=lambda run: datetime.fromisoformat(run["created_at"]), default=None)
+ return newest["run_id"] if newest else None
+
+
+def retryable_workflow_ids(status: dict[str, Any]) -> list[str]:
+ return [
+ workflow["workflow_id"]
+ for workflow in status.get("workflows") or []
+ if any(job["status"] in RETRYABLE for job in workflow.get("jobs") or [])
+ ]
+
+
+def main() -> None:
+ repo, pr_number = os.environ["REPO"], os.environ["PR_NUMBER"]
+ run_id = newest_run_id(list_pr("run", repo, pr_number, ALL))
+ if not run_id:
+ sys.stdout.write(f"::notice::PR {pr_number} has no Depot run to retry.\n")
+ return
+ # A run that has no workflow yet has a `null` status.
+ workflow_ids = retryable_workflow_ids(depot("status", run_id, "-o", "json") or {})
+ for workflow_id in workflow_ids:
+ sys.stdout.write(f"Retrying the failed and cancelled jobs of run {run_id} (workflow {workflow_id})\n")
+ depot("retry", run_id, "--failed", "--workflow", workflow_id, "-o", "json")
+ if not workflow_ids:
+ sys.stdout.write(f"::notice::PR {pr_number} has no failed or cancelled Depot jobs to retry.\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.github/scripts/test_retry_depot_pr_run.py b/.github/scripts/test_retry_depot_pr_run.py
new file mode 100644
index 000000000000..fb7f3d237d21
--- /dev/null
+++ b/.github/scripts/test_retry_depot_pr_run.py
@@ -0,0 +1,45 @@
+import importlib.util
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+SCRIPT_PATH = Path(__file__).with_name("retry_depot_pr_run.py")
+SPEC = importlib.util.spec_from_file_location("retry_depot_pr_run", SCRIPT_PATH)
+assert SPEC is not None
+assert SPEC.loader is not None
+script = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(script)
+
+
+def run(run_id: str, second: int) -> dict[str, str]:
+ return {"run_id": run_id, "created_at": f"2026-10-16T12:00:{second:02d}Z"}
+
+
+def workflow(workflow_id: str, *job_statuses: str) -> dict[str, Any]:
+ return {"workflow_id": workflow_id, "jobs": [{"status": status} for status in job_statuses]}
+
+
+ "runs,expected",
+ [
+ pytest.param([run("b", 9), run("a", 5)], "b", id="newest_by_time"),
+ pytest.param([run("z", 5), run("a", 5)], "z", id="same_second_tie_keeps_list_order"),
+ pytest.param([], None, id="no_runs"),
+ ],
+)
+def test_newest_run_id(runs: list[dict[str, str]], expected: str | None) -> None:
+ assert script.newest_run_id(runs) == expected
+
+
+ "workflows,expected",
+ [
+ pytest.param([workflow("w", "finished", "running", "failed")], ["w"], id="failed_job_mid_run"),
+ pytest.param([workflow("w", "finished", "cancelled")], ["w"], id="cancelled_job"),
+ pytest.param([workflow("w", "finished", "skipped", "running")], [], id="nothing_failed"),
+ pytest.param([workflow("a", "failed"), workflow("b", "finished")], ["a"], id="only_failed_workflow"),
+ ],
+)
+def test_retryable_workflow_ids(workflows: list[dict[str, Any]], expected: list[str]) -> None:
+ assert script.retryable_workflow_ids({"workflows": workflows}) == expected