> ## Documentation Index
> Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CI / GitHub Actions

> Deploy your tasks from CI using trusted deploys or an environment API key.

For GitHub Actions without stored credentials, use [Trusted publishing](https://trigger.dev/docs/deployment/trusted-publishing.md) with OIDC. The API-key instructions below also apply to other CI systems. Use an environment API key rather than a Personal Access Token so deployments are not tied to an individual team member's account or permissions. A Personal Access Token also [expires](https://trigger.dev/docs/management/authentication.md#pat-expiry) after the lifetime chosen when it was created, and a copied CLI login [expires after 7 days without use](https://trigger.dev/docs/cli-login-commands.md#login-expiry).

> [!TIP]
>
> Check out our new [GitHub integration](https://trigger.dev/docs/github-integration.md) for automatic deployments, without adding any GitHub Actions workflows.

## GitHub Actions example

This simple GitHub action workflow will deploy your Trigger.dev tasks when new code is pushed to the `main` branch.

> [!WARNING]
>
> The deploy step will fail if any version mismatches are detected. Please see the [version
> pinning](https://trigger.dev/docs/github-actions.md#cli-version-pinning) section for more details.

```yaml .github/workflows/release-trigger-prod.yml theme={"theme":"css-variables"}
name: Deploy to Trigger.dev (prod)

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js 20.x
        uses: actions/setup-node@v4
        with:
          node-version: "20.x"

      - name: Install dependencies
        run: npm install

      - name: 🚀 Deploy Trigger.dev
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
        run: |
          npx trigger.dev@latest deploy --env prod --external-id ${{ github.sha }}
```

```yaml .github/workflows/release-trigger-staging.yml theme={"theme":"css-variables"}
name: Deploy to Trigger.dev (staging)

# Requires manually calling the workflow from a branch / commit to deploy to staging
on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js 20.x
        uses: actions/setup-node@v4
        with:
          node-version: "20.x"

      - name: Install dependencies
        run: npm install

      - name: 🚀 Deploy Trigger.dev
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_STAGING_ACCESS_TOKEN }}
        run: |
          npx trigger.dev@latest deploy --env staging --external-id ${{ github.sha }}
```

If you already have a GitHub action file, you can just add the final step "🚀 Deploy Trigger.dev" to your existing file.

### Pinning runs to the deployment you just built

The `--external-id ${{ github.sha }}` above tags the deployment with the commit it was built from. That is the first half of [version skew protection](https://trigger.dev/docs/deployment/atomic-deployment.md): to complete it, give your running application the **same value** so it sends that id when it triggers.

```bash theme={"theme":"css-variables"}
# In your application's runtime environment, for the release built from this commit
TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
```

Every task triggered by that release is then pinned to the deployment built from the same commit — and runs triggered before the task build finishes wait for it rather than executing on the previous version.

> [!NOTE]
>
> Tagging the deployment is harmless on its own: if nothing sends a matching id, runs behave exactly
> as they do today. `--external-id` also makes repeat deploys idempotent — re-running the workflow
> for a commit that is already deployed reports the existing version instead of building again.
>
> Two things follow from that. Because no build runs, a re-run after changing a synced environment
> variable won't pick the new value up — make an empty commit, or pass `--force`. And if you add a
> `paths:` filter to this workflow, `${{ github.sha }}` stops being a safe id: commits that don't
> touch your tasks never produce a deployment carrying that SHA, so every run from those releases
> expires. See [when nothing ever
> lands](https://trigger.dev/docs/deployment/atomic-deployment.md#when-nothing-ever-lands).

## Preview branches

To deploy to preview branches from Pull Requests and have them archived when PRs are merged or closed, use a workflow that runs on `pull_request` with **all four types** including `closed`:

```yaml .github/workflows/trigger-preview-branches.yml theme={"theme":"css-variables"}
name: Deploy to Trigger.dev (preview branches)

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js 20.x
        uses: actions/setup-node@v4
        with:
          node-version: "20.x"

      - name: Install dependencies
        run: npm install

      - name: Deploy preview branch
        run: npx trigger.dev@latest deploy --env preview --external-id ${{ github.event.pull_request.head.sha }}
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_PREVIEW_ACCESS_TOKEN }}
```

On `pull_request`, `github.sha` is the merge commit GitHub creates for the PR, not the commit your
app was built from. Use `github.event.pull_request.head.sha` so the id matches the one your preview
deployment sends.

> [!NOTE]
>
> **Include `closed`** in the `pull_request.types` list. Without it, preview branches won't be archived when PRs are merged or closed, and you may hit the limit on active preview branches. See [Preview branches](https://trigger.dev/docs/deployment/preview-branches.md#preview-branches-with-github-actions-recommended) for more details.

## Create a deployment API key

Create a separate API key for each environment that your CI workflows deploy to. The key remains valid when team membership or permissions change.

**1. Open the API keys page**

Select the project and target environment, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).

**2. Create an API key**

Click **New API key**, give the key a name that identifies the workflow, and choose **Deploy
only** access.

**3. Copy the API key**

Create the key and copy its value. Trigger.dev shows the complete value only once.

**4. Add the TRIGGER\_ACCESS\_TOKEN secret to GitHub**

Open the repository's **Settings**, then select **Secrets and variables** → **Actions** → **New
repository secret**. Add the name `TRIGGER_ACCESS_TOKEN` and paste the API key as its value.

![Add TRIGGER\_ACCESS\_TOKEN in GitHub](https://mintcdn.com/trigger/uys6iMwf9B_ojh8r/images/github-access-token.png?fit=max\&auto=format\&n=uys6iMwf9B_ojh8r\&q=85\&s=6c516d32254c19937c0e7104753316a7)

The API key must belong to the environment targeted by the deploy command. If the repository deploys to multiple environments, store each environment's key in a separate GitHub secret and map the appropriate secret to `TRIGGER_ACCESS_TOKEN` in each workflow.

## CLI Version pinning

The CLI and `@trigger.dev/*` package versions need to be in sync with the `trigger.dev` CLI, otherwise there will be errors and unpredictable behavior. Hence, the `deploy` command will automatically fail during CI on any version mismatches.
Tip: add the `trigger.dev` CLI to your `devDependencies` and the deploy command to your `package.json` file to keep versions managed in the same place. For example:

```json theme={"theme":"css-variables"}
{
  "scripts": {
    "deploy:trigger-prod": "trigger deploy --env prod",
    "deploy:trigger": "trigger deploy --env staging"
  },
  "devDependencies": {
    "trigger.dev": "4.7.0"
  }
}
```

Your workflow file will follow the version specified in the `package.json` script, like so:

```yaml .github/workflows/release-trigger.yml theme={"theme":"css-variables"}
- name: 🚀 Deploy Trigger.dev
  env:
    TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
  run: |
    npm run deploy:trigger
```

You should use the version you run locally during dev and manual deploy. The current version is displayed in the banner, but you can also check it by appending `--version` to any command.

## Self-hosting

When self-hosting, you need to:

* Set up Docker Buildx in your CI environment for building images locally.
* Add your registry credentials to the GitHub secrets.
* Specify the `TRIGGER_API_URL` environment variable pointing to your webapp domain, for example: `https://trigger.example.com`

```yaml .github/workflows/release-trigger-self-hosted.yml theme={"theme":"css-variables"}
name: Deploy to Trigger.dev (self-hosted)

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js 20.x
        uses: actions/setup-node@v4
        with:
          node-version: "20.x"

      - name: Install dependencies
        run: npm install

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          version: latest

      - name: Login to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: 🚀 Deploy Trigger.dev
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
          TRIGGER_API_URL: ${{ secrets.TRIGGER_API_URL }}
        run: |
          npx trigger.dev@latest deploy --env prod
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.