Depot CI compatibility with GitHub Actions

Depot CI executes GitHub Actions YAML workflows. The following tables list GitHub Actions syntax, triggers, and configuration and whether they're supported in Depot CI.

Workflow-level configuration

Triggers (on.*)

Native GitHub stacked pull requests

Depot CI supports native GitHub stacked pull requests for pull_request workflows. Depot CI evaluates a stack's branches filter against its ultimate base branch, then runs the matching workflow for each pull request in the stack using that pull request's own merge ref.

For pull requests in a stack, github.event.pull_request.stack exposes the stack's number, size, position, base.ref, and base.sha. The value is null for a pull request that is not in a stack.

For ordinary pull requests without stack metadata, Depot CI continues to match pull_request.branches against the pull request's direct base branch.

Repository dispatch events

repository_dispatch lets you trigger Depot CI workflows from outside GitHub by sending a custom event to the GitHub API — useful for kicking off a run from another system (for example, a deployment provider) without polling or running your own relay.

Subscribe to every dispatch, or filter by event type with types:

on:
  repository_dispatch:
    types: [deploy-succeeded]

GitHub only delivers repository_dispatch events against your repository's default branch, so the workflow that runs is the one on the default branch. The custom event type and any client_payload you send are available through the github.event context (github.event.action and github.event.client_payload), matching GitHub Actions.

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

Step-level configuration

Expressions

Contexts

Functions

Action types

GitHub checks

Depot CI automatically reports GitHub checks for each job in a workflow run. For more information, see GitHub checks.

Limitations

GitHub-only event triggers

The following events are GitHub-specific concepts that aren't applicable to Depot CI workflows, such as Discussions, Pages, and issue events other than comments.

Reusable workflows from other repositories

The uses key for referencing workflows from other repositories is not supported. You can still use uses to reference actions from the GitHub Actions Marketplace (for example, uses: actions/checkout@v4).

Pull request workflows triggered from forks

GitHub allows pull_request and pull_request_target workflows to run when triggered from forked repositories. Support for this is planned.

Runner labels

Only Depot runs-on labels are supported. Nonstandard labels become depot-ubuntu-latest and expressions are preserved as-is. For Depot CI sandbox sizes and labels, see Depot CI sandboxes.

Permissions

The following permissions are supported: actions, checks, code-quality, contents, id-token, metadata, pull_requests, statuses, workflows.

The code-quality permission must be requested explicitly. It isn't included in read-all or write-all, which retain the existing permission set so older Depot Code Access GitHub App installations don't fail token creation before the new permission is approved.

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 and Using GitHub Packages with GitHub Apps).

For container images, you can use another registry instead, such as Depot Registry. When using depot/build-push-action, replace the GHCR login and push steps with the save input:

- 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 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 with write:packages scope, stored as a Depot CI secret.

Note that a PAT is a long-lived credential scoped to a user account, so consider the security implications of storing and rotating it.