@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/errors-retrying.mdx

@@ -0,0 +1,383 @@
+---
+title: "Errors & Retrying"
+description: "How to deal with errors and write reliable tasks."
+---
+
+import OpenaiRetry from "/snippets/code/openai-retry.mdx";
+
+When an uncaught error is thrown inside your task, that task attempt will fail.
+
+You can configure retrying in two ways:
+
+1. In your [trigger.config file](/config/config-file) you can set the default retrying behavior for all tasks.
+2. On each task you can set the retrying behavior.
+
+<Note>Task-level retry settings override the defaults in your `trigger.config` file.</Note>
+
+<Note>
+  By default when you create your project using the CLI init command, retrying is enabled in the DEV
+  environment. You can disable it by setting `enabledInDev: false` in your [trigger.config file](/config/config-file).
+</Note>
+
+## A simple example with OpenAI
+
+This task will retry 10 times with exponential backoff.
+
+- `openai.chat.completions.create()` can throw an error.
+- The result can be empty and we want to try again. So we manually throw an error.
+
+<OpenaiRetry />
+
+## Combining tasks
+
+One way to gain reliability is to break your work into smaller tasks and [trigger](/triggering) them from each other. Each task can have its own retrying behavior:
+
+```ts /trigger/multiple-tasks.ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  retry: {
+    maxAttempts: 10,
+  },
+  run: async (payload: string) => {
+    const result = await otherTask.triggerAndWait("some data");
+    //...do other stuff
+  },
+});
+
+export const otherTask = task({
+  id: "other-task",
+  retry: {
+    maxAttempts: 5,
+  },
+  run: async (payload: string) => {
+    return {
+      foo: "bar",
+    };
+  },
+});
+```
+
+Another benefit of this approach is that you can view the logs and retry each task independently from the dashboard.
+
+## Retrying smaller parts of a task
+
+Another complimentary strategy is to perform retrying inside of your task.
+
+We provide some useful functions that you can use to retry smaller parts of a task. Of course, you can also write your own logic or use other packages.
+
+### retry.onThrow()
+
+You can retry a block of code that can throw an error, with the same retry settings as a task.
+
+```ts /trigger/retry-on-throw.ts
+import { task, logger, retry } from "@trigger.dev/sdk";
+
+export const retryOnThrow = task({
+  id: "retry-on-throw",
+  run: async (payload: any) => {
+    //Will retry up to 3 times. If it fails 3 times it will throw.
+    const result = await retry.onThrow(
+      async ({ attempt }) => {
+        //throw on purpose the first 2 times, obviously this is a contrived example
+        if (attempt < 3) throw new Error("failed");
+        //...
+        return {
+          foo: "bar",
+        };
+      },
+      { maxAttempts: 3, randomize: false }
+    );
+
+    //this will log out after 3 attempts of retry.onThrow
+    logger.info("Result", { result });
+  },
+});
+```
+
+<Note>
+  If all of the attempts with `retry.onThrow` fail, an error will be thrown. You can catch this or
+  let it cause a retry of the entire task.
+</Note>
+
+### retry.fetch()
+
+You can use `fetch`, `axios`, or any other library in your code.
+
+But we do provide a convenient function to perform HTTP requests with conditional retrying based on the response:
+
+```ts /trigger/retry-fetch.ts
+import { task, logger, retry } from "@trigger.dev/sdk";
+
+export const taskWithFetchRetries = task({
+  id: "task-with-fetch-retries",
+  run: async (payload: any, { ctx }) => {
+    //if the Response is a 429 (too many requests), it will retry using the data from the response. A lot of good APIs send these headers.
+    const headersResponse = await retry.fetch("http://my.host/test-headers", {
+      retry: {
+        byStatus: {
+          "429": {
+            strategy: "headers",
+            limitHeader: "x-ratelimit-limit",
+            remainingHeader: "x-ratelimit-remaining",
+            resetHeader: "x-ratelimit-reset",
+            resetFormat: "unix_timestamp_in_ms",
+          },
+        },
+      },
+    });
+    const json = await headersResponse.json();
+    logger.info("Fetched headers response", { json });
+
+    //if the Response is a 500-599 (issue with the server you're calling), it will retry up to 10 times with exponential backoff
+    const backoffResponse = await retry.fetch("http://my.host/test-backoff", {
+      retry: {
+        byStatus: {
+          "500-599": {
+            strategy: "backoff",
+            maxAttempts: 10,
+            factor: 2,
+            minTimeoutInMs: 1_000,
+            maxTimeoutInMs: 30_000,
+            randomize: false,
+          },
+        },
+      },
+    });
+    const json2 = await backoffResponse.json();
+    logger.info("Fetched backoff response", { json2 });
+
+    //You can additionally specify a timeout. In this case if the response takes longer than 1 second, it will retry up to 5 times with exponential backoff
+    const timeoutResponse = await retry.fetch("https://httpbin.org/delay/2", {
+      timeoutInMs: 1000,
+      retry: {
+        timeout: {
+          maxAttempts: 5,
+          factor: 1.8,
+          minTimeoutInMs: 500,
+          maxTimeoutInMs: 30_000,
+          randomize: false,
+        },
+      },
+    });
+    const json3 = await timeoutResponse.json();
+    logger.info("Fetched timeout response", { json3 });
+
+    return {
+      result: "success",
+      payload,
+      json,
+      json2,
+      json3,
+    };
+  },
+});
+```
+
+<Note>
+  If all of the attempts with `retry.fetch` fail, an error will be thrown. You can catch this or let
+  it cause a retry of the entire task.
+</Note>
+
+## Advanced error handling and retrying
+
+We provide a `catchError` callback on the task, and you can register one globally with `tasks.catchError()`. This gets called when an uncaught error is thrown in your task.
+
+You can
+
+- Inspect the error, log it, and return a different error if you'd like.
+- Modify the retrying behavior based on the error, payload, context, etc.
+
+If you don't return anything from the function it will use the settings on the task (or inherited from the config). So you only need to use this to override things.
+
+### OpenAI error handling example
+
+OpenAI calls can fail for a lot of reasons and the ideal retry behavior is different for each.
+
+In this complicated example:
+
+- We skip retrying if there's no Response status.
+- We skip retrying if you've run out of credits.
+- If there are no Response headers we let the normal retrying logic handle it (return undefined).
+- If we've run out of requests or tokens we retry at the time specified in the headers.
+
+<CodeGroup>
+
+```ts tasks.ts
+import { task } from "@trigger.dev/sdk";
+import { calculateISO8601DurationOpenAIVariantResetAt, openai } from "./openai.js";
+
+export const openaiTask = task({
+  id: "openai-task",
+  retry: {
+    maxAttempts: 1,
+  },
+  run: async (payload: { prompt: string }) => {
+    const chatCompletion = await openai.chat.completions.create({
+      messages: [{ role: "user", content: payload.prompt }],
+      model: "gpt-3.5-turbo",
+    });
+
+    return chatCompletion.choices[0].message.content;
+  },
+  catchError: async ({ payload, error, ctx, retryAt }) => {
+    if (error instanceof OpenAI.APIError) {
+      if (!error.status) {
+        return {
+          skipRetrying: true,
+        };
+      }
+
+      if (error.status === 429 && error.type === "insufficient_quota") {
+        return {
+          skipRetrying: true,
+        };
+      }
+
+      if (!error.headers) {
+        //returning undefined means the normal retrying logic will be used
+        return;
+      }
+
+      const remainingRequests = error.headers["x-ratelimit-remaining-requests"];
+      const requestResets = error.headers["x-ratelimit-reset-requests"];
+
+      if (typeof remainingRequests === "string" && Number(remainingRequests) === 0) {
+        return {
+          retryAt: calculateISO8601DurationOpenAIVariantResetAt(requestResets),
+        };
+      }
+
+      const remainingTokens = error.headers["x-ratelimit-remaining-tokens"];
+      const tokensResets = error.headers["x-ratelimit-reset-tokens"];
+
+      if (typeof remainingTokens === "string" && Number(remainingTokens) === 0) {
+        return {
+          retryAt: calculateISO8601DurationOpenAIVariantResetAt(tokensResets),
+        };
+      }
+    }
+  },
+});
+```
+
+```ts openai.ts
+import { OpenAI } from "openai";
+
+export const openai = new OpenAI({ apiKey: env.OPENAI_API_KEY });
+
+export function calculateISO8601DurationOpenAIVariantResetAt(
+  resets: string,
+  now: Date = new Date()
+): Date | undefined {
+  // Check if the input is null or undefined
+  if (!resets) return undefined;
+
+  // Regular expression to match the duration string pattern
+  const pattern = /^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?(?:(\d+)ms)?$/;
+  const match = resets.match(pattern);
+
+  // If the string doesn't match the expected format, return undefined
+  if (!match) return undefined;
+
+  // Extract days, hours, minutes, seconds, and milliseconds from the string
+  const days = parseInt(match[1] ?? "0", 10) || 0;
+  const hours = parseInt(match[2] ?? "0", 10) || 0;
+  const minutes = parseInt(match[3] ?? "0", 10) || 0;
+  const seconds = parseFloat(match[4] ?? "0") || 0;
+  const milliseconds = parseInt(match[5] ?? "0", 10) || 0;
+
+  // Calculate the future date based on the current date plus the extracted time
+  const resetAt = new Date(now);
+  resetAt.setDate(resetAt.getDate() + days);
+  resetAt.setHours(resetAt.getHours() + hours);
+  resetAt.setMinutes(resetAt.getMinutes() + minutes);
+  resetAt.setSeconds(resetAt.getSeconds() + Math.floor(seconds));
+  resetAt.setMilliseconds(
+    resetAt.getMilliseconds() + (seconds - Math.floor(seconds)) * 1000 + milliseconds
+  );
+
+  return resetAt;
+}
+```
+
+</CodeGroup>
+
+## Preventing retries
+
+### Using `AbortTaskRunError`
+
+You can prevent retries by throwing an `AbortTaskRunError`. This will fail the task attempt and disable retrying.
+
+```ts /trigger/myTasks.ts
+import { task, AbortTaskRunError } from "@trigger.dev/sdk";
+
+export const openaiTask = task({
+  id: "openai-task",
+  run: async (payload: { prompt: string }) => {
+    //if this fails, it will throw an error and stop retrying
+    const chatCompletion = await openai.chat.completions.create({
+      messages: [{ role: "user", content: payload.prompt }],
+      model: "gpt-3.5-turbo",
+    });
+
+    if (chatCompletion.choices[0]?.message.content === undefined) {
+      // If OpenAI returns an empty response, abort retrying
+      throw new AbortTaskRunError("OpenAI call failed");
+    }
+
+    return chatCompletion.choices[0].message.content;
+  },
+});
+```
+
+### Using try/catch
+
+Sometimes you want to catch an error and don't want to retry the task. You can use try/catch as you normally would. In this example we fallback to using Replicate if OpenAI fails.
+
+```ts /trigger/myTasks.ts
+import { task } from "@trigger.dev/sdk";
+
+export const openaiTask = task({
+  id: "openai-task",
+  run: async (payload: { prompt: string }) => {
+    try {
+      //if this fails, it will throw an error and retry
+      const chatCompletion = await openai.chat.completions.create({
+        messages: [{ role: "user", content: payload.prompt }],
+        model: "gpt-3.5-turbo",
+      });
+
+      if (chatCompletion.choices[0]?.message.content === undefined) {
+        //sometimes OpenAI returns an empty response, let's retry by throwing an error
+        throw new Error("OpenAI call failed");
+      }
+
+      return chatCompletion.choices[0].message.content;
+    } catch (error) {
+      //use Replicate if OpenAI fails
+      const prediction = await replicate.run(
+        "meta/llama-2-70b-chat:02e509c789964a7ea8736978a43525956ef40397be9033abf9fd2badfe68c9e3",
+        {
+          input: {
+            prompt: payload.prompt,
+            max_new_tokens: 250,
+          },
+        }
+      );
+
+      if (prediction.output === undefined) {
+        //retry if Replicate fails
+        throw new Error("Replicate call failed");
+      }
+
+      return prediction.output;
+    }
+  },
+});
+```
+
+## Replay failed runs in bulk
+
+After you deploy a fix, use [bulk actions](/bulk-actions) to replay multiple failed runs from the dashboard, or [bulk actions with the SDK](/runs/bulk-actions) to replay them from backend code. Bulk replay creates an asynchronous action that targets selected run IDs or a `runs.list()` filter, so you can retry a known failure set without replaying each run individually.

