@trigger.dev/sdk 4.5.0-rc.5 → 4.5.0-rc.7

package/docs/deployment/overview.mdx

@@ -0,0 +1,257 @@
+---
+title: "Deployment"
+sidebarTitle: "Overview"
+description: "Learn how to deploy your tasks to Trigger.dev."
+---
+
+import CorepackError from "/snippets/corepack-error.mdx";
+
+Before you can run production workloads on Trigger.dev, you need to deploy your tasks. The only way to do this at the moment is through the [deploy CLI command](/cli-deploy):
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest deploy
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest deploy
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest deploy
+```
+
+</CodeGroup>
+
+## Deploying 101
+
+Let's assume you have an existing trigger.dev project with a few tasks that you have been running locally but now want to deploy to the Trigger.dev cloud (or your self-hosted instance).
+
+First, let's make sure you are logged in to the CLI (if you haven't already):
+
+```bash
+npx trigger.dev login
+```
+
+This will open a browser window where you can log in with your Trigger.dev account and link your CLI.
+
+Now you can deploy your tasks:
+
+```bash
+npx trigger.dev deploy
+```
+
+This should print out a success message and let you know a new version has been deployed:
+
+```bash
+Trigger.dev (3.3.16)
+------------------------------------------------------
+┌  Deploying project
+│
+◇  Retrieved your account details for eric@trigger.dev
+│
+◇  Successfully built code
+│
+◇  Successfully deployed version 20250228.1
+│
+└  Version 20250228.1 deployed with 4 detected tasks
+```
+
+Now if you visit your Trigger.dev dashboard you should see the new version deployed:
+
+![Trigger.dev dashboard showing the latest version deployed](/deployment/my-first-deployment.png)
+
+<Note>
+  Deploying consists of building your tasks and uploading them to the Trigger.dev cloud. This
+  process can take a few seconds to a few minutes depending on the size of your project.
+</Note>
+
+## Triggering deployed tasks
+
+Once you have deployed your tasks, you can trigger tasks exactly the same way you did locally, but with the "PROD" API key:
+
+![Trigger.dev dashboard showing the API key](/deployment/api-key.png)
+
+Copy the API key from the dashboard and set the `TRIGGER_SECRET_KEY` environment variable, and then any tasks you trigger will run against the deployed version:
+
+```txt .env
+TRIGGER_SECRET_KEY="tr_prod_abc123"
+```
+
+Now you can trigger your tasks:
+
+```ts
+import { myTask } from "./trigger/tasks";
+
+await myTask.trigger({ foo: "bar" });
+```
+
+See our [triggering tasks](/triggering) guide for more information.
+
+## Versions
+
+When you deploy your tasks, Trigger.dev creates a new version of all tasks in your project. A version is a snapshot of your tasks at a certain point in time. This ensures that tasks are not affected by changes to the code.
+
+### Current version
+
+When you deploy, the version number is automatically incremented, and the new version is set as the current version for that environment.
+
+<Note>
+  A single environment (prod, staging, etc.) can only have a single "current" version at a time.
+</Note>
+
+The current version defines which version of the code new task runs will execute against. When a task run starts, it is locked to the current version. This ensures that the task run is not affected by changes to the code. Retries of the task run will also be locked to the original version.
+
+<Note>
+  When you Replay a run in the dashboard we will create a new run, locked to the current version and
+  not necessarily the version of the original run.
+</Note>
+
+### Version locking
+
+You can optionally specify the version when triggering a task using the `version` parameter. This is useful when you want to run a task against a specific version of the code:
+
+```ts
+await myTask.trigger({ foo: "bar" }, { version: "20250228.1" });
+```
+
+If you want to set a global version to run all tasks against, you can use the `TRIGGER_VERSION` environment variable:
+
+```bash
+TRIGGER_VERSION=20250228.1
+```
+
+### Child tasks and auto-version locking
+
+Trigger and wait functions version lock child task runs to the parent task run version. This ensures the results from child runs match what the parent task is expecting. If you don't wait then version locking doesn't apply.
+
+| Trigger function        | Parent task version | Child task version | isLocked |
+| ----------------------- | ------------------- | ------------------ | -------- |
+| `trigger()`             | `20240313.2`        | Current            | No       |
+| `batchTrigger()`        | `20240313.2`        | Current            | No       |
+| `triggerAndWait()`      | `20240313.2`        | `20240313.2`       | Yes      |
+| `batchTriggerAndWait()` | `20240313.2`        | `20240313.2`       | Yes      |
+
+### Skipping promotion
+
+When you deploy, the new version is automatically promoted be the current version. If you want to skip this promotion, you can use the `--skip-promotion` flag:
+
+```bash
+npx trigger.dev deploy --skip-promotion
+```
+
+This will create a new deployment version but not promote it to the current version:
+
+![Trigger.dev dashboard showing the latest version deployed but not promoted](/deployment/skip-promotion.png)
+
+This allows you to deploy and test a new version without affecting new task runs. When you want to promote the version, you can do so from the CLI:
+
+```bash
+npx trigger.dev promote 20250228.1
+```
+
+Or from the dashboard:
+
+![Trigger.dev dashboard showing the promote button](/deployment/promote-button.png)
+
+To learn more about skipping promotion and how this enables atomic deployments, see our [Atomic deployment](/deployment/atomic-deployment) guide.
+
+## Staging deploys
+
+By default, the `deploy` command will deploy to the `prod` environment. If you want to deploy to a different environment, you can use the `--env` flag:
+
+```bash
+npx trigger.dev deploy --env staging
+```
+
+<Note>
+  If you are using the Trigger.dev Cloud, staging deploys are only available on the Hobby and Pro
+  plans.
+</Note>
+
+This will create an entirely new version of your tasks for the `staging` environment, with a new version number and an independent current version:
+
+![Trigger.dev dashboard showing the staging environment](/deployment/staging-deploy.png)
+
+Now you can trigger tasks against the staging environment by setting the `TRIGGER_SECRET_KEY` environment variable to the staging API key:
+
+```txt .env
+TRIGGER_SECRET_KEY="tr_stg_abcd123"
+```
+
+For additional environments beyond `prod` and `staging`, you can use [preview branches](/deployment/preview-branches), which allow you to create isolated environments for each branch of your code.
+
+## Local builds
+
+By default we use a remote build provider to speed up builds. However, you can also force the build to happen locally on your machine using the `--force-local-build` flag:
+
+```bash
+npx trigger.dev deploy --force-local-build
+```
+
+<Tip>
+  Deploying with local builds can be a useful fallback in cases where our remote build provider is experiencing availability issues.
+</Tip>
+
+### System requirements
+
+To use local builds, you need the following tools installed on your machine:
+
+- Docker ([installation guide](https://docs.docker.com/get-started/get-docker))
+- Docker Buildx ([installation guide](https://github.com/docker/buildx#installing))
+
+## Environment variables
+
+To add custom environment variables to your deployed tasks, you need to add them to your project in the Trigger.dev dashboard, or automatically sync them using our [syncEnvVars](/config/config-file#syncenvvars) or [syncVercelEnvVars](/config/config-file#syncvercelenvvars) build extensions.
+
+For more information on environment variables, see our [environment variables](/deploy-environment-variables) guide.
+
+## Troubleshooting
+
+When things go wrong with your deployment, there are a few things you can do to diagnose the issue:
+
+### Dry runs
+
+You can do a "dry run" of the deployment to see what is built and uploaded without actually deploying:
+
+```bash
+npx trigger.dev deploy --dry-run
+
+#  Dry run complete. View the built project at /<project path>/.trigger/tmp/<build dir>
+```
+
+The dry run will output the build directory where you can inspect the built tasks and dependencies. You can also compress this directory and send it to us if you need help debugging.
+
+### Debug logs
+
+You can run the deploy command with `--log-level debug` at the end. This will print out a lot of information about the deploy. If you can't figure out the problem from the information below please join [our Discord](https://trigger.dev/discord) and create a help forum post. Do NOT share the extended debug logs publicly as they might reveal private information about your project.
+
+### Common issues
+
+#### `Failed to build project image: Error building image`
+
+There should be a link below the error message to the full build logs on your machine. Take a look at these to see what went wrong. Join [our Discord](https://trigger.dev/discord) and you share it privately with us if you can't figure out what's going wrong. Do NOT share these publicly as the verbose logs might reveal private information about your project.
+
+Sometimes these errors are caused by upstream availability issues with our remote build provider. In this case, you can try deploying with a local build using the `--force-local-build` flag. Refer to the [Local builds](#local-builds) section for more information.
+
+#### `Deployment encountered an error`
+
+Usually there will be some useful guidance below this message. If you can't figure out what's going wrong then join [our Discord](https://trigger.dev/discord) and create a Help forum post with a link to your deployment.
+
+#### `No loader is configured for ".node" files`
+
+This happens because `.node` files are native code and can't be bundled like other packages. To fix this, add your package to [`build.external`](/config/config-file#external) in the `trigger.config.ts` file like this:
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    external: ["your-node-package"],
+  },
+});
+```
+<CorepackError />

