Depot CI Beta setup and compatibility

Depot CI is currently in beta. We are inviting a limited number of users to participate in the beta. If you're interested in participating, please join the waitlist.

Why are we building Depot CI?

We are building Depot CI to provide a faster, more reliable, and more feature-rich CI provider for this new world of software engineering we are all living in.

The architecture of Depot CI

The general architecture idea behind Depot CI consists of three parts:

• The compute subsystem is responsible for executing the work that needs to be done. It receives the tasks to execute from the orchestrator, provisions the compute resources needed, and executes the work.

• The orchestrator subsystem schedules multi-step workflows across the fleet of compute, handles dependencies between tasks, and monitors progress.

• The GitHub Actions workflow parser takes an Actions-format YAML file and translates it into workflows for the orchestrator to process. It handles compatibility with how a regular Actions runner would execute a workflow, things like behavior, environment variables, and so on.

While Depot CI currently executes Actions-format YAML, the entire system is programmable, which we intend to expose directly via an API. The plan is for Depot CI to support arbitrary frontends that can represent a CI workflow or pipeline, with direct API access to workflows, orchestration, and compute sandboxes.

Where we are starting

In this initial beta release, we are starting with a single frontend: GitHub Actions workflows. The goal here is to make it as easy as possible for you to get started with Depot CI while we test and iterate on the core functionality of the system.

Depot CI in this initial beta release is aimed to be a drop-in replacement for GitHub Actions that runs entirely within Depot. This means that you can use your existing GitHub Actions workflows and they will run within Depot CI.

Getting started

For the beta, we highly recommend that you run Depot CI alongside GitHub Actions.

Things are expected to break and we'll be iterating quickly. So please keep your GitHub Actions workflows running alongside Depot CI so that you don't end up blocked by a broken workflow.

Install the Depot Code Access app into your GitHub organization

If you've used Claude Code on Depot, you'll already have the Depot Code Access app installed in your GitHub organization.

1. Log in to your Depot dashboard.
2. Click Settings.
3. In the GitHub Code Access section, check for existing GitHub connections.
4. To connect another organization, click Connect to GitHub.
5. Follow the prompts to add the Depot Code Access app to your GitHub organization.

Migrate workflows and configure secrets

The depot ci migrate command automates getting started with Depot CI. It launches an interactive wizard that discovers your GitHub Actions workflows, analyzes them for Depot CI compatibility, copies your selected workflows to .depot/, and prompts you to configure any referenced secrets and variables.

Your original .github/ directory is left as-is, so your GitHub Actions workflows continue running in parallel while you test Depot CI.

Note: Your workflows will run simultaneously in GitHub and Depot. Be mindful of workflows that cause changes in external systems, for example that trigger a deploy or update an important artifact, because they will execute twice.

From the root of your repository, run:

depot ci migrate

For a full description of how the migrate command works, see the CLI reference.

You can use the Depot CLI to manage secrets and variables after you migrate.

Manage your workflows

View and manage your workflows from the Workflows page of your Depot dashboard.

You can also use the Depot CLI to:

• run a workflow or job
• check the status of a run
• fetch job logs.

Compatibility with GitHub Actions

We are keeping track of the GitHub Actions syntax, triggers, and configuration that we are compatible with. See the following compatibility tables.

Workflow-level configuration

Syntax and keys at the workflow level that are supported.

Triggers (on.*)

Triggers that can kick off a Depot CI workflow today.

Job-level configuration (jobs.<job_id>.*)

Job level syntax and keys that are supported.

Step-level configuration

Expressions

Expression contexts that are supported today.

Expression functions

Expression functions that are supported today.

Supported action types

Unsupported features and current limitations

This section describes features that are not supported today with Depot CI.

Reusable workflows from other repositories

We don't support reusing workflows from other repositories using the uses key. You can still use the uses key to reference actions from the Marketplace, for example uses: action/checkout@v1.

Pull request workflows triggered from forks

GitHub allows pull_request workflows to run when triggered from forked repositories. We don't support this today but plan to support it.

Pull requests target workflows triggered from forks

GitHub allows pull_request_target workflows to run when triggered from forked repositories. We don't support this today but plan to support it.

Snapshotting and custom images

We'll have our own implementation for snapshotting and using snapshots.

Events triggering workflows

We currently support a subset of events that trigger workflows: push, pull_request, pull_request_target, schedule, workflow_call, workflow_dispatch, workflow_run.

Non ubuntu labels

We currently support only the Depot runs-on labels. We treat any labels we can't decipher as depot-ubuntu-latest.

Concurrency groups

Not supported in the beta yet.

OIDC

Not supported in the beta yet. We're currently adding this functionality.

Permissions

Today we support and respect the following permissions: actions, checks, contents, metadata, pull_requests, statuses, workflows. Notably, id-token requires OIDC and isn't supported yet.

Hierarchical secrets and variables

Today, secrets and variables are not hierarchical. They are scoped only to your Depot organization, which means you can't set different values for the same secret across different repositories.

Depot CLI usage and reference

Migrate workflows with the Depot CLI

The depot ci migrate command automates migrating to Depot CI. To get started with Depot CI, see Get started.

depot ci migrate

The command does the following:

1. Discovers all workflow files in .github/workflows/.
2. Analyzes each workflow for compatibility with Depot CI.
3. Prompts you to select which workflows to migrate.
4. Creates a .depot/ directory and copies selected workflows (and any local actions from .github/actions/) there.
5. Detects secrets and variables referenced in the selected workflows and prompts you to enter their values.

migrate flags

Non-interactive mode

Use --yes to run the migration without any prompts. Combine it with --secret and --var flags to supply secret and variable values. For example:

