Can I run GitHub Actions workflows locally before pushing?

Yes. Depot CI can run a GitHub Actions workflow against your local working tree before you commit or push anything.

From the root of your repository, run:

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

Depot CI detects the changes in your working tree, uploads them as a patch, and runs the workflow in a fresh Depot sandbox. The workflow uses the same GitHub Actions syntax, actions, job dependencies, and steps that it will use in CI.

This removes the usual edit, commit, push, wait cycle. Change the code, run the workflow, read the failure, fix it, and run it again. Push when it's green.

Run the workflow before pushing

Migrated Depot CI workflows live in .depot/workflows/. If the repository only has workflows under .github/workflows/, start by migrating them:

depot ci migrate

The command finds the existing GitHub Actions workflows, lets you choose which ones to migrate, and copies them into .depot/workflows/ with compatibility fixes where needed. The workflow structure and GitHub Actions syntax stay the same.

Then run a workflow against the current checkout:

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

You don't need a remote commit for the changes you're testing. You don't need to open a pull request. Each run gets a fresh copy of the current local patch.

How the local patch reaches CI

For a branch that already exists on the remote, Depot creates a patch containing the changes that haven't been pushed. For a local-only branch, Depot creates the patch relative to the repository's default branch.

When a selected job uses actions/checkout, Depot injects a step immediately after checkout to apply the patch. The rest of the job sees the local version of the code.

There's one important edge case: untracked files aren't included. Stage a new file before running the workflow so Git can include it in the patch:

git add path/to/new-file
depot ci run --workflow .depot/workflows/ci.yml

Staging the file doesn't require committing or pushing it.

Run only the job you're changing

Running the entire workflow after every edit is often a waste. Use --job to target the smallest useful part:

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

You can select more than one job by repeating the flag:

depot ci run \
  --workflow .depot/workflows/ci.yml \
  --job lint \
  --job test

Depot resolves the dependencies required by the selected jobs. This makes it practical to iterate on one failure without waiting for unrelated build, packaging, or deployment jobs.

Add --follow to stream the selected job's logs in the terminal:

depot ci run \
  --workflow .depot/workflows/ci.yml \
  --job test \
  --follow

Configure secrets separately

The local patch contains code, not the secret values from your shell or GitHub repository. Workflows that reference ${{ secrets.NAME }} need the corresponding secret configured in Depot CI.

When migrating existing workflows, import the referenced GitHub secrets and variables with:

depot ci migrate secrets-and-vars

You can also manage secrets and variables in the Depot dashboard or CLI. Secrets can be limited by repository, branch, workflow, or environment. Keep production credentials scoped away from local test runs, especially when the workflow can deploy or mutate external systems.

Don't put a secret in the workflow file, a temporary commit, or the local patch just to make a test pass.

Use act for a local Docker simulation

act is an open source tool that reads workflows from .github/workflows/ and runs their jobs inside Docker containers on your laptop. It's useful for checking workflow syntax, testing shell steps, and iterating on simple Linux jobs without pushing a commit.

Run the workflows triggered by a push event with:

act push

Or target one workflow and job:

act push --workflows .github/workflows/ci.yml --job test

The tradeoff is fidelity. act approximates GitHub Actions. It doesn't run the job on the machine image, hardware, or control plane that will execute it in CI. Its unsupported functionality includes incomplete GitHub context and gaps around concurrency, job permissions, OIDC, deployment environments, annotations, cancellation, and several other workflow features.

The result also depends on the developer's Docker engine, CPU architecture, memory, and network. An Apple silicon laptop can behave differently from an x64 runner. A container image can have different tools and system behavior from a complete runner VM.

Use act when a quick local approximation is enough. Use Depot CI when you need to validate the workflow on fresh, isolated CI compute with its job graph, service containers, matrices, artifacts, secrets, Arm runners, nested virtualization, and actual resource limits intact.

The Depot command is local. The execution environment is CI.

A tight debug loop

Use this loop while working on a change:

1. Run the smallest relevant job with depot ci run --workflow .depot/workflows/ci.yml --job <job> --follow.
2. Read the failed step and fix the code in the local working tree.
3. Run the same command again. Depot uploads a new patch for every attempt.
4. If the logs aren't enough, rerun with --ssh-after-step <n> and inspect the sandbox immediately before the failure.
5. Run the full workflow once the targeted job passes.
6. Commit and push the result.

For example, pause after the third step of the test job:

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

That gives you a shell with the checked-out code, installed dependencies, environment, and files created by the first three steps still in place. Fix the actual failure instead of adding debug commits and guessing from another wall of logs.

See Manage workflow runs for the complete local-run workflow and Use Depot CI in coding agent loops for running the same loop with an agent.