Depot CI compatibility with GitHub Actions | Depot CI | Depot Docs

Depot CI

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.*)

Scheduled workflows

Use on.schedule to run a workflow on a cron schedule. Add the workflow to .depot/workflows/ and merge it to your repository's default branch to activate the schedule. Scheduled workflows run from the default branch.

For example, save this workflow as .depot/workflows/daily.yml to run it daily at 02:00 UTC:

name: Daily task

on:
  schedule:
    - cron: '0 2 * * *'

jobs:
  daily:
    runs-on: depot-ubuntu-latest
    steps:
      - run: echo "Running the daily task"

Depot evaluates cron expressions in UTC and ignores the per-entry timezone setting.

Depot triggers scheduled workflows independently of GitHub's schedule event. We attempt to start scheduled workflows within one minute of their scheduled time, but we don't provide an official SLA for start times.

Workflow run events

Use workflow_run to start a listener workflow from another workflow's events. The on.workflow_run.workflows filter accepts the triggering workflow's YAML name, Depot filename, or repository path.

Read the triggering workflow's fields from github.event.workflow_run:

For .depot/workflows/ci.yml with name: Build and test, the payload has name: Build and test, path: .depot/workflows/ci.yml, and basepath: ci.yml. Without a name, name is .depot/workflows/ci.yml.

Use name to compare workflow names, path to compare repository paths, and basepath to compare filenames.

To also support older stored events, use this filename comparison:

if: ${{ (github.event.workflow_run.basepath || github.event.workflow_run.path || github.event.workflow_run.name) == 'ci.yml' }}

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.

Pull request review events

pull_request_review starts a workflow when someone submits, edits, or dismisses a review. pull_request_review_comment starts a workflow when someone creates, edits, or deletes a comment on a pull request's diff. For comments in the pull request's conversation, use issue_comment.

Filter by activity with types:

on:
  pull_request_review_comment:
    types: [created, edited]

Without types, the workflow runs for every activity: submitted, edited, and dismissed for reviews, and created, edited, and deleted for review comments.

A review event starts a run only when the listening workflow is on your repository's default branch. The run uses the pull request's merge ref. Read the review or comment from github.event, for example github.event.comment.body and github.event.pull_request.number. As in GitHub Actions, github.base_ref and github.head_ref are empty for these events. Runs for pull requests from forks get a read-only GITHUB_TOKEN and no secrets. Review and review comment runs triggered by Dependabot get the same treatment.

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

JavaScript actions that declare runs.using: node20, node16, or node12 run on Node.js 24, matching GitHub-hosted runners. Actions that declare runs.using: node24 are unchanged. To run those actions on Node.js 20 temporarily, set ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION to 'true' in the workflow, job, or step env. Depot will remove this opt-out to match GitHub and will announce the date in the changelog.

This example applies the opt-out to one job:

jobs:
  build:
    runs-on: depot-ubuntu-24.04
    env:
      ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: 'true'
    steps:
      - uses: actions/checkout@v4

This runtime is separate from the node on PATH that run: steps use.

GitHub checks

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

Reusable workflows from other repositories

You can call a reusable workflow from another repository using a job-level uses reference, such as owner/repo/.github/workflows/build.yml@v1. Depot CI supports nested calls, matrix jobs, inputs, and outputs.

Use a full 40-character commit SHA or a version tag such as v1, v1.2, or v1.2.3. Branch references such as main and abbreviated commit SHAs aren't supported. A version-looking reference must resolve to a tag, not a branch.

For private or internal source repositories, the caller must be a trusted private repository in the same GitHub organization. Grant the Depot Code Access GitHub App access to the source repository.

Depot resolves authored .github/workflows/ paths to files in .depot/workflows/ in the source repository. You can also reference .depot/workflows/ directly.

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.

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 workflow permission keys are supported: actions, checks, code-quality, contents, id-token, issues, packages, pull-requests, security-events, statuses.

Depot ignores unsupported permission keys when configuring GITHUB_TOKEN; they don't cause workflow validation to fail. Operations that require those permissions can fail at runtime. Use pull-requests, with a hyphen, to request pull request access.

To use issues: read or issues: write, your Depot Code Access GitHub App installation must have the corresponding Issues permission. If the installation hasn't granted the requested level, Depot can create the job token without issues; operations that require that permission won't work until you approve it in the GitHub App installation settings.

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.