depot ci migrate --yes \
  --secret NPM_TOKEN=npm_abc123 \
  --secret DATABASE_URL=postgres://... \
  --var SERVICE_NAME=api \
  --org my-org-id

If a workflow references a secret or variable that you haven't supplied via the --secret or --var flags, the migration completes with a warning. You can add missing secrets and variables later with the depot ci secrets add or depot ci vars add commands, or via the API.

Compatibility analysis

Before copying any files, the wizard analyzes each workflow for features that Depot CI doesn't yet support.

The wizard shows a summary of issues for each workflow:

• No issues: The workflow is fully compatible and safe to migrate.
• Warnings: Features are partially supported. The workflow will run but behavior may differ from GitHub Actions.
• Critical issues: Features are unsupported. The workflow is unlikely to run correctly in Depot CI today.

For a full list of compatible syntax, triggers, and configuration, see Compatibility with GitHub Actions.

What gets copied

The migration copies the following into your .depot/ directory:

Manage secrets with the Depot CLI

Use the depot ci secrets commands to add, list, and remove secrets for your Depot CI workflows from the command line, as an alternative to the API.

Add a secret

depot ci secrets add SECRET_NAME

If you omit --value, the CLI prompts you to enter the value securely (input is hidden).

List secrets

depot ci secrets list

Displays names and metadata (no values) for all secrets configured for your organization.

Remove a secret

depot ci secrets remove SECRET_NAME

Prompts for confirmation before deleting. Use --force to skip the prompt.

Manage variables with the Depot CLI

Variables are non-secret configuration values available in workflows as ${{ vars.VARIABLE_NAME }}. Unlike secrets, variable values can be read back through the API or CLI.

The depot ci vars commands mirror the secrets commands.

Add a variable

depot ci vars add VAR_NAME --value "some-value"

If you omit --value, the CLI prompts you to enter the value.

List variables

depot ci vars list

Remove a variable

depot ci vars remove VAR_NAME

Run a workflow with the Depot CLI

The depot ci run command submits a local workflow YAML file to the Depot CI API and starts a run. If you have uncommitted changes relative to the default branch, the CLI automatically detects them, uploads a patch to Depot Cache, and injects a step into each selected job to apply the patch after checkout. The run reflects your local working state without requiring a push.

Run a workflow

From the root of your repository, run:

depot ci run --workflow .depot/workflows/ci.yml

The command does the following:

1. Reads and parses the workflow YAML file.
2. Detects any uncommitted changes by comparing your working tree against the merge base with the default branch.
3. If changes exist, uploads a patch to Depot Cache and injects a patch-application step after actions/checkout in each selected job.
4. Submits the workflow to the Depot CI API and prints the resulting org ID and run ID.

run flags

Run specific jobs

Pass --job one or more times to run a subset of the jobs defined in the workflow:

depot ci run --workflow .depot/workflows/ci.yml --job build --job test

Jobs not listed are excluded from the submitted workflow. If a requested job name does not exist in the workflow, the command exits with an error listing the available jobs.

Debug with SSH

Use --ssh-after-step to insert a tmate debug session after a specific step in a single job. This lets you SSH into the runner at that point in the workflow to inspect state interactively.

depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3

--ssh-after-step requires exactly one --job to be specified.

Check CI run status with the Depot CLI

The depot ci status command looks up the status of a Depot CI run and displays its workflows, jobs, and individual job attempts in a hierarchical view.

Get run status

depot ci status <run-id>

Replace <run-id> with the run ID returned by depot ci run or visible in the Depot dashboard. The command prints:

• The organization and run ID with the overall run status.
• Each workflow in the run, with its status and workflow file path.
• Each job within a workflow, with its job ID, key, and status.
• Each attempt within a job, with its attempt ID, attempt number, and status.

Fetch CI job logs with the Depot CLI

The depot ci logs command fetches and prints the log output for a specific CI job attempt.

Get job attempt logs

depot ci logs <attempt-id>

Replace <attempt-id> with the attempt ID shown in the output of depot ci status. The command fetches all log lines for that attempt to stdout.

Get started with Depot CI without using the migrate command

If you aren't using the depot ci migrate command to get started with Depot CI, you can copy workflows and configure secrets manually.

Copy your workflows to a Depot folder

In your repository, create a new directory called .depot. Copy your workflows manually by duplicating your .github/workflows/ files into .depot/workflows/ and any .github/actions/ files into .depot/actions/.

Note: Your workflows will run simultaneously in GitHub and Depot. Be mindful of workflows that cause changes in external systems, for example that trigger a deploy or update an important artifact, because they will execute twice.

Configure secrets and variables with the API

If your workflows use secrets (like ${{ secrets.NPM_TOKEN }}), and you're not using depot ci migrate, then you'll need to configure secrets in Depot CI using the API or the depot ci secrets command.

You need an organization token (DEPOT_TOKEN) to authenticate.

To add a secret:

curl -X POST https://api.depot.dev/depot.ci.v1.SecretService/AddSecret \
  -H "Authorization: Bearer ${DEPOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NPM_TOKEN",
    "value": "npm_abc123..."
  }'

To add multiple secrets:

curl -X POST https://api.depot.dev/depot.ci.v1.SecretService/BatchAddSecrets \
  -H "Authorization: Bearer ${DEPOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": [
      {"name": "NPM_TOKEN", "value": "npm_abc123..."},
      {"name": "DATABASE_PASSWORD", "value": "super-secret"}
    ]
  }'

Your workflows can access secrets, but you can't read them via the API.

To add variables, for non-secret configuration, use the VariableService API (similar to SecretService) or the depot ci vars command. Variables are available via ${{ vars.VARIABLE_NAME }} and can be read back through the API or CLI, unlike secrets.