package/docs/github-actions.mdx

@@ -0,0 +1,260 @@
+---
+title: "CI / GitHub Actions"
+description: "Deploy your tasks from GitHub Actions and other CI environments using an environment API key."
+---
+
+The instructions below are specific to GitHub Actions, but the same concepts 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.
+
+<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.
+
+<Warning>
+  The deploy step will fail if any version mismatches are detected. Please see the [version
+  pinning](/github-actions#cli-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 --env prod --external-id ${{ github.sha }}
+```
+
+```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_STAGING_ACCESS_TOKEN }}
+        run: |
+          npx trigger.dev@latest deploy --env staging --external-id ${{ github.sha }}
+```
+
+</CodeGroup>
+
+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](/deployment/atomic-deployment): to complete it, give your running application the **same value** so it sends that id when it triggers.
+
+```bash
+# 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](/deployment/atomic-deployment#when-nothing-ever-lands).
+</Note>
+
+## 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 --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](/deployment/preview-branches#preview-branches-with-github-actions-recommended) for more details.
+</Note>
+
+## 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.
+
+<Steps>
+
+<Step title="Open the API keys page">
+  Select the project and target environment, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
+</Step>
+
+<Step title="Create an API key">
+  Click **New API key**, give the key a name that identifies the workflow, and choose **Deploy
+  only** access.
+</Step>
+
+<Step title="Copy the API key">
+  Create the key and copy its value. Trigger.dev shows the complete value only once.
+</Step>
+
+<Step title="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](/images/github-access-token.png)
+</Step>
+
+</Steps>
+
+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
+{
+  "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
+- 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 --env prod
+```
+
+</CodeGroup>