triggerdotdev--trigger.dev/docs/github-actions.mdx

---
title: "CI / GitHub Actions"
description: "You can easily deploy your tasks with GitHub actions and other CI environments."
---

The instructions below are specific to GitHub Actions, but the same concepts can be used with other CI systems.

<Tip>
  Check out our new [GitHub integration](/github-integration) for automatic deployments, without adding any GitHub Actions workflows.
</Tip>

## GitHub Actions example

This simple GitHub action workflow will deploy your Trigger.dev tasks when new code is pushed to the `main` branch and the `trigger` directory has changes in it.

<Warning>
  The deploy step will fail if any version mismatches are detected. Please see the [version
  pinning](/github-actions#version-pinning) section for more details.
</Warning>

<CodeGroup>

```yaml .github/workflows/release-trigger-prod.yml
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
```

```yaml .github/workflows/release-trigger-staging.yml
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_ACCESS_TOKEN }}
        run: |
          npx trigger.dev@latest deploy --env staging
```

</CodeGroup>

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

## 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
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
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
```

<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](/deployment/preview-branches#preview-branches-with-github-actions-recommended) for more details.
</Note>

## Creating a Personal Access Token

<Steps>

<Step title="Create a new access token">
  Go to your profile page and click on the ["Personal Access
  Tokens"](https://cloud.trigger.dev/account/tokens) tab.
</Step>

<Step title="Go to your repository on GitHub.">
  Click on 'Settings' -> 'Secrets and variables' -> 'Actions' -> 'New repository secret'
</Step>

<Step title="Add the TRIGGER_ACCESS_TOKEN">
  Add the name `TRIGGER_ACCESS_TOKEN` and the value of your access token. ![Add TRIGGER_ACCESS_TOKEN
  in GitHub](/images/github-access-token.png)
</Step>

</Steps>

## 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
{
  "scripts": {
    "deploy:trigger-prod": "trigger deploy",
    "deploy:trigger": "trigger deploy --env staging"
  },
  "devDependencies": {
    "trigger.dev": "4.0.2"
  }
}
```

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

```yaml .github/workflows/release-trigger.yml
- 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`

<CodeGroup>

```yaml .github/workflows/release-trigger-self-hosted.yml
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
```

</CodeGroup>