We use cookies to understand how people use Depot.
Depot
Sign InGet started
Depot CI

Quickstart for Depot CI

Migrate your GitHub Actions workflows to run entirely on Depot compute with built-in job visibility, debuggability, and control.

During migration and testing, we recommend keeping your GitHub Actions workflows running alongside your Depot CI workflows.

Prerequisites

You'll need a Depot account.

Install the Depot CLI

Install the Depot CLI on your machine to work with Depot CI from your terminal or coding agent.

  • macOS

    brew install depot/tap/depot

  • Linux

    curl -L https://depot.dev/install-cli.sh | sh

  • All platforms

    Download the binary file for your platform from the Depot CLI releases page in GitHub.

Connect to GitHub

Depot CI uses the Depot Code Access app to read your repository and register workflow triggers. If you use Claude Code remote agent on Depot, you already have this installed.

  1. Go to Organization Settings in your Depot dashboard.
  2. In the GitHub Code Access section, click Connect to GitHub.
  3. Follow the prompts to install the Depot Code Access app into your GitHub organization.

Migrate your workflows

The depot ci migrate command automates migrating your GitHub Actions workflows to Depot CI.

From the root of your repository, run:

depot ci migrate

The command runs a preflight check, then copies and transforms your workflows:

  1. Validates authentication and checks that the Depot Code Access app is installed with the correct permissions.
  2. Discovers all workflow files in .github/workflows/.
  3. Prompts you to select which workflows to migrate.
  4. Copies selected workflows to .depot/workflows/ and any local actions to .depot/actions/, applies compatibility fixes, and adds inline comments for any changes.

After migration, the command reports any secrets and variables referenced by the migrated workflows. To import them, see Import secrets and variables below.

For a full description of flags and subcommands, see depot ci migrate in the Depot CLI reference.

Sandbox labels and sizes

The depot ci migrate command changes standard ubuntu-24.x or ubuntu-latest runner labels in your workflow to the equivalent Depot CI sandbox label and notes the change in the migrated file. Nonstandard labels become depot-ubuntu-latest and expressions are preserved as-is. For Depot CI sandbox sizes and labels, see Depot CI sandboxes.

Import secrets and variables

If your workflows reference GitHub secrets or variables, run depot ci migrate secrets-and-vars to import them into Depot CI:

depot ci migrate secrets-and-vars

This command creates a temporary GitHub Actions workflow that reads your existing GitHub secrets and variables and imports them into Depot CI. The workflow runs once and then you can delete it. The command prints a GitHub Actions run URL where you can monitor the workflow progress.

depot ci migrate secrets-and-vars is the fastest path if you have many secrets. You can also add secrets and variables manually using the CLI or dashboard. See Manage secrets and variables for details.

Merge the migrated workflows

Push and merge the changes so that automatic workflow triggers (like push and pull_request) are registered with Depot CI.

Important: After you merge, the workflows run in both GitHub and Depot CI. Any workflows that deploy, update artifacts, or cause any changes in external systems will execute twice.

  1. Commit the new .depot/ directory and push. For example:

    git add .depot/
git commit -m "Add Depot CI workflows"
git push

  2. Merge the changes into your default branch.

If your workflows include a push trigger on the default branch, merging starts your first run on Depot CI. Go to the Depot CI page in your Depot dashboard to see it.

Next steps

Check on your workflows

After merging, go to the Depot CI page in your Depot dashboard to confirm your workflows ran successfully. Compare the results against your GitHub Actions runs to make sure everything behaves as expected.

You can also check run status from the CLI:

depot ci run list
depot ci status <run-id>

Run a workflow locally

Use depot ci run to test a workflow against your local working tree without pushing to GitHub first:

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

If you have uncommitted changes, they're automatically included in the run.

Pass --job to run a subset of jobs:

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