Merge pull request #168 from depot/docs-sync-updates

Update content from depot/app

Author: jacobwgillespie

content/ci/compatibility.mdx

@@ -130,6 +130,10 @@ Depot CI executes GitHub Actions YAML workflows. The following tables list GitHu
 | Composite  | Composite actions        | ✅            |
 | Docker     | Container actions        | ✅            |
 
+## GitHub checks
+
+Depot CI automatically reports GitHub checks for each job in a workflow run. For more information, see [GitHub checks](/docs/ci/observability/github-checks).
+
 ## Limitations
 
 ### GitHub-only event triggers
@@ -183,4 +187,27 @@ Only Depot `runs-on` labels are supported. Any label that Depot doesn't recogniz
 
 ### Permissions
 
-The following permissions are supported: `actions`, `checks`, `contents`, `id-token`, `metadata`, `packages`, `pull_requests`, `statuses`, `workflows`.
+The following permissions are supported: `actions`, `checks`, `contents`, `id-token`, `metadata`, `pull_requests`, `statuses`, `workflows`.
+
+#### GitHub Packages authentication
+
+Pushing and pulling from GitHub Packages registries using `secrets.GITHUB_TOKEN` doesn't work in Depot CI. GitHub's package registry servers only accept personal access tokens for authentication, not GitHub App tokens. This is a known GitHub limitation (see discussions: [Read GitHub Packages permission for GitHub App](https://github.com/orgs/community/discussions/24636) and [Using GitHub Packages with GitHub Apps](https://github.com/orgs/community/discussions/26920)).
+
+For container images, you can use another registry instead, such as [Depot Registry](/docs/registry/overview). When using `depot/build-push-action`, replace the GHCR login and push steps with the `save` input:
+
+```yaml
+- uses: depot/build-push-action@v1
+  with:
+    context: .
+    project: <your-depot-project-id>
+    save: true
+    save-tags: |
+      latest
+      ${{ github.sha }}
+```
+
+See the [Depot Registry quickstart](/docs/registry/quickstart) for pulling images and other usage.
+
+This limitation applies to all GitHub Packages registries, not just the container registry. If you need to keep using a GitHub Packages registry, you can authenticate with a GitHub [personal access token](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic) with `write:packages` scope, [stored as a Depot CI secret](/docs/ci/how-to-guides/manage-secrets-and-variables).
+
+Note that a PAT is a long-lived credential scoped to a user account, so consider the security implications of storing and rotating it.

content/ci/how-to-guides/coding-agents.mdx

@@ -0,0 +1,153 @@
+---
+title: Use Depot CI in coding agent loops
+ogTitle: How to use Depot CI CLI commands for coding agent loops
+description: Learn how to get your coding agent iterating locally with Depot CI.
+---
+
+Depot CI is built for programmatic use, so it's a natural fit for AI coding agents. Instead of the usual push-wait-guess cycle, an agent can run CI locally, read the failure, fix the code, and rerun, all in a closed loop from your terminal.
+
+This guide provides an example of how to set up that loop. The guide covers Claude Code and Cursor, but the pattern works for any agent with shell access.
+
+## The agent loop
+
+You're working with an agent on a task, and you want to make sure CI passes before moving on or pushing your changes.
+
+No human needs to approve each step. You tell the agent to fix CI, and the agent iterates until it's done.
+
+![Agent fix-CI loop: tell agent to fix CI, agent triggers run scoped to
+  smallest job, checks status, reads logs from failed jobs, SSHs into runner if
+  logs aren't enough, fixes code, reruns until CI
+  passes](/images/docs/agent-loop.png)
+
+For a raw narrative version of this pattern, see the blog post [The End of push-wait-guess CI](/blog/the-end-of-push-wait-guess-ci).
+
+## Why the CLI works well for agents
+
+Most coding agents already have a shell. The Depot CLI gives them CI without any HTTP plumbing. `depot ci run` tests workflows against your local working tree without requiring a commit or push. That's what makes the agent loop work: the agent can edit code and rerun CI in a tight loop without polluting the git history or waiting on long-running CI in GitHub.
+
+- `depot ci run` starts a run against your local working tree. Use `--job` to scope to specific jobs for faster iteration. The CLI resolves job dependencies automatically.
+- `depot ci status` shows the full run hierarchy, workflows, jobs, and attempts with their statuses.
+- `depot ci logs` fetches the log output for a failed job so the agent can read the error and fix it.
+- `depot ci ssh` connects directly to a running sandbox via the Depot API, giving you (or the agent) an interactive shell on the runner. To keep a sandbox alive at the right moment, use `depot ci run --ssh-after-step <n>` to inject a tmate debug pause after a specific step, then connect with `depot ci ssh` or the tmate connection string from the logs.
+
+## Prerequisites
+
+- Complete the Depot CI [quickstart](/docs/ci/quickstart).
+- Run `depot login` or set `DEPOT_TOKEN` so the agent can authenticate.
+- An AI coding agent with shell access (such as Claude Code or Cursor).
+
+## Install the Depot skills
+
+Install [Depot skills](https://github.com/depot/skills) to teach your agent how to get started with Depot and use all the Depot CLI commands for Depot CI.
+
+To install Depot skills with [skills.sh](https://skills.sh/), run `npx skills add depot/skills`.
+
+## Set up the fix CI loop command
+
+With the skills installed, create a command that tells the agent to use them, defines the loop, and sets the boundaries for what the agent can do autonomously.
+
+The example command for this guide is `/fix-ci`.
+
+Add a markdown file that defines the command to your repo. For example, in `.claude/commands/` or `.cursor/commands/`.
+
+Example `fix-ci.md`:
+
+```markdown
+Fix a Depot CI workflow, run, or job until it is green.
+
+### Before you start
+
+Invoke the `depot-ci` skill to load the full CLI reference. Then drive the debug loop.
+
+### Inputs
+
+Accept any of:
+
+- a workflow path (for example, `.depot/workflows/ci.yml`)
+- a run ID, job ID, or attempt ID
+- a target job name (for example, `build`)
+- a natural-language goal (for example, "make the test job pass")
+
+If the request is ambiguous, ask for the narrowest useful target.
+
+### The Loop
+
+1. **Run** the workflow against local changes, scoped to the smallest useful job.
+2. **Check status** and **read logs** for failed jobs.
+3. If logs aren't enough, connect to the running sandbox with **`depot ci ssh`**, or **rerun with `--ssh-after-step`** to pause at a specific step first.
+4. **Fix locally** based on what you found.
+5. **Rerun.** Repeat until green.
+
+### Autonomy
+
+The agent may: run workflows, inspect status/logs, SSH into runners, edit local files, and rerun until green.
+
+Ask before: changing secrets or vars, altering deploy or release behavior, opening a PR, or large refactors beyond the immediate fix.
+
+### When done, report
+
+- what was targeted
+- what was wrong
+- what changed
+- proof of green (or the exact remaining blocker)
+```
+
+The key ingredients are the same for any agent: install the skill so the agent has the CLI reference, then give it a command or prompt that describes the run-status-logs-ssh loop and the autonomy boundaries.
+
+## Give the agent permission to run the loop
+
+For the agent to iterate autonomously, it needs permission to run `depot` commands without prompting. How you configure permissions depends on your agent. Here are some examples.
+
+### Claude Code permissions
+
+Add a permission rule to `.claude/settings.json` to allow any Depot command:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(depot *)"]
+  }
+}
+```
+
+### Cursor permissions
+
+Add a permission rule to `<project>/.cursor/cli.json` to allow any Depot command:
+
+```json
+{
+  "permissions": {
+    "allow": ["Shell(depot)"]
+  }
+}
+```
+
+## Run the agent loop
+
+Type `/fix-ci .depot/workflows/ci.yml` (for example) in your agent chat and watch the agent take over. You can adjust your custom command using the tips in the following section.
+
+## Tips for customizing your agent loop
+
+### Iteration limits
+
+Cap the number of CI attempts so the agent doesn't loop forever on a fundamentally broken build. Three to five attempts is a reasonable default.
+
+### Log truncation
+
+CI logs can be long. If your agent has a limited context window, truncate logs to the last N lines or extract just the error output. Most failures surface near the end of the log.
+
+### Polling
+
+`depot ci status` returns immediately. It doesn't block until the run finishes. Agents will naturally poll by calling the status command in a loop. This works fine in practice.
+
+### Human approval gates
+
+If the agent shouldn't take certain actions autonomously, configure your agent's permission model to require approval for those commands. The `/fix-ci` command definition in the example includes suggested boundaries: the agent can run workflows, read logs, SSH in, and edit code, but should ask before changing secrets, deploying, or opening PRs.
+
+### Untracked files aren't patched
+
+`depot ci run` only includes tracked files in the local patch. If you've added a new file, use `git add` before running the agent, or add that step to your agent loop.
+
+## What's next
+
+The pattern in this guide is one way to implement a coding agent loop that uses Depot CI to iterate locally. Experiment with skills or sub agents or a mixture of these to create patterns that work for you. You can create more custom commands for managing or monitoring workflows with Depot CI. Learn more about the [Depot CI CLI commands](/docs/cli/reference/depot-ci) that your agents can use.

content/ci/how-to-guides/custom-images.mdx

@@ -6,17 +6,27 @@ description: Learn how to snapshot a Depot CI sandbox that includes your tools a
 
 import {NoteCallout} from '~/components/blog/NoteCallout'
 
-You can build a custom image in Depot CI using a job that runs only your setup steps on the Depot base image. After your setup steps complete, the snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely.
+Build a reusable custom image from the Depot base image that includes your tools and dependencies.
+
+## How it works
+
+You build a custom image in Depot CI using a job that runs only your setup steps on the Depot base image. After your setup steps complete, a Depot snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely.
 
 <NoteCallout fullWidth>
-  The snapshot action can only be used in workflows running on Depot CI. It is not compatible with GitHub Actions or
+  The snapshot action can only be used in workflows running on Depot CI. It's not compatible with GitHub Actions or
   other CI providers.
 </NoteCallout>
 
 ## Snapshot a sandbox to build a custom image
 
 Create a job that runs on a standard Depot sandbox and installs the tools and dependencies you want to bake in. This is a separate workflow that only creates your custom image and pushes it to the Depot Registry. You'll need to run this workflow initially to create the image and then only when dependencies change.
 
+<NoteCallout fullWidth>
+  Actions that set or change environment variables (such as actions/setup-node) need to be in both the build image
+  workflow and the workflows that use the custom image. See [Environment variable changes don't persist in custom
+  images](#environment-variable-changes-dont-persist-in-custom-images).
+</NoteCallout>
+
 To create the build image workflow:
 
 - Add [`depot/snapshot-action`](https://github.com/depot/snapshot-action) as a step (after your setup steps). It captures the full state of the sandbox environment and pushes it to the Depot registry as a reusable image.
@@ -77,6 +87,22 @@ Available values for `size`:
 | `8x32`   | 8    | 32 GB  |
 | `16x64`  | 16   | 64 GB  |
 | `32x128` | 32   | 128 GB |
+| `64x256` | 64   | 256 GB |
+
+## Environment variable changes don't persist in custom images
+
+For actions that set or change environment variables, you need to include the steps in both the image build workflow and the workflows that use the custom image.
+
+Snapshots capture only the sandbox filesystem. Environment variables exist only in the running process (not the filesystem) so they aren't included in the snapshot.
+
+For example, some actions (like `actions/setup-node`) download tools and configure `PATH` to find them. The downloaded tools persist in the snapshot, but the `PATH` changes don't. When a new job starts from the custom image, it's a fresh environment with default environment variables. The tools are present but can't be found without the `PATH` updates.
+
+To restore the environment variables, include the action in both workflows:
+
+- In the image build workflow, the action downloads the tool and bakes it into the filesystem.
+- In the workflow that uses the custom image, the action detects the tool is already on disk, skips the download, and only sets up the environment variables.
+
+Steps that install tools with `apt-get install` don't need to be in both workflows because they install to system paths that are already on `PATH` by default.
 
 ## Full example
 
@@ -128,3 +154,14 @@ jobs:
 ```
 
 Run `.depot/workflows/build-ci-image.yml` whenever dependencies change to keep the custom image up-to-date.
+
+## Best practices
+
+**Set `clean: false` when pre-cloning a repository**: If your custom image includes a pre-cloned copy of your repository, set `clean: false` on `actions/checkout` so it skips running `git clean -ffdx` before fetching. Without `clean: false`, checkout removes untracked files from the pre-cloned repo (like installed dependencies or build artifacts), negating the benefit of pre-cloning.
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+    with:
+      clean: false
+```

content/ci/how-to-guides/debug-with-ssh.mdx

@@ -4,9 +4,13 @@ ogTitle: How to debug a failing Depot CI job with SSH
 description: Learn how to SSH into a Depot CI job to interactively debug failures and inspect the job environment.
 ---
 
-To debug a failing step in Depot CI, you can connect to the sandbox running your job using SSH. There are two ways to do this depending on what you need:
+Debug a Depot CI job using SSH to inspect the sandbox running the job.
 
-- **tmate-based SSH**: Inject a pause at a specific step number and automatically connect. Use this when you want to inspect the exact environment state right before a failing step, with the full workflow environment (checked-out code, installed dependencies, environment variables) available.
+## How it works
+
+You can connect to the sandbox running your job using SSH. There are two ways to do this depending on what you need:
+
+- **tmate-based SSH**: Inject a pause at a specific step number and automatically connect with the [tmate](https://github.com/mxschmitt/action-tmate) action. Use this when you want to inspect the exact environment state right before a failing step, with the full workflow environment (checked-out code, installed dependencies, environment variables) available.
 - **Direct SSH**: Connect directly to the Depot sandbox running your job. Use this when you want a live shell without needing to stop at a specific step. Note that direct SSH connects to the sandbox itself and does not include the workflow environment. Steps like `actions/checkout` or dependency installation might not have run yet, or might land in a different working directory.
 
 ## Prerequisites

content/ci/how-to-guides/manage-secrets-and-variables.mdx

@@ -4,19 +4,20 @@ ogTitle: How to manage secrets and variables in Depot CI
 description: Learn how to add and remove secrets and environment variables for use in your Depot CI workflows.
 ---
 
-Secrets and variables in Depot CI are scoped to your Depot organization or to a single repository. Repository-scoped secrets override org-wide secrets with the same name.
+Secrets and variables in Depot CI are scoped to your Depot organization or to a single repository. Repository-scoped secrets override org-wide secrets with the same
+name.
 
-Organization owners can manage secrets and variables from the Depot CI [**Settings**](https://depot.dev/orgs/_/workflows/settings) in the Depot dashboard:
+Organization owners can manage secrets and variables from the Depot CI [**Settings**](https://depot.dev/orgs/_/workflows/settings) in the dashboard or from the CLI.
 
 - Add org-wide or repo-specific secrets and variables.
-- View all org-wide secrets and variables, or filter by repo.
+- View all org-wide or repo-specific secrets and variables.
 - Remove secrets and variables.
 
-You can't view secret values in the dashboard after you create them. Variable values are plain text and visible in the dashboard.
+You can't view secret values after you create them. Variable values are plain text and visible in the dashboard and CLI output.
 
-Names must be non-empty. Repository-scoped names can't contain a forward slash (`/`).
+Names must be non-empty and repository-scoped names can't contain a forward slash (`/`).
 
-### Import secrets and variables from GitHub
+## Import secrets and variables from GitHub
 
 If you're migrating from GitHub Actions, you can import your existing GitHub secrets and variables into Depot CI with a single command:
 
@@ -30,37 +31,39 @@ You can also manage secrets and variables with the Depot CLI. See the [examples]
 
 ## Add secrets to Depot CI using the dashboard
 
-1. From the [Depot CI workflows](/orgs/_/workflows) page, click **Settings**.
+1. From the [Depot CI workflows](/orgs/_/workflows) page, click the settings icon.
 2. In the **Secrets** section, under **Set secret**, use the **Applies to** dropdown to choose the scope.
 3. Enter a **Name** and **Value** for the secret. Optionally add a **Description**.
 4. Click **Set secret**.
 
 ## Remove secrets in Depot CI using the dashboard
 
-1. From the [Depot CI workflows](/orgs/_/workflows) page, click **Settings**.
+1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon.
 2. In the **Secrets** section, find the secret you want to remove and click its actions menu.
 3. Select **Remove secret** and click **Remove** to confirm.
 
 ## Add variables to Depot CI using the dashboard
 
-1. From the [Depot CI workflows](/orgs/_/workflows) page, click **Settings**.
+1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon.
 2. In the **Variables** section, under **Set variable**, use the **Applies to** dropdown to choose the scope.
 3. Enter a **Name** and **Value** for the variable. Optionally add a **Description**.
 4. Click **Set variable**.
 
 ## Remove variables in Depot CI using the dashboard
 
-1. From the [Depot CI workflows](/orgs/_/workflows) page, click **Settings**.
+1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon.
 2. In the **Variables** section, find the variable you want to remove and click its actions menu.
 3. Select **Remove variable** and click **Remove** to confirm.
 
 ## Update secrets and variables in Depot CI using the dashboard
 
-You can update the description of a secret or variable from the dashboard. To update a secret or variable value, set it again with the same name. The new value overwrites the old one.
+You can update only the description of a secret or variable from the dashboard.
+
+To update a secret or variable value, set it again with the same name. The new value overwrites the old one.
 
 To update a description:
 
-1. From the [Depot CI workflows](/orgs/_/workflows) page, click **Settings**.
+1. From the [Depot CI](/orgs/_/workflows) page, click the settings icon.
 2. Find the secret or variable and click its actions menu.
 3. Select **Edit description**.
 4. Update the description and click **Save**.