@trigger.dev/sdk 4.8.3 → 4.8.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commonjs/v3/ai-shared.d.ts +3 -2
- package/dist/commonjs/v3/ai-shared.js +219 -28
- package/dist/commonjs/v3/ai-shared.js.map +1 -1
- package/dist/commonjs/v3/ai.d.ts +4 -0
- package/dist/commonjs/v3/ai.js +97 -87
- package/dist/commonjs/v3/ai.js.map +1 -1
- package/dist/commonjs/v3/auth.d.ts +1 -3
- package/dist/commonjs/v3/auth.js +1 -8
- package/dist/commonjs/v3/auth.js.map +1 -1
- package/dist/commonjs/v3/chat-server.js +3 -1
- package/dist/commonjs/v3/chat-server.js.map +1 -1
- package/dist/commonjs/v3/oidc/aws.d.ts +2 -0
- package/dist/commonjs/v3/oidc/aws.js +4 -1
- package/dist/commonjs/v3/oidc/aws.js.map +1 -1
- package/dist/commonjs/v3/oidc/infisical.d.ts +16 -0
- package/dist/commonjs/v3/oidc/infisical.js +43 -0
- package/dist/commonjs/v3/oidc/infisical.js.map +1 -0
- package/dist/commonjs/version.js +1 -1
- package/dist/esm/v3/ai-shared.d.ts +3 -2
- package/dist/esm/v3/ai-shared.js +214 -28
- package/dist/esm/v3/ai-shared.js.map +1 -1
- package/dist/esm/v3/ai.d.ts +4 -0
- package/dist/esm/v3/ai.js +98 -88
- package/dist/esm/v3/ai.js.map +1 -1
- package/dist/esm/v3/auth.d.ts +1 -3
- package/dist/esm/v3/auth.js +1 -8
- package/dist/esm/v3/auth.js.map +1 -1
- package/dist/esm/v3/chat-server.js +4 -2
- package/dist/esm/v3/chat-server.js.map +1 -1
- package/dist/esm/v3/oidc/aws.d.ts +2 -0
- package/dist/esm/v3/oidc/aws.js +4 -1
- package/dist/esm/v3/oidc/aws.js.map +1 -1
- package/dist/esm/v3/oidc/infisical.d.ts +16 -0
- package/dist/esm/v3/oidc/infisical.js +40 -0
- package/dist/esm/v3/oidc/infisical.js.map +1 -0
- package/dist/esm/version.js +1 -1
- package/docs/ai-chat/backend.mdx +2 -2
- package/docs/ai-chat/custom-agents.mdx +8 -1
- package/docs/ai-chat/lifecycle-hooks.mdx +4 -0
- package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
- package/docs/ai-chat/transcript-storage.mdx +3 -1
- package/docs/apikeys/custom-access.mdx +209 -0
- package/docs/apikeys.mdx +50 -14
- package/docs/cli-preview-archive.mdx +8 -0
- package/docs/deployment/overview.mdx +2 -0
- package/docs/deployment/trusted-publishing.mdx +140 -0
- package/docs/github-actions.mdx +2 -2
- package/docs/oidc/anthropic.mdx +187 -0
- package/docs/oidc/aws.mdx +219 -0
- package/docs/oidc/custom.mdx +48 -0
- package/docs/oidc/infisical.mdx +59 -0
- package/docs/oidc.mdx +46 -233
- package/docs/self-hosting/env/webapp.mdx +7 -0
- package/docs/webhooks/public-beta.mdx +70 -0
- package/package.json +17 -2
package/docs/apikeys.mdx
CHANGED
|
@@ -12,7 +12,7 @@ description: "Authenticate backend requests with environment-specific API keys."
|
|
|
12
12
|
|
|
13
13
|
<Tip>
|
|
14
14
|
To access AWS or another external service from a deployed task without stored cloud keys, use
|
|
15
|
-
[
|
|
15
|
+
[workload identity](/oidc). Trigger.dev API keys cannot mint OIDC tokens.
|
|
16
16
|
</Tip>
|
|
17
17
|
|
|
18
18
|
## Create an API key
|
|
@@ -31,12 +31,14 @@ API keys belong to one environment. A Development key cannot access Production,
|
|
|
31
31
|
Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
|
|
32
32
|
</Step>
|
|
33
33
|
<Step title="Create the key">
|
|
34
|
-
Click **
|
|
35
|
-
contain up to 64 characters.
|
|
34
|
+
Click **Create API key**, enter a descriptive name, and choose when it expires: in 30 days, 90
|
|
35
|
+
days (the default), or 1 year, on a custom date, or never. Names can contain up to 64 characters. To
|
|
36
|
+
[restrict the key to your servers](#restrict-a-key-to-ip-addresses), list their IP addresses.
|
|
36
37
|
</Step>
|
|
37
38
|
<Step title="Choose its access">
|
|
38
39
|
Select the narrowest access preset that supports the integration. For task-aware presets, choose
|
|
39
|
-
all tasks or up to 10 task identifiers.
|
|
40
|
+
all tasks or up to 10 task identifiers. When no single preset fits, switch to
|
|
41
|
+
[Custom](/apikeys/custom-access) and combine presets or set each area's level.
|
|
40
42
|
</Step>
|
|
41
43
|
<Step title="Copy and store the secret">
|
|
42
44
|
Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
|
|
@@ -59,7 +61,7 @@ import { configure, tasks } from "@trigger.dev/sdk";
|
|
|
59
61
|
import type { sendEmail } from "./trigger/send-email";
|
|
60
62
|
|
|
61
63
|
configure({
|
|
62
|
-
|
|
64
|
+
accessToken: process.env.TRIGGER_SECRET_KEY,
|
|
63
65
|
previewBranch: "my-branch", // Only needed for preview branches
|
|
64
66
|
baseURL: "https://mytrigger.example.com", // Optional
|
|
65
67
|
});
|
|
@@ -80,21 +82,23 @@ The default API URL is `https://api.trigger.dev`.
|
|
|
80
82
|
|
|
81
83
|
## Access presets
|
|
82
84
|
|
|
83
|
-
Access presets define what a key can do.
|
|
85
|
+
Access presets define what a key can do. Every preset is available on every plan.
|
|
84
86
|
|
|
85
87
|
| Preset | Access |
|
|
86
88
|
| --- | --- |
|
|
87
|
-
| **Trigger only** | Trigger runs and batches for all or selected tasks. Trigger responses include scoped public access tokens for the runs and batches they create |
|
|
88
|
-
| **Task operator** | Trigger all or selected tasks and inspect or operate on their runs |
|
|
89
|
-
| **Observer** | Read runs, tasks, batches, logs, traces, queues, errors, and
|
|
90
|
-
| **Operator** | Observe and operate on runs, queues, errors, and
|
|
89
|
+
| **Trigger only** | Trigger runs and batches for all or selected tasks, and upload large payloads. Trigger responses include scoped public access tokens for the runs and batches they create |
|
|
90
|
+
| **Task operator** | Trigger all or selected tasks, upload large payloads, and inspect or operate on their runs |
|
|
91
|
+
| **Observer** | Read runs, tasks, batches, logs, traces, queues, errors, webhooks, sessions, and prompts |
|
|
92
|
+
| **Operator** | Observe and operate on runs, queues, errors, webhooks, sessions, and waitpoints, close sessions, send to and wait on input streams, read tagged runs and prompts, upload large payloads, and trigger tasks |
|
|
91
93
|
| **Webhooks only** | Read and write [webhooks](/webhooks/overview). Replaying deliveries that trigger tasks and creating webhook waiters require task or waitpoint scopes |
|
|
92
|
-
| **Waitpoints only** | Create,
|
|
94
|
+
| **Waitpoints only** | Create, read, and complete [waitpoint tokens](/wait-for-token), and create and cancel webhook waiters. No task or run access |
|
|
93
95
|
| **Deploy only** | Deploy versions, sync environment variables, and manage Preview branches |
|
|
94
96
|
| **Variables only** | Read and write environment variables in this environment |
|
|
95
97
|
| **No restrictions** | Full access to the environment |
|
|
96
98
|
|
|
97
|
-
**Trigger only** and **Task operator** can be restricted to selected tasks, up to 10 tasks per key. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks
|
|
99
|
+
**Trigger only** and **Task operator** can be restricted to selected tasks, up to 10 tasks per key. Task restrictions use task identifiers, such as `send-email`. A request involving multiple tasks (such as a batch trigger) succeeds only when the key can access every task in the request, so a task-restricted key can batch-trigger only its selected tasks.
|
|
100
|
+
|
|
101
|
+
When no single preset fits, such as a CI key that operates on runs and also deploys, build the key's access with [custom access](/apikeys/custom-access). Your organization can also save custom access as its own preset.
|
|
98
102
|
|
|
99
103
|
## Deploy with an API key
|
|
100
104
|
|
|
@@ -115,9 +119,38 @@ The key must belong to the target environment. Use a Production key with `--env
|
|
|
115
119
|
CLI login.
|
|
116
120
|
</Note>
|
|
117
121
|
|
|
122
|
+
## Restrict a key to IP addresses
|
|
123
|
+
|
|
124
|
+
Give a key a list of allowed IP addresses to limit where it can be used. Requests using the key from any other address are rejected, so a leaked key is useless outside your network. They get the same `Invalid API key` error as a key that doesn't exist, so the response never confirms the key is real. If a working key suddenly returns that error, check its allowed IP addresses.
|
|
125
|
+
|
|
126
|
+
- Enter one IPv4 or IPv6 address or CIDR range per line, for example `203.0.113.9` or `203.0.113.0/24`. A key can have up to 50 ranges.
|
|
127
|
+
- Leave the list empty to allow any IP address.
|
|
128
|
+
- Private and reserved ranges, such as `10.0.0.0/8` or `192.168.0.0/16`, are not accepted. Use the public addresses your requests come from.
|
|
129
|
+
- Set the list when you create the key, or change it later with **Edit allowed IPs** in the key's menu. Changes take effect immediately.
|
|
130
|
+
- The API keys page shows the IP address each key was last used from, so you can check it before saving a list.
|
|
131
|
+
- [Public Access Tokens](/realtime/auth) created with the key are not IP-restricted, since they are meant for browsers. Creating one still requires an allowed IP address.
|
|
132
|
+
|
|
133
|
+
<Tip>
|
|
134
|
+
To lock down an environment, give each backend its own IP-restricted key, move your applications
|
|
135
|
+
to those keys, then hide the root key. Your tasks keep working because they don't authenticate
|
|
136
|
+
with your API keys.
|
|
137
|
+
</Tip>
|
|
138
|
+
|
|
139
|
+
## Change a key's access
|
|
140
|
+
|
|
141
|
+
To change what an existing key can do, click the key on the API keys page to open its details, then click **Edit access**. The key's menu has the same option. Pick another preset or switch to **Custom**, then click **Save access**. The dialog lists what the key gains and loses before you confirm.
|
|
142
|
+
|
|
143
|
+
The key's secret doesn't change, so nothing needs redeploying, and the new access applies to the key's next request. Name, expiry and allowed IP addresses stay as they are. Editing access needs permission to manage API keys in that environment. The root key and revoked or expired keys can't be edited.
|
|
144
|
+
|
|
145
|
+
To remove access a key never uses, click **Narrow to what it used** in the key's details. See [See what a key uses](/apikeys/custom-access#see-what-a-key-uses).
|
|
146
|
+
|
|
147
|
+
### When a key's access differs from its preset
|
|
148
|
+
|
|
149
|
+
A key keeps the access it was created with. If a preset later grants more or less, keys created before the change don't follow it. When a preset now grants more than a key has, the API keys page marks the key with a dot after the preset name in the **Access** column. Click the key to see which areas the preset now grants, then click **Update to current preset** and **Save access** to update the key.
|
|
150
|
+
|
|
118
151
|
## Expire and revoke keys
|
|
119
152
|
|
|
120
|
-
Set an expiration date when creating a key if the integration only needs temporary access. An expired key stops authenticating automatically.
|
|
153
|
+
Set an expiration date when creating a key if the integration only needs temporary access. A key with a custom date works until the end of that day in UTC. An expired key stops authenticating automatically.
|
|
121
154
|
|
|
122
155
|
Revoking a key takes effect immediately and cannot be reversed. Requests using the key fail, and the key can no longer create public access tokens. Create a replacement before revoking a key when you need to rotate it without interrupting the integration.
|
|
123
156
|
|
|
@@ -150,7 +183,9 @@ The SDK sends the branch automatically. When calling the API directly, send the
|
|
|
150
183
|
|
|
151
184
|
## Self-hosting
|
|
152
185
|
|
|
153
|
-
Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
|
|
186
|
+
Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets, custom access, saved presets and key usage are available in Trigger.dev Cloud.
|
|
187
|
+
|
|
188
|
+
IP allowlists use the last address in the `X-Forwarded-For` header, so run the webapp behind a reverse proxy that appends the client IP to that header. To allow private ranges because your clients reach the instance over a private network, set `API_KEY_ALLOW_PRIVATE_IP_RANGES=1`.
|
|
154
189
|
|
|
155
190
|
Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error. Upgrade the instance before creating public tokens with an environment API key.
|
|
156
191
|
|
|
@@ -158,6 +193,7 @@ Keep your instance and SDK current before creating keys. Calling a public-token
|
|
|
158
193
|
|
|
159
194
|
- Create one key per service or integration instead of sharing keys.
|
|
160
195
|
- Choose the narrowest access preset and task selection that supports the integration.
|
|
196
|
+
- Restrict keys used from servers with fixed IP addresses to those addresses.
|
|
161
197
|
- Store keys in a secret manager and inject them as backend environment variables.
|
|
162
198
|
- Set expiration dates for temporary integrations and deployment credentials.
|
|
163
199
|
- Revoke keys when an integration or team member no longer needs access.
|
|
@@ -42,6 +42,14 @@ npx trigger.dev@latest preview archive [path]
|
|
|
42
42
|
|
|
43
43
|
## Options
|
|
44
44
|
|
|
45
|
+
<ParamField body="Authentication method" type="--auth-method <method>">
|
|
46
|
+
Use `auto` (default) or `oidc`. In GitHub Actions, `auto` uses OIDC when no
|
|
47
|
+
`TRIGGER_ACCESS_TOKEN` is set. Explicit `oidc` ignores stored credentials and tokens.
|
|
48
|
+
See [Trusted publishing](/deployment/trusted-publishing).
|
|
49
|
+
</ParamField>
|
|
50
|
+
|
|
51
|
+
You can also authenticate with a parent Preview environment API key in `TRIGGER_ACCESS_TOKEN`.
|
|
52
|
+
|
|
45
53
|
<BranchOption />
|
|
46
54
|
|
|
47
55
|
<ConfigFileOption />
|
|
@@ -24,6 +24,8 @@ yarn dlx trigger.dev@latest deploy
|
|
|
24
24
|
|
|
25
25
|
</CodeGroup>
|
|
26
26
|
|
|
27
|
+
For GitHub Actions workflows without stored API keys, use [Trusted publishing](/deployment/trusted-publishing) with OIDC.
|
|
28
|
+
|
|
27
29
|
## Deploying 101
|
|
28
30
|
|
|
29
31
|
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).
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Trusted publishing"
|
|
3
|
+
description: "Deploy from GitHub Actions without storing a Trigger.dev API key."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Trusted publishing uses GitHub Actions OIDC tokens to authorize deployments. No Personal Access Token or environment API key is needed in GitHub secrets. Builds run entirely on Trigger.dev's build server.
|
|
7
|
+
|
|
8
|
+
## Configure trust
|
|
9
|
+
|
|
10
|
+
1. Select **Staging**, **Preview**, or **Production**, then open [**Trusted publishing**](https://cloud.trigger.dev/_/trusted-publishing) under **Security**.
|
|
11
|
+
2. Enter the **Organization or user** and **Repository**, then click **Save**. This repository configuration applies to the whole project.
|
|
12
|
+
3. Click **Enable** for the selected environment. Choose a **Scope by** option (see [Scope and additional claims](#scope-and-additional-claims)), then click **Save** to allow publishing.
|
|
13
|
+
4. Configure each environment separately. Preview settings apply to **all Preview branches**.
|
|
14
|
+
|
|
15
|
+
Saved settings appear as a read-only row. Click **Edit** to change them. Deleting environment settings returns to the **Enable** button. Unsaved setup is discarded when you leave the page.
|
|
16
|
+
|
|
17
|
+
Development does not use trusted publishing. Changing the repository or its pinned IDs disables publishing for every environment. Re-save each environment to allow publishing again. Deleting the repository removes its grants.
|
|
18
|
+
|
|
19
|
+
### Pin GitHub identities
|
|
20
|
+
|
|
21
|
+
Both fields accept a name alone or a name followed by `@ID`:
|
|
22
|
+
|
|
23
|
+
| Field | Name | Pinned identity |
|
|
24
|
+
| --- | --- | --- |
|
|
25
|
+
| Organization or user | `triggerdotdev` | `triggerdotdev@12345` |
|
|
26
|
+
| Repository | `my-project` | `my-project@67890` |
|
|
27
|
+
|
|
28
|
+
Pinning IDs is recommended: names can be reused after renames, transfers, or deletions. Without an ID, the corresponding name is checked instead.
|
|
29
|
+
|
|
30
|
+
Look up both IDs with the GitHub CLI, using an account with access to the repository:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
gh api repos/OWNER/REPO \
|
|
34
|
+
--jq '{repository_id: .id, repository_owner_id: .owner.id}'
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The organization or user uses `repository_owner_id`; the repository uses `repository_id`. These IDs are not secrets. GitHub Actions also exposes them as `GITHUB_REPOSITORY_OWNER_ID` and `GITHUB_REPOSITORY_ID`.
|
|
38
|
+
|
|
39
|
+
## Scope and additional claims
|
|
40
|
+
|
|
41
|
+
Choose one scope:
|
|
42
|
+
|
|
43
|
+
- **Any branch or tag:** no ref restriction.
|
|
44
|
+
- **Branch:** a branch name such as `main` or `release/*`.
|
|
45
|
+
- **Tag:** a tag name such as `v1.0.0` or `v*`.
|
|
46
|
+
- **Environment:** an exact GitHub Environment name such as `production`. Set `environment: production` on the workflow job and use GitHub's required reviewers or other protections.
|
|
47
|
+
|
|
48
|
+
Branch and tag names support `*` wildcards. Do not include the `refs/heads/` or `refs/tags/` prefix.
|
|
49
|
+
|
|
50
|
+
Additional claims restrict the scope further. Enter a GitHub OIDC token claim name and its accepted values, separated by commas. Every claim must match; any listed value for that claim is accepted. Values match exactly, without wildcards.
|
|
51
|
+
|
|
52
|
+
For example, add `event_name` with `push, workflow_dispatch` to restrict triggers, or `job_workflow_ref` with a reusable workflow's exact ref. You can require a GitHub Environment alongside a branch by adding an `environment` claim.
|
|
53
|
+
|
|
54
|
+
## Preview environments
|
|
55
|
+
|
|
56
|
+
Preview accepts `pull_request` and non-PR workflows, subject to the saved scope and additional claims.
|
|
57
|
+
|
|
58
|
+
Use **Any branch or tag** or a matching **Environment** scope for PR workflows. GitHub's PR ref is typically `refs/pull/NUMBER/merge`, so it does not match a Branch scope such as `main`.
|
|
59
|
+
|
|
60
|
+
From a `pull_request` workflow, deploy to a Preview branch using:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npx trigger.dev@latest deploy \
|
|
64
|
+
--auth-method oidc \
|
|
65
|
+
--native-build \
|
|
66
|
+
--env preview \
|
|
67
|
+
--branch "$GITHUB_HEAD_REF"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
A Preview deploy for a closed or merged PR archives its branch instead of creating a deployment. You can also archive explicitly from a cleanup job with `id-token: write`:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npx trigger.dev@latest preview archive \
|
|
74
|
+
--auth-method oidc \
|
|
75
|
+
--branch "$GITHUB_HEAD_REF"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The workflow must match the project's **Preview** trusted-publishing settings. It can archive any Preview branch in that project, regardless of the workflow's current branch. Archiving preserves branch history; an already archived or missing branch is a successful no-op.
|
|
79
|
+
|
|
80
|
+
`pull_request_target` and other PR event types such as `pull_request_review` are not supported for Preview. Staging and Production reject `pull_request*` events.
|
|
81
|
+
|
|
82
|
+
## GitHub Actions workflow
|
|
83
|
+
|
|
84
|
+
This example assumes a pnpm project with a lockfile and a `packageManager` field in `package.json`. Set `project` in `trigger.config.ts` (or `TRIGGER_PROJECT_REF`) to the project where you configured trust.
|
|
85
|
+
|
|
86
|
+
```yaml .github/workflows/trigger-deploy.yml
|
|
87
|
+
name: Deploy to Trigger.dev
|
|
88
|
+
|
|
89
|
+
on:
|
|
90
|
+
push:
|
|
91
|
+
branches: [main]
|
|
92
|
+
|
|
93
|
+
permissions:
|
|
94
|
+
contents: read
|
|
95
|
+
id-token: write
|
|
96
|
+
|
|
97
|
+
jobs:
|
|
98
|
+
deploy:
|
|
99
|
+
runs-on: ubuntu-latest
|
|
100
|
+
# Add environment: production if your publishing scope requires it.
|
|
101
|
+
steps:
|
|
102
|
+
- uses: actions/checkout@v7.0.1
|
|
103
|
+
- uses: actions/setup-node@v7
|
|
104
|
+
with:
|
|
105
|
+
node-version: "24"
|
|
106
|
+
- uses: pnpm/action-setup@v6
|
|
107
|
+
- run: pnpm install --frozen-lockfile
|
|
108
|
+
- run: |
|
|
109
|
+
npx trigger.dev@latest deploy \
|
|
110
|
+
--auth-method oidc \
|
|
111
|
+
--native-build \
|
|
112
|
+
--env prod
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
For Staging, use `--env staging`. For Preview, use `--env preview --branch YOUR_PREVIEW_BRANCH`.
|
|
116
|
+
|
|
117
|
+
Open **Deployments > Deploys** in the target environment and confirm the new deployment succeeded.
|
|
118
|
+
|
|
119
|
+
`--auth-method oidc` ignores stored credentials and `TRIGGER_ACCESS_TOKEN`. Without that flag, an explicit `TRIGGER_ACCESS_TOKEN` takes precedence over GitHub OIDC, which takes precedence over a saved login.
|
|
120
|
+
|
|
121
|
+
## Promote a deployment
|
|
122
|
+
|
|
123
|
+
To promote a version deployed with `--skip-promotion`, run:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npx trigger.dev@latest promote VERSION --auth-method oidc --env prod
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Use `--env staging` or `--env preview --branch BRANCH` for other environments. Promotion requires the target environment's trusted-publishing settings, including any GitHub Environment or additional-claim restrictions. It cannot promote a version from a different environment or roll back to an older version.
|
|
130
|
+
|
|
131
|
+
`preview archive` and `promote` use the same automatic OIDC selection and `--auth-method oidc` override as `deploy`. `preview archive` also accepts a parent Preview environment API key through `TRIGGER_ACCESS_TOKEN`.
|
|
132
|
+
|
|
133
|
+
## Limits and troubleshooting
|
|
134
|
+
|
|
135
|
+
- Only full build-server builds are supported. Local builds, Depot builds, `--local-bundle`, `--from-bundle`, and `--dry-run` are not supported.
|
|
136
|
+
- The CLI receives no Trigger.dev API key or permission to read or sync environment variables. That work happens inside the build server. Authorized build and task code can still access the target environment's secrets.
|
|
137
|
+
- Submissions are not automatically retried. If a response is lost, check the dashboard before deploying again.
|
|
138
|
+
- If authorization fails, check the project ref, pinned IDs, saved environment settings, scope, additional claims, and `id-token: write` permission.
|
|
139
|
+
|
|
140
|
+
This is separate from [task OIDC](/oidc), which lets running tasks access external services. For API-key authentication, see [CI / GitHub Actions](/github-actions).
|
package/docs/github-actions.mdx
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "CI / GitHub Actions"
|
|
3
|
-
description: "Deploy your tasks from
|
|
3
|
+
description: "Deploy your tasks from CI using trusted deploys or an environment API key."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
For GitHub Actions without stored credentials, use [Trusted publishing](/deployment/trusted-publishing) 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.
|
|
7
7
|
|
|
8
8
|
<Tip>
|
|
9
9
|
Check out our new [GitHub integration](/github-integration) for automatic deployments, without adding any GitHub Actions workflows.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Connect to Anthropic"
|
|
3
|
+
sidebarTitle: "Anthropic"
|
|
4
|
+
description: "Call Claude from your tasks and chat agents without storing an Anthropic API key."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use Anthropic's [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) to exchange a Trigger.dev OIDC token for a short-lived Claude API token. Your tasks and [chat agents](/ai-chat/overview) call Claude with no `ANTHROPIC_API_KEY` stored anywhere.
|
|
8
|
+
|
|
9
|
+
You configure Anthropic to trust your Trigger.dev environment, store three IDs as environment variables, and give the AI SDK's Anthropic provider a token function.
|
|
10
|
+
|
|
11
|
+
Follow the [OIDC prerequisites](/oidc#prerequisites). You also need the admin or owner role in your Anthropic organization.
|
|
12
|
+
|
|
13
|
+
## Configure Anthropic
|
|
14
|
+
|
|
15
|
+
Go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your Trigger.dev environment and copy the issuer URL and subject. Then open [Workload identity](https://platform.claude.com/settings/workload-identity-federation) in the Claude Console, select **Connect workload**, and choose **Custom OIDC**.
|
|
16
|
+
|
|
17
|
+
<Steps>
|
|
18
|
+
<Step title="Issuer">
|
|
19
|
+
| Field | Value |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| **Issuer URL** | Your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`, with no trailing slash. |
|
|
22
|
+
| **Discovery URL override** | Leave blank. |
|
|
23
|
+
| **CA certificate** | Leave blank. |
|
|
24
|
+
| **Enforce single-use tokens** | Leave enabled. Trigger.dev tokens carry a unique `jti`. |
|
|
25
|
+
| **Maximum token lifetime** | Leave at 1 hour. Trigger.dev tokens expire after five minutes. |
|
|
26
|
+
|
|
27
|
+
Confirm that the discovery document and JWKS are reachable from the public internet, then continue. The Console fetches your signing keys at this step.
|
|
28
|
+
</Step>
|
|
29
|
+
<Step title="Federation rule">
|
|
30
|
+
Name the rule, then paste the **complete subject copied from the dashboard** into **Subject (sub) claim**. Leave **Additional claim condition** blank.
|
|
31
|
+
|
|
32
|
+
Under **Enable in workspaces**, select a single workspace. Tokens minted by the rule are billed to it and follow its rate limits.
|
|
33
|
+
|
|
34
|
+
The default scope, `workspace:developer`, matches a workspace API key. If your tasks only call the Messages API, open **Advanced rule options** and set it to `workspace:inference`.
|
|
35
|
+
</Step>
|
|
36
|
+
<Step title="Target">
|
|
37
|
+
Choose **Create a new one** and name the service account, for example `trigger-production`. It joins the rule's workspace automatically.
|
|
38
|
+
</Step>
|
|
39
|
+
<Step title="Test">
|
|
40
|
+
The Console shows a token exchange snippet. Copy the `federation_rule_id` (`fdrl_...`), `organization_id`, and `service_account_id` (`svac_...`) from it. The Console listens for a first exchange for 15 minutes; if that window passes, run the test again from the rule's page.
|
|
41
|
+
</Step>
|
|
42
|
+
</Steps>
|
|
43
|
+
|
|
44
|
+
Anthropic requires the audience `https://api.anthropic.com`, so request that audience when minting tokens for this rule.
|
|
45
|
+
|
|
46
|
+
## Store the IDs
|
|
47
|
+
|
|
48
|
+
Add the three IDs as environment variables on the Trigger.dev environment. None of them is a secret.
|
|
49
|
+
|
|
50
|
+
```bash .env
|
|
51
|
+
ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
|
|
52
|
+
ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
|
|
53
|
+
ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The provider below always authenticates with the federated token, even if `ANTHROPIC_API_KEY` is set. Once federation works, delete the old API key in the Claude Console and remove it from the environment.
|
|
57
|
+
|
|
58
|
+
## Install the packages
|
|
59
|
+
|
|
60
|
+
<CodeGroup>
|
|
61
|
+
|
|
62
|
+
```bash npm
|
|
63
|
+
npm i @trigger.dev/sdk@latest @anthropic-ai/sdk@latest @ai-sdk/anthropic@latest ai@latest
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```bash pnpm
|
|
67
|
+
pnpm add @trigger.dev/sdk@latest @anthropic-ai/sdk@latest @ai-sdk/anthropic@latest ai@latest
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```bash bun
|
|
71
|
+
bun add @trigger.dev/sdk@latest @anthropic-ai/sdk@latest @ai-sdk/anthropic@latest ai@latest
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
</CodeGroup>
|
|
75
|
+
|
|
76
|
+
## Create the Claude provider
|
|
77
|
+
|
|
78
|
+
`oidcFederationProvider` from the Anthropic SDK performs the exchange, and `TokenCache` reuses the resulting token until shortly before it expires. The AI SDK's Anthropic provider calls `authToken` before each request.
|
|
79
|
+
|
|
80
|
+
```ts /trigger/claude.ts
|
|
81
|
+
import { auth } from "@trigger.dev/sdk";
|
|
82
|
+
import { createAnthropic } from "@ai-sdk/anthropic";
|
|
83
|
+
import { oidcFederationProvider } from "@anthropic-ai/sdk/lib/credentials/oidc-federation";
|
|
84
|
+
import { TokenCache } from "@anthropic-ai/sdk/lib/credentials/token-cache";
|
|
85
|
+
|
|
86
|
+
export function claude() {
|
|
87
|
+
const anthropicToken = new TokenCache(
|
|
88
|
+
oidcFederationProvider({
|
|
89
|
+
// Anthropic accepts each token's jti once, so mint a fresh one per exchange.
|
|
90
|
+
identityTokenProvider: async () => {
|
|
91
|
+
const { token } = await auth.getOIDCToken({ audience: "https://api.anthropic.com" });
|
|
92
|
+
return token;
|
|
93
|
+
},
|
|
94
|
+
federationRuleId: process.env.ANTHROPIC_FEDERATION_RULE_ID!,
|
|
95
|
+
organizationId: process.env.ANTHROPIC_ORGANIZATION_ID!,
|
|
96
|
+
serviceAccountId: process.env.ANTHROPIC_SERVICE_ACCOUNT_ID!,
|
|
97
|
+
baseURL: "https://api.anthropic.com",
|
|
98
|
+
fetch,
|
|
99
|
+
})
|
|
100
|
+
);
|
|
101
|
+
|
|
102
|
+
return createAnthropic({ authToken: () => anthropicToken.getToken() });
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
If your rule is enabled in more than one workspace, also pass `workspaceId` (`wrkspc_...`) to `oidcFederationProvider`.
|
|
107
|
+
|
|
108
|
+
## Use it in a chat agent
|
|
109
|
+
|
|
110
|
+
Create the provider inside `run`, so a cached Anthropic token never outlives the run.
|
|
111
|
+
|
|
112
|
+
```ts /trigger/chat.ts
|
|
113
|
+
import { chat } from "@trigger.dev/sdk/ai";
|
|
114
|
+
import { stepCountIs } from "ai";
|
|
115
|
+
import { claude } from "./claude";
|
|
116
|
+
|
|
117
|
+
export const supportChat = chat.agent({
|
|
118
|
+
id: "support-chat",
|
|
119
|
+
run: async ({ messages, signal, streamText }) => {
|
|
120
|
+
const anthropic = claude();
|
|
121
|
+
|
|
122
|
+
return streamText({
|
|
123
|
+
model: anthropic("claude-sonnet-5-5"),
|
|
124
|
+
messages,
|
|
125
|
+
abortSignal: signal,
|
|
126
|
+
stopWhen: stepCountIs(10),
|
|
127
|
+
});
|
|
128
|
+
},
|
|
129
|
+
});
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
<Warning>
|
|
133
|
+
Don't create the provider at module scope or store it in [`chat.local`](/ai-chat/chat-local). A module-scope cache can serve one run's token to the next run in the same process, and `chat.local` values are copied into subtask metadata.
|
|
134
|
+
</Warning>
|
|
135
|
+
|
|
136
|
+
Each turn performs one exchange, and every model call in the turn, including tool-call steps, reuses that token.
|
|
137
|
+
|
|
138
|
+
## Use it in a task
|
|
139
|
+
|
|
140
|
+
The same provider works with any AI SDK function:
|
|
141
|
+
|
|
142
|
+
```ts /trigger/summarize.ts
|
|
143
|
+
import { task } from "@trigger.dev/sdk";
|
|
144
|
+
import { generateText } from "ai";
|
|
145
|
+
import { claude } from "./claude";
|
|
146
|
+
|
|
147
|
+
export const summarize = task({
|
|
148
|
+
id: "summarize",
|
|
149
|
+
run: async (payload: { text: string }) => {
|
|
150
|
+
const anthropic = claude();
|
|
151
|
+
|
|
152
|
+
const { text } = await generateText({
|
|
153
|
+
model: anthropic("claude-sonnet-5-5"),
|
|
154
|
+
prompt: `Summarize in two sentences:\n\n${payload.text}`,
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
return { summary: text };
|
|
158
|
+
},
|
|
159
|
+
});
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## How tokens are refreshed
|
|
163
|
+
|
|
164
|
+
- **The exchange.** `oidcFederationProvider` posts the Trigger.dev token to `https://api.anthropic.com/v1/oauth/token` using the RFC 7523 `jwt-bearer` grant. Anthropic verifies it against your issuer's JWKS and the rule, then returns an access token prefixed `sk-ant-oat01-`.
|
|
165
|
+
- **Lifetime.** The Anthropic token lasts the shorter of the rule's token lifetime and twice the remaining lifetime of the Trigger.dev token, so expect about 10 minutes.
|
|
166
|
+
- **Refresh.** `TokenCache` returns the cached token until two minutes before expiry, then exchanges again in the background. Each exchange calls `identityTokenProvider`, which requests a new Trigger.dev token.
|
|
167
|
+
|
|
168
|
+
## Verify the connection
|
|
169
|
+
|
|
170
|
+
Redeploy, then run `summarize` or send a message to `support-chat`. A successful exchange appears in the [authentication history](https://platform.claude.com/settings/workload-identity-federation?tab=history) in the Claude Console, attributed to the service account.
|
|
171
|
+
|
|
172
|
+
For local Development runs, which cannot mint OIDC tokens, use your own API key: when `ctx.environment.type === "DEVELOPMENT"`, return `createAnthropic()` instead, which reads `ANTHROPIC_API_KEY`.
|
|
173
|
+
|
|
174
|
+
## Troubleshooting
|
|
175
|
+
|
|
176
|
+
### Authentication failed
|
|
177
|
+
|
|
178
|
+
Anthropic returns the same `Authentication failed` error for every rejected exchange. Open the [authentication history](https://platform.claude.com/settings/workload-identity-federation?tab=history) to see the reason, then fix the mismatch:
|
|
179
|
+
|
|
180
|
+
- **Issuer mismatch:** the rule's issuer URL must equal the token's `iss` exactly, including the absence of a trailing slash.
|
|
181
|
+
- **Subject mismatch:** paste the complete subject from the dashboard. Preview branches use the individual branch's subject.
|
|
182
|
+
- **`jti_reused`:** a token was exchanged twice. Keep `identityTokenProvider` requesting a new token on every call instead of caching one.
|
|
183
|
+
- **`workspace_id_required`:** the rule is enabled in more than one workspace. Pass `workspaceId` to `oidcFederationProvider`.
|
|
184
|
+
|
|
185
|
+
### Credit balance is too low
|
|
186
|
+
|
|
187
|
+
The exchange succeeded and the API accepted the token; the workspace has no credits. Add credits under **Plans & Billing** in the Claude Console.
|