package/docs/deployment/preview-branches.mdx

@@ -0,0 +1,224 @@
+---
+title: "Preview branches"
+description: "Create isolated environments for each branch of your code, allowing you to test changes before merging to production. You can create preview branches manually or automatically from your git branches."
+---
+
+## How to use preview branches
+
+The preview environment is special – you create branches from it. The branches you create live under the preview environment and have all the features you're used to from other environments (like staging or production). That means you can trigger runs, have schedules, test them, use Realtime, etc.
+
+![Preview environment and branches](/deployment/preview-environment-branches.png)
+
+We recommend you automatically create a preview branch for each git branch when a Pull Request is opened and then archive it automatically when the PR is merged/closed.
+
+The process to use preview branches looks like this:
+
+1. Create a preview branch
+2. Deploy to the preview branch (1+ times)
+3. Trigger runs using your Preview API key (`TRIGGER_SECRET_KEY`) and the branch name (`TRIGGER_PREVIEW_BRANCH`).
+4. Archive the preview branch when the branch is done.
+
+There are two main ways to do this:
+
+1. Automatically: using GitHub Actions (recommended).
+2. Manually: in the dashboard and/or using the CLI.
+
+### Limits on active preview branches
+
+We restrict the number of active preview branches (per project). You can archive a preview branch at any time (automatically or manually) to unlock another slot – or you can upgrade your plan.
+
+Once archived you can still view the dashboard for the branch but you can't trigger or execute runs (or other write operations).
+
+This limit exists because each branch has an independent concurrency limit. For the Cloud product these are the limits:
+
+| Plan  | Active preview branches |
+| ----- | ----------------------- |
+| Free  | 0                       |
+| Hobby | 5                       |
+| Pro   | 20 (then paid for more) |
+
+For full details see our [pricing page](https://trigger.dev/pricing).
+
+## Triggering runs and using the SDK
+
+Before we talk about how to deploy to preview branches, one important thing to understand is that you must set the `TRIGGER_PREVIEW_BRANCH` environment variable as well as the `TRIGGER_SECRET_KEY` environment variable.
+
+When deploying to somewhere that supports `process.env` (like Node.js runtimes) you can just set the environment variables:
+
+```bash
+TRIGGER_SECRET_KEY="tr_preview_1234567890"
+TRIGGER_PREVIEW_BRANCH="your-branch-name"
+```
+
+If you're deploying somewhere that doesn't support `process.env` (like some edge runtimes) you can manually configure the SDK:
+
+```ts
+import { configure } from "@trigger.dev/sdk";
+import { myTask } from "./trigger/myTasks";
+
+configure({
+  secretKey: "tr_preview_1234567890", // WARNING: Never actually hardcode your secret key like this
+  previewBranch: "your-branch-name",
+});
+
+async function triggerTask() {
+  await myTask.trigger({ userId: "1234" }); // Trigger a run in your-branch-name
+}
+```
+
+### Triggering across multiple branches from one process
+
+If a single process needs to trigger runs in several preview branches (or a mix of prod and preview), use `new TriggerClient({...})` for each target instead of mutating global config. Each instance owns its own auth and branch.
+
+```ts
+import { TriggerClient } from "@trigger.dev/sdk";
+
+const signupFlow = new TriggerClient({
+  accessToken: process.env.TRIGGER_PREVIEW_KEY,
+  previewBranch: "signup-flow",
+});
+const checkout = new TriggerClient({
+  accessToken: process.env.TRIGGER_PREVIEW_KEY,
+  previewBranch: "checkout-redesign",
+});
+
+const payload = { to: "user@example.com" };
+await Promise.all([
+  signupFlow.tasks.trigger("send-email", payload),
+  checkout.tasks.trigger("send-email", payload),
+]);
+```
+
+See [Multiple SDK clients](/management/multiple-clients) for the full pattern.
+
+## Preview branches with GitHub Actions (recommended)
+
+This GitHub Action will:
+
+1. Automatically create a preview branch for your Pull Request (if the branch doesn't already exist).
+2. Deploy the preview branch.
+3. Archive the preview branch when the Pull Request is merged/closed. This only works if your workflow runs on **closed** PRs (`types: [opened, synchronize, reopened, closed]`). If you omit `closed`, branches won't be archived automatically.
+
+```yml .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 }}
+```
+
+For this workflow to work, you need to set the following secrets in your GitHub repository:
+
+- `TRIGGER_ACCESS_TOKEN`: A Trigger.dev personal access token (they start with `tr_pat_`). [Learn how to create one and set it in GitHub](/github-actions#creating-a-personal-access-token).
+
+Notice that the deploy command has `--env preview` at the end. We automatically detect the preview branch from the GitHub actions env var.
+
+You can manually specify the branch using `--branch <branch-name>` in the deploy command, but this isn't required.
+
+## Preview branches with the CLI (manual)
+
+### Deploying a preview branch
+
+Creating and deploying a preview branch manually is easy:
+
+```bash
+npx trigger.dev@latest deploy --env preview
+```
+
+This will create and deploy a preview branch, automatically detecting the git branch. If for some reason the auto-detection doesn't work it will let you know and tell you do this:
+
+```bash
+npx trigger.dev@latest deploy --env preview --branch your-branch-name
+```
+
+### Archiving a preview branch
+
+You can manually archive a preview branch with the CLI:
+
+```bash
+npx trigger.dev@latest preview archive
+```
+
+Again we will try auto-detect the current branch. But you can specify the branch name with `--branch <branch-name>`.
+
+## Creating and archiving preview branches from the dashboard
+
+From the "Preview branches" page you can create a branch:
+
+![Preview branches page](/deployment/preview-branches.png)
+![Create preview branch](/deployment/preview-branches-new.png)
+
+You can also archive a branch:
+
+![Archive preview branch](/deployment/preview-branches-archive.png)
+
+## Environment variables
+
+You can set environment variables for "Preview" and they will get applied to all branches (existing and new). You can also set environment variables for a specific branch. If they are set for both then the branch-specific variables will take precedence.
+
+![Environment variables](/deployment/preview-environment-variables.png)
+
+These can be set manually in the dashboard, or automatically at deploy time using the [syncEnvVars()](/config/extensions/syncEnvVars) or [syncVercelEnvVars()](/config/extensions/syncEnvVars#syncvercelenvvars) build extensions.
+
+### Sync environment variables
+
+Full instructions are in the [syncEnvVars()](/config/extensions/syncEnvVars) documentation.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+// You will need to install the @trigger.dev/build package
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  //... other config
+  build: {
+    // This will automatically detect and sync environment variables
+    extensions: [
+      syncEnvVars(async (ctx) => {
+        // You can fetch env variables from a 3rd party service like Infisical, Hashicorp Vault, etc.
+        // The ctx.branch will be set if it's a preview deployment.
+        return await fetchEnvVars(ctx.environment, ctx.branch);
+      }),
+    ],
+  },
+});
+```
+
+### Sync Vercel environment variables
+
+You need to set the `VERCEL_ACCESS_TOKEN`, `VERCEL_PROJECT_ID` and `VERCEL_TEAM_ID` environment variables. You can find these in the Vercel dashboard. Full instructions are in the [syncVercelEnvVars()](/config/extensions/syncEnvVars#syncvercelenvvars) documentation.
+
+The extension will automatically detect a preview branch deploy from Vercel and sync the appropriate environment variables.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+// You will need to install the @trigger.dev/build package
+import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  //... other config
+  build: {
+    // This will automatically detect and sync environment variables
+    extensions: [syncVercelEnvVars()],
+  },
+});
+```