Skip to content

Commit bbd82ad

Browse files
ericallamericallam
authored
docs: improve deployment docs and add atomic deploy guide (#1748)
* docs: improve deployment docs and add atomic deploy guide * Various docs fixes
1 parent edf0c10 commit bbd82ad

14 files changed

+514
-30
lines changed

‎docs/cli-deploy-commands.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: "CLI deploy options"
2+
title: "CLI deploy command"
33
sidebarTitle: "deploy"
4-
description: "Use these options to help deploy your tasks to Trigger.dev."
4+
description: "Use the deploy command to deploy your tasks to Trigger.dev."
55
---
66

7-
import CliDeployCommands from '/snippets/cli-commands-deploy.mdx';
7+
import CliDeployCommands from "/snippets/cli-commands-deploy.mdx";
88

9-
<CliDeployCommands/>
9+
<CliDeployCommands />

‎docs/cli-promote-commands.mdx

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: "CLI promote command"
3+
sidebarTitle: "promote"
4+
description: "Use the promote command to promote a previously deployed version to the current version."
5+
---
6+
7+
import CliPromoteCommands from "/snippets/cli-commands-promote.mdx";
8+
9+
<CliPromoteCommands />

‎docs/deployment/api-key.png

320 KB
Loading

‎docs/deployment/atomic-deployment.mdx

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: "Atomic deploys"
3+
sidebarTitle: "Atomic deploys"
4+
description: "Use atomic deploys to coordinate changes to your tasks and your application."
5+
---
6+
7+
Atomic deploys in Trigger.dev allow you to synchronize the deployment of your application with a specific version of your tasks. This ensures that your application always uses the correct version of its associated tasks, preventing inconsistencies or errors due to version mismatches.
8+
9+
## How it works
10+
11+
Atomic deploys achieve synchronization by deploying your tasks to Trigger.dev without promoting them to the default version. Instead, you explicitly specify the deployed task version in your application’s environment. Here’s the process at a glance:
12+
13+
1. **Deploy Tasks to Trigger.dev**: Use the Trigger.dev CLI to deploy your tasks with the `--skip-promotion` flag. This creates a new task version without making it the default.
14+
2. **Capture the Deployment Version**: The CLI outputs the version of the deployed tasks, which you’ll use in the next step.
15+
3. **Deploy Your Application**: Deploy your application (e.g., to Vercel), setting an environment variable like `TRIGGER_VERSION` to the captured task version.
16+
17+
## Vercel CLI & GitHub Actions
18+
19+
If you deploy to Vercel via their CLI, you can use this sample workflow that demonstrates performing atomic deploys with GitHub Actions, Trigger.dev, and Vercel:
20+
21+
```yml
22+
name: Deploy to Trigger.dev (prod)
23+
on:
24+
push:
25+
branches:
26+
- main
27+
concurrency:
28+
group: ${{ github.workflow }}
29+
cancel-in-progress: true
30+
jobs:
31+
deploy:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- uses: actions/checkout@v4
35+
36+
- name: Use Node.js 20.x
37+
uses: actions/setup-node@v4
38+
with:
39+
node-version: "20.x"
40+
41+
- name: Install dependencies
42+
run: npm install
43+
44+
- name: Deploy Trigger.dev
45+
id: deploy-trigger
46+
env:
47+
TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
48+
run: |
49+
npx trigger.dev@latest deploy --skip-promotion
50+
51+
- name: Deploy to Vercel
52+
run: npx vercel --yes --prod -e TRIGGER_VERSION=$TRIGGER_VERSION --token $VERCEL_TOKEN
53+
env:
54+
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
55+
TRIGGER_VERSION: ${{ steps.deploy-trigger.outputs.deploymentVersion }}
56+
57+
- name: Promote Trigger.dev Version
58+
if: false
59+
run: npx trigger.dev@latest promote $TRIGGER_VERSION
60+
env:
61+
TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
62+
TRIGGER_VERSION: ${{ steps.deploy-trigger.outputs.deploymentVersion }}
63+
```
64+
65+
- Deploy to Trigger.dev
66+
67+
- The `npx trigger.dev deploy` command uses `--skip-promotion` to deploy the tasks without setting the version as the default.
68+
- The step’s id: `deploy-trigger` allows us to capture the deployment version in the output (deploymentVersion).
69+
70+
- Deploy to Vercel:
71+
- The `npx vercel` command deploys the application, setting the `TRIGGER_VERSION` environment variable to the task version from the previous step.
72+
- The --prod flag ensures a production deployment, and -e passes the environment variable.
73+
- The `@trigger.dev/sdk` automatically uses the `TRIGGER_VERSION` environment variable to trigger the correct version of the tasks.
74+
75+
For this workflow to work, you need to set up the following secrets in your GitHub repository:
76+
77+
- `TRIGGER_ACCESS_TOKEN`: Your Trigger.dev personal access token. View the instructions [here](/github-actions) to learn more.
78+
- `VERCEL_TOKEN`: Your Vercel personal access token. You can find this in your Vercel account settings.
79+
80+
## Vercel GitHub integration
81+
82+
If you're are using Vercel, chances are you are using their GitHub integration and deploying your application directly from pushes to GitHub. This section covers how to achieve atomic deploys with Trigger.dev in this setup.
83+
84+
### Turn off automatic promotion
85+
86+
By default, Vercel automatically promotes new deployments to production. To prevent this, you need to disable the auto-promotion feature in your Vercel project settings:
87+
88+
1. Go to your Production environment settings in Vercel at `https://vercel.com/<team-slug>/<project-slug>/settings/environments/production`
89+
2. Disable the "Auto-assign Custom Production Domains" setting:
90+
91+
![Vercel project settings showing the auto-promotion setting](/deployment/auto-assign-production-domains.png)
92+
93+
3. Hit the "Save" button to apply the changes.
94+
95+
Now whenever you push to your main branch, Vercel will deploy your application to the production environment without promoting it, and you can control the promotion manually.
96+
97+
### Deploy with Trigger.dev
98+
99+
Now we want to deploy that same commit to Trigger.dev, and then promote the Vercel deployment when that completes. Here's a sample GitHub Actions workflow that does this:
100+
101+
```yml
102+
name: Deploy to Trigger.dev (prod)
103+
104+
on:
105+
push:
106+
branches:
107+
- main
108+
109+
concurrency:
110+
group: ${{ github.workflow }}
111+
cancel-in-progress: true
112+
113+
jobs:
114+
deploy:
115+
runs-on: ubuntu-latest
116+
117+
steps:
118+
- uses: actions/checkout@v4
119+
120+
- name: Use Node.js 20.x
121+
uses: actions/setup-node@v4
122+
with:
123+
node-version: "20.x"
124+
125+
- name: Install dependencies
126+
run: npm install
127+
128+
- name: Wait for vercel deployment (push)
129+
id: wait-for-vercel
130+
uses: ericallam/vercel-wait@main
131+
with:
132+
project-id: ${{ secrets.VERCEL_PROJECT_ID }}
133+
token: ${{ secrets.VERCEL_TOKEN }}
134+
sha: ${{ github.sha }}
135+
136+
- name: 🚀 Deploy Trigger.dev
137+
id: deploy-trigger
138+
env:
139+
TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
140+
run: |
141+
npx trigger.dev@latest deploy
142+
143+
- name: Promote Vercel deploy
144+
run: npx vercel promote $VERCEL_DEPLOYMENT_ID --yes --token $VERCEL_TOKEN --scope $VERCEL_SCOPE_NAME
145+
env:
146+
VERCEL_DEPLOYMENT_ID: ${{ steps.wait-for-vercel.outputs.deployment-id }}
147+
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
148+
VERCEL_SCOPE_NAME: "<your team slug>"
149+
```
150+
151+
This workflow does the following:
152+
153+
1. Waits for the Vercel deployment to complete using the `ericallam/vercel-wait` action.
154+
2. Deploys the tasks to Trigger.dev using the `npx trigger.dev deploy` command. There's no need to use the `--skip-promotion` flag because we want to promote the deployment.
155+
3. Promotes the Vercel deployment using the `npx vercel promote` command.
156+
157+
For this workflow to work, you need to set up the following secrets in your GitHub repository:
158+
159+
- `TRIGGER_ACCESS_TOKEN`: Your Trigger.dev personal access token. View the instructions [here](/github-actions) to learn more.
160+
- `VERCEL_TOKEN`: Your Vercel personal access token. You can find this in your Vercel account settings.
161+
- `VERCEL_PROJECT_ID`: Your Vercel project ID. You can find this in your Vercel project settings.
162+
- `VERCEL_SCOPE_NAME`: Your Vercel team slug.
163+
164+
Checkout our [example repo](https://github.com/ericallam/vercel-atomic-deploys) to see this workflow in action.
165+
166+
<Note>
167+
We are using the `ericallam/vercel-wait` action above as a fork of the [official
168+
tj-actions/vercel-wait](https://github.com/tj-actions/vercel-wait) action because there is a bug
169+
in the official action that exits early if the deployment isn't found in the first check. I've
170+
opened a PR for this issue [here](https://github.com/tj-actions/vercel-wait/pull/106).
171+
</Note>

‎docs/deployment/auto-assign-production-domains.png

353 KB
Loading

‎docs/deployment/my-first-deployment.png

449 KB
Loading

0 commit comments

Comments
 (0)