From 00fac70a123c3f79e2dbe644f8ad4e9623cf6104 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:06:28 -0600 Subject: [PATCH 1/8] docs: crosslink API error references Add focused links from cloud agent, CLI, integration, billing, and API docs to the relevant API/SDK troubleshooting error pages. Co-Authored-By: Oz --- .../agent-platform/cloud-agents/environments.mdx | 6 +++--- .../cloud-agents/integrations/github-actions.mdx | 2 ++ .../cloud-agents/integrations/linear.mdx | 6 +++--- .../cloud-agents/integrations/quickstart.mdx | 4 ++-- .../cloud-agents/integrations/slack.mdx | 6 +++--- .../cloud-agents/managing-cloud-agents.mdx | 2 +- .../docs/agent-platform/cloud-agents/quickstart.mdx | 6 +++--- .../team-access-billing-and-identity.mdx | 10 +++++----- .../cloud-agents/triggers/scheduled-agents.mdx | 2 +- src/content/docs/reference/api-and-sdk/index.mdx | 4 ++-- .../docs/reference/api-and-sdk/quickstart.mdx | 2 +- src/content/docs/reference/cli/api-keys.mdx | 6 +++--- src/content/docs/reference/cli/integration-setup.mdx | 2 ++ src/content/docs/reference/cli/troubleshooting.mdx | 12 ++++++------ 14 files changed, 37 insertions(+), 33 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index 406583c6..3afc8ccf 100644 --- a/src/content/docs/agent-platform/cloud-agents/environments.mdx +++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx @@ -290,12 +290,12 @@ If your setup commands depend on secrets or credentials, configure them through ### Common issues -* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. +* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. Setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). * Solution: Write idempotent setup commands that work on a fresh container. * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization. * Solution: Configure credentials with [Agent Secrets](/agent-platform/cloud-agents/secrets/). -* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. +* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. Missing external authorization can surface as [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup. * **Docker image incompatibility** – You see the error: "VM failed before the agent could run. This is likely an issue with your Docker image." - * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. + * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. This can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). * Solution: Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`). diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 909c336e..5df18385 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -49,6 +49,8 @@ To use agents in GitHub Actions, you need: * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) * Familiarity with GitHub Actions concepts — see the official docs for [GitHub Actions](https://docs.github.com/en/actions) +If the Warp API key is missing, invalid, or expired, the action can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). + ### Using Skills Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agent-platform/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agent-platform/capabilities/skills/#skills-as-agents) to run on a schedule or in response to events. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 3f112fdf..58fbed28 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -66,10 +66,10 @@ Because PRs are created as _you_, this makes code review, auditing, and team col ### Requirements * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email as your Linear workspace. -* **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. +* **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access to the repo if you want Warp to create PRs on your behalf. @@ -124,7 +124,7 @@ To remove the Oz integration from Linear: -After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. +After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index 37c0ea76..158218f5 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -17,9 +17,9 @@ Oz integrations let you trigger cloud agents directly from the tools your team a ## Prerequisites -* **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). +* **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) or run `/create-environment` in Warp. -* **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration. +* **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration; missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). --- diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index b37d510b..beaf547a 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -82,10 +82,10 @@ Because PRs are created as you, the workflow slots seamlessly into your team’s ### Requirements * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email used in your Slack workspace. -* **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. +* **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access for Warp to open PRs on your behalf. @@ -170,7 +170,7 @@ To remove the Oz app from your Slack workspace: ![Confirmation dialog to remove the Oz app from a Slack workspace.](../../../../../assets/agent-platform/remove-slack-app.png) -Once removed, Slack will immediately disable the integration for all teammates. +Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx index 9e5773e6..1c8e72e5 100644 --- a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx @@ -90,7 +90,7 @@ Where the agent was launched from. Common sources include: Warp uses a small set of statuses to help you quickly identify what needs attention: -
StatusIconDescription
WorkingN/Ain progress (may include queued / running states)
Blocked🟨

(interactive only)


the conversation is waiting on user input or a required step

Canceled⬜️(interactive only)

the interactive conversation was canceled before completion
Failed / Errored🔺something went wrong (applies to both interactive and cloud agent runs)
Success✅completed successfully (applies to both interactive and cloud agent runs)
+
StatusIconDescription
WorkingN/Ain progress (may include queued / running states)
Blocked🟨

(interactive only)


the conversation is waiting on user input or a required step

Canceled⬜️(interactive only)

the interactive conversation was canceled before completion
Failed / Errored🔺something went wrong (applies to both interactive and cloud agent runs)
Success✅completed successfully (applies to both interactive and cloud agent runs)
**Duration (for cloud agent tasks)** diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index 8e7b0d5c..0700dd58 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -151,13 +151,13 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical ## Troubleshooting **Environment creation fails**\ -Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images. +Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. **Agent can't access repos**\ -Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. +Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). **Not enough credits to run cloud agents**\ -Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. +Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). **More resources** diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index f000e7ee..2b22b553 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -68,7 +68,7 @@ A [Warp team](/knowledge-and-collaboration/teams/) is a group of users who share Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@Oz** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. -When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. +When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). #### Requirements for integrations @@ -82,10 +82,10 @@ Your team must meet the following requirements to run integrations: When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **User-triggered runs on Build, Max, or Business** - Warp draws from any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user and are not shared across the team. -* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. +* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap; once the cap is reached, runs can return [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/). * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. -If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. +If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. These runs can return [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. :::note If you're on an Enterprise plan, please reach out to [warp.dev/contact-sales](https://www.warp.dev/contact-sales) with any billing questions related to integrations. @@ -197,7 +197,7 @@ Warp’s behavior in GitHub is defined by two layers of control: **In practice, agents can only operate on repositories that:** * Are included in the environment configuration -* Are accessible to both the GitHub app and the triggering user +* Are accessible to both the GitHub app and the triggering user. Missing GitHub authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/), while insufficient permissions can return [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). --- @@ -222,7 +222,7 @@ How credits are consumed depends on how the agent run is triggered and authentic **Team API key and scheduled cloud agent runs** (fully automated or headless workflows): * Runs are not tied to any individual user. -* On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. +* On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted, which can return [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. * On Enterprise plans, these runs draw from the team-scoped credit pool, per your Enterprise contract terms. * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows. * For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Oz by Warp GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx index b41429af..df4501d0 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx @@ -281,7 +281,7 @@ Each scheduled run behaves like a standard cloud agent run, with a few important * Runs execute automatically without human intervention. * All usage is billed to the team’s shared credit balance. -If a scheduled run fails, it does not block future runs. Each execution is independent. +If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. ### Permissions and responsibility diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/reference/api-and-sdk/index.mdx index 152d8643..89f0d09c 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/reference/api-and-sdk/index.mdx @@ -32,7 +32,7 @@ Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [ * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) -* **Consistent error type**s that map to API status codes +* [**Consistent error types**](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes * **Helpers for raw responses** when you need headers/status or custom parsing If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. @@ -105,7 +105,7 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type Fetch full details for a single run, including session link and resolved configuration. -All endpoint semantics, query parameters, and error codes are documented on the [Agents API Reference](/api). +All endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). --- diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index f3472053..71b6ad6f 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -70,7 +70,7 @@ The `state` has the following possible values: * `QUEUED` - The run is waiting to start. * `INPROGRESS` - The agent is actively running. * `SUCCEEDED` - The run completed successfully. -* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details. +* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret the error code. These are the most common states. See the [full API reference](/reference/api-and-sdk/) for all possible values. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index c9207226..5eeff4db 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -44,7 +44,7 @@ Team keys without GitHub App authorization are the right fit for automated workf Warp supports two types of API keys, each with different billing and identity behavior: * **Personal API keys** - Cloud agent runs authenticate as you, just like running an agent from the Warp app or triggering one via Slack or Linear. On Build, Max, and Business plans, runs draw from your plan-included credits, then your add-on credits — both scoped to your individual user. On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. -* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted (insufficient credits error). With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. +* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted ([insufficient credits error](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/)). With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. Team API keys are useful for fully automated workflows, CI/CD pipelines, and scheduled tasks where no specific user context is needed. For the full credit waterfall and how it interacts with add-on credits, see [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/). @@ -66,7 +66,7 @@ $ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase" ``` :::note -API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be invalid or from an older format. +API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). ::: ## Managing API keys @@ -88,7 +88,7 @@ To delete an API key: 2. Find the key you want to delete in the API Keys list. 3. Click the delete icon next to the key. -Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. +Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). ## Best practices diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 97db4c3a..71612ff5 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -52,6 +52,8 @@ Setting up an integration consists of three steps. 2. **Authorize GitHub** so Warp can clone repositories, write code, debug issues, open pull requests, and more. 3. **Configure** the Oz app with an integration. +If setup fails, the returned error code can point to the specific fix: [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for environment initialization, [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) for missing GitHub or external-service authorization, and [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) for incomplete integration setup. + --- ## Step 1: Creating an environment diff --git a/src/content/docs/reference/cli/troubleshooting.mdx b/src/content/docs/reference/cli/troubleshooting.mdx index 025b9d80..ea9eabb2 100644 --- a/src/content/docs/reference/cli/troubleshooting.mdx +++ b/src/content/docs/reference/cli/troubleshooting.mdx @@ -34,7 +34,7 @@ oz --version **Authentication issues** * Interactive login: ensure you've completed the browser-based flow with `oz login`. -* API keys: confirm the key is valid, not expired, and exported correctly. +* API keys: confirm the key is valid, not expired, and exported correctly. Invalid, expired, or missing keys can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). **Agent or MCP errors**\ Ensure your agent profile and [MCP servers](/agent-platform/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/reference/cli/mcp-servers/) and [Agent profiles](/reference/cli/agent-profiles/) for details. @@ -113,7 +113,7 @@ oz environment delete Add `--force` to skip confirmation checks for environments used by integrations. -Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail until you create a new integration with a valid environment. +Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail with a [`resource_not_found` error](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) until you create a new integration with a valid environment. ### Integrations @@ -144,7 +144,7 @@ This happens when: * You add a repo that Warp doesn’t have access to yet, or * You personally haven’t granted the Warp GitHub app permissions for that repo. -Follow the GitHub popup flow to install/adjust the Warp GitHub app. +Follow the GitHub popup flow to install/adjust the Warp GitHub app. Missing external authorization can return an [`external_authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). #### **The agent can’t open PRs or push changes to my repo** @@ -155,7 +155,7 @@ Check the following: 2. **Warp GitHub app has access to that repo** 1. In GitHub’s settings, confirm the Warp app is installed and that the repo is selected. 3. **You have write access** - 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf. + 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf, and the run may return a [`not_authorized` error](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). ### Docker image & environment failures @@ -167,7 +167,7 @@ Check: 2. The image is public on Docker Hub. 3. You can pull it locally: `docker pull ` -If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. +If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. Image pull and setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). #### **The agent can’t find tools or runtimes inside the environment** @@ -178,7 +178,7 @@ This usually means the Docker image is missing required dependencies. Fix by eit #### **I see "VM failed before the agent could run. This is likely an issue with your Docker image"** -This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime. +This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime, and this can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). Fix: From 6d4ee3ca0331872e01b1bff635694e03557fd02e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:36:51 -0600 Subject: [PATCH 2/8] docs: adjust error crosslink placement Co-Authored-By: Oz --- .../cloud-agents/integrations/github-actions.mdx | 4 ++-- .../agent-platform/cloud-agents/integrations/linear.mdx | 6 ++++-- .../agent-platform/cloud-agents/integrations/quickstart.mdx | 6 ++++-- .../docs/agent-platform/cloud-agents/integrations/slack.mdx | 6 ++++-- 4 files changed, 14 insertions(+), 8 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 5df18385..63502f78 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -49,8 +49,6 @@ To use agents in GitHub Actions, you need: * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) * Familiarity with GitHub Actions concepts — see the official docs for [GitHub Actions](https://docs.github.com/en/actions) -If the Warp API key is missing, invalid, or expired, the action can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). - ### Using Skills Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agent-platform/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agent-platform/capabilities/skills/#skills-as-agents) to run on a schedule or in response to events. @@ -67,6 +65,8 @@ You can specify a skill using the `skill` input parameter, either instead of or warp_api_key: ${{ secrets.WARP_API_KEY }} ``` +If the `warp_api_key` secret is missing, invalid, or expired, the action can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). + #### Skill format options The `skill` parameter supports multiple formats for referencing skills: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 58fbed28..d2b88149 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -66,10 +66,10 @@ Because PRs are created as _you_, this makes code review, auditing, and team col ### Requirements * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email as your Linear workspace. -* **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +* **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access to the repo if you want Warp to create PRs on your behalf. @@ -110,6 +110,8 @@ oz integration create linear --environment The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. +If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Linear authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). + --- ### Uninstallation instructions diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index 158218f5..5c7f7060 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -17,9 +17,9 @@ Oz integrations let you trigger cloud agents directly from the tools your team a ## Prerequisites -* **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). +* **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) or run `/create-environment` in Warp. -* **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration; missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +* **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration. --- @@ -43,6 +43,8 @@ oz integration create slack --environment Replace `` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. +If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). + To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: ```bash diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index beaf547a..3d357760 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -82,10 +82,10 @@ Because PRs are created as you, the workflow slots seamlessly into your team’s ### Requirements * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email used in your Slack workspace. -* **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +* **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access for Warp to open PRs on your behalf. @@ -135,6 +135,8 @@ oz integration create slack --environment The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team. +If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). + You can optionally attach a custom prompt that is applied to every agent run: ``` From d40df0829b27add273ddbc206b28f8d13e05f73e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:49:31 -0600 Subject: [PATCH 3/8] docs: style error links as troubleshooting tips Co-Authored-By: Oz --- .../cloud-agents/integrations/github-actions.mdx | 4 +++- .../docs/agent-platform/cloud-agents/integrations/linear.mdx | 4 +++- .../agent-platform/cloud-agents/integrations/quickstart.mdx | 4 +++- .../docs/agent-platform/cloud-agents/integrations/slack.mdx | 4 +++- src/content/docs/reference/cli/integration-setup.mdx | 4 +++- 5 files changed, 15 insertions(+), 5 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 63502f78..37682253 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -65,7 +65,9 @@ You can specify a skill using the `skill` input parameter, either instead of or warp_api_key: ${{ secrets.WARP_API_KEY }} ``` -If the `warp_api_key` secret is missing, invalid, or expired, the action can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +:::tip +**Troubleshooting**: If the `warp_api_key` secret is missing, invalid, or expired, the action can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +::: #### Skill format options diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index d2b88149..3fa8e467 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -110,7 +110,9 @@ oz integration create linear --environment The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. -If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Linear authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +:::tip +**Troubleshooting**: If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Linear authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +::: --- diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index 5c7f7060..fe27ccd2 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -43,7 +43,9 @@ oz integration create slack --environment Replace `` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. -If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +:::tip +**Troubleshooting**: If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +::: To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index 3d357760..f13ae2d7 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -135,7 +135,9 @@ oz integration create slack --environment The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team. -If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +:::tip +**Troubleshooting**: If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +::: You can optionally attach a custom prompt that is applied to every agent run: diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 71612ff5..bb1888f9 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -52,7 +52,9 @@ Setting up an integration consists of three steps. 2. **Authorize GitHub** so Warp can clone repositories, write code, debug issues, open pull requests, and more. 3. **Configure** the Oz app with an integration. -If setup fails, the returned error code can point to the specific fix: [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for environment initialization, [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) for missing GitHub or external-service authorization, and [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) for incomplete integration setup. +:::tip +**Troubleshooting**: If setup fails, the returned error code can point to the specific fix: [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for environment initialization, [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) for missing GitHub or external-service authorization, and [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) for incomplete integration setup. +::: --- From e085d4413f51be20e1a980ad5d157bce65ab3757 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 08:59:52 -0600 Subject: [PATCH 4/8] docs: refine troubleshooting tip formatting Co-Authored-By: Oz --- .../cloud-agents/integrations/github-actions.mdx | 4 +++- .../agent-platform/cloud-agents/integrations/linear.mdx | 5 ++++- .../agent-platform/cloud-agents/integrations/quickstart.mdx | 5 ++++- .../docs/agent-platform/cloud-agents/integrations/slack.mdx | 5 ++++- src/content/docs/reference/cli/integration-setup.mdx | 6 +++++- 5 files changed, 20 insertions(+), 5 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 37682253..92384cd9 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -66,7 +66,9 @@ You can specify a skill using the `skill` input parameter, either instead of or ``` :::tip -**Troubleshooting**: If the `warp_api_key` secret is missing, invalid, or expired, the action can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +If the action fails, use the returned error code to narrow the fix. + +* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/): missing, invalid, or expired `warp_api_key` secret ::: #### Skill format options diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 3fa8e467..6fd1cee1 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -111,7 +111,10 @@ oz integration create linear --environment The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. :::tip -**Troubleshooting**: If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Linear authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. + +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/): plan or credit issues +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or Linear authorization ::: --- diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index fe27ccd2..cbf3528e 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -44,7 +44,10 @@ oz integration create slack --environment Replace `` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. :::tip -**Troubleshooting**: If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. + +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/): plan or credit issues +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or Slack authorization ::: To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index f13ae2d7..3918c3dd 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -136,7 +136,10 @@ oz integration create slack --environment The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team. :::tip -**Troubleshooting**: If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Plan or credit issues can return [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/), while missing GitHub or Slack authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. + +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/): plan or credit issues +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or Slack authorization ::: You can optionally attach a custom prompt that is applied to every agent run: diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index bb1888f9..7da3c113 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -53,7 +53,11 @@ Setting up an integration consists of three steps. 3. **Configure** the Oz app with an integration. :::tip -**Troubleshooting**: If setup fails, the returned error code can point to the specific fix: [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for environment initialization, [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) for missing GitHub or external-service authorization, and [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) for incomplete integration setup. +If setup fails, use the returned error code to narrow the fix. + +* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/): environment initialization issues +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or external-service authorization +* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/): incomplete integration setup ::: --- From 8c6eaf0a83e258ff877f36769c9211361e409438 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 09:09:06 -0600 Subject: [PATCH 5/8] docs: polish troubleshooting tip copy Co-Authored-By: Oz --- .../cloud-agents/integrations/github-actions.mdx | 4 ++-- .../agent-platform/cloud-agents/integrations/linear.mdx | 6 +++--- .../cloud-agents/integrations/quickstart.mdx | 6 +++--- .../agent-platform/cloud-agents/integrations/slack.mdx | 6 +++--- src/content/docs/reference/cli/integration-setup.mdx | 8 ++++---- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 92384cd9..76115bdf 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -66,9 +66,9 @@ You can specify a skill using the `skill` input parameter, either instead of or ``` :::tip -If the action fails, use the returned error code to narrow the fix. +If the action fails, use the returned error code to narrow the fix. Common errors include: -* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/): missing, invalid, or expired `warp_api_key` secret +* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret) ::: #### Skill format options diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 6fd1cee1..d784881e 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -111,10 +111,10 @@ oz integration create linear --environment The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. :::tip -If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. +If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/): plan or credit issues -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or Linear authorization +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) ::: --- diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index cbf3528e..410ef152 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -44,10 +44,10 @@ oz integration create slack --environment Replace `` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. :::tip -If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. +If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/): plan or credit issues -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or Slack authorization +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index 3918c3dd..5676f2ab 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -136,10 +136,10 @@ oz integration create slack --environment The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team. :::tip -If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. +If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/): plan or credit issues -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or Slack authorization +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: You can optionally attach a custom prompt that is applied to every agent run: diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 7da3c113..8aad3139 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -53,11 +53,11 @@ Setting up an integration consists of three steps. 3. **Configure** the Oz app with an integration. :::tip -If setup fails, use the returned error code to narrow the fix. +If setup fails, use the returned error code to narrow the fix. Common errors include: -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/): environment initialization issues -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/): missing GitHub or external-service authorization -* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/): incomplete integration setup +* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization) +* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup) ::: --- From 6a8d8e78852a0c8d889d4321e507decf8ffc5051 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 09:22:12 -0600 Subject: [PATCH 6/8] docs: consolidate integrations overview quickstart Co-Authored-By: Oz --- .../cloud-agents/integrations/index.mdx | 84 ++----------------- 1 file changed, 5 insertions(+), 79 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx index 58f96de6..1aff0032 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx @@ -23,86 +23,12 @@ All of this is powered by the [Oz CLI](/reference/cli/). --- -## Quickstart +## Get started -The fastest way to get agents running from Slack or Linear is to create an environment with the guided flow. An **environment** defines everything the agent needs to run your code remotely, including your Docker image, repos, and setup commands. +To trigger your first agent from Slack or Linear, follow the [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/). It walks through connecting Slack, starting an agent from a message, and watching the run. - - -#### 1. Run /create-environment - -From Warp, run the following slash command: - -``` -/create-environment -``` - -You can run it inside any repo, or point it at multiple repos: - -``` -/create-environment ./frontend ./backend -/create-environment your-org/repo-name -/create-environment https://github.com/your-org/api.git -``` - -:::note -Learn more about slash commands and how to use them in the [Slash Commands](/agent-platform/capabilities/slash-commands/) documentation. -::: - -The guided flow will: - -* Detect which repos you want the agent to work with -* Identify languages, frameworks, and tools -* Suggest a Docker image (or build/push one if needed) - * The Docker image can be your own custom image, an official base image (e.g. node, python), or one of Warp's prebuilt dev images (see [repo](https://github.com/warpdotdev/oz-dev-environments)). -* Recommend setup commands -* Create the environment and return an environment ID - -This produces a ready-to-use environment that Warp can use across Slack, Linear, and terminal triggers. - -#### 2. Authorize GitHub - -Warp will prompt you to install or update the Warp GitHub app so the agent can read and write to the repos you included. You only need to do this once. Teammates will authorize on their first run as needed. - -:::note -**Using Azure DevOps, GitLab, or Bitbucket?** Native integrations for these platforms are not yet available, but you can connect repositories by storing a personal access token as a Warp-managed secret and cloning via a setup command. See [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/), [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), or [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) for step-by-step instructions. -::: - -#### 3. Create an integration +This setup walkthrough shows how to create an environment and connect it to an integration: -:::note -For easier setup, use the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) to configure integrations with a guided flow. The web app works on mobile devices. -::: - -Alternatively, use the CLI: - -For Slack: - -``` -oz integration create slack --environment -``` - -For Linear: - -``` -oz integration create linear --environment -``` - -The CLI opens an authorization page where you install Oz into your Slack workspace or Linear team. - -#### 4. Start using agents - -In Slack: - -* Tag **@Oz** in a message or thread -* Or DM the bot - -In Linear: - -* Tag @Oz on an issue - -Warp will read the thread/issue, spin up your environment, run the workflow in the cloud, and post progress + PRs back into the same conversation. - ---- + -For more details on configuring integrations and environments in Warp, please refer to [Integration setup](/reference/cli/integration-setup/). +For deeper setup details, see [Integration setup](/reference/cli/integration-setup/) for environments, GitHub authorization, CLI flags, and integration configuration. For product-specific behavior, see the [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) references. From e733873d6363efd4490f5339c8b3b869d775752f Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 1 Jun 2026 12:44:00 -0600 Subject: [PATCH 7/8] docs: refine integrations overview links Co-Authored-By: Oz --- .../agent-platform/cloud-agents/integrations/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx index 1aff0032..fdc30a1a 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx @@ -25,10 +25,10 @@ All of this is powered by the [Oz CLI](/reference/cli/). ## Get started -To trigger your first agent from Slack or Linear, follow the [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/). It walks through connecting Slack, starting an agent from a message, and watching the run. - -This setup walkthrough shows how to create an environment and connect it to an integration: +Use the setup walkthrough below for a quick look at how environments connect to integrations, then choose the guide that matches what you want to do next. -For deeper setup details, see [Integration setup](/reference/cli/integration-setup/) for environments, GitHub authorization, CLI flags, and integration configuration. For product-specific behavior, see the [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) references. +* [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish. +* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. +* [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) - Learn how each integration behaves, how agents are triggered, and what teammates see in those tools. From ea6f5e03ca218d7ede953316ee1d70ecced180a0 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 2 Jun 2026 10:36:48 -0600 Subject: [PATCH 8/8] docs: address error crosslink review feedback Co-Authored-By: Oz --- .../cloud-agents/integrations/index.mdx | 7 +++++-- .../cloud-agents/integrations/linear.mdx | 2 +- .../cloud-agents/integrations/quickstart.mdx | 2 +- .../cloud-agents/integrations/slack.mdx | 2 +- .../team-access-billing-and-identity.mdx | 20 ++++++++++++++----- src/content/docs/reference/cli/api-keys.mdx | 2 +- 6 files changed, 24 insertions(+), 11 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx index fdc30a1a..d70b96f4 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx @@ -13,7 +13,7 @@ Warp integrations let your team trigger agents directly from the terminal, or fr * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf -If you're deciding whether an agent should run from a schedule, Slack or Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). +If you're deciding whether an agent should run from a schedule, Slack, Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). :::note For a full walkthrough of Warp's integrations and configurable environments, please refer to [Integration setup](/reference/cli/integration-setup/). @@ -31,4 +31,7 @@ Use the setup walkthrough below for a quick look at how environments connect to * [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish. * [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. -* [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) - Learn how each integration behaves, how agents are triggered, and what teammates see in those tools. +* [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) - Trigger agents from team conversations, issues, and comments. +* [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) - Run agents from CI workflows and repository events. +* [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/), and [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/) - Connect non-GitHub repositories with tokens and Warp-managed secrets. +* [AWS, GCP, and other cloud providers](/agent-platform/cloud-agents/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index d784881e..e31a8da0 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -113,7 +113,7 @@ The CLI will open a browser window prompting you to install the Oz app into your :::tip If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues) +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) * [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) ::: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index 410ef152..70253dc5 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -46,7 +46,7 @@ Replace `` with your environment ID (see [Environments](/agent-platform/ :::tip If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues) +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) * [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index 5676f2ab..86d3d5c9 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -138,7 +138,7 @@ The CLI will open a browser window to install the Oz app into your Slack workspa :::tip If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues) +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) * [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 2b22b553..60cbb5c8 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -68,7 +68,7 @@ A [Warp team](/knowledge-and-collaboration/teams/) is a group of users who share Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@Oz** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. -When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. #### Requirements for integrations @@ -82,10 +82,10 @@ Your team must meet the following requirements to run integrations: When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **User-triggered runs on Build, Max, or Business** - Warp draws from any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user and are not shared across the team. -* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap; once the cap is reached, runs can return [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/). +* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap; once the cap is reached, runs are blocked until the cap resets or increases. * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. -If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. These runs can return [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. +If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. :::note If you're on an Enterprise plan, please reach out to [warp.dev/contact-sales](https://www.warp.dev/contact-sales) with any billing questions related to integrations. @@ -197,7 +197,7 @@ Warp’s behavior in GitHub is defined by two layers of control: **In practice, agents can only operate on repositories that:** * Are included in the environment configuration -* Are accessible to both the GitHub app and the triggering user. Missing GitHub authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/), while insufficient permissions can return [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). +* Are accessible to both the GitHub app and the triggering user. --- @@ -222,7 +222,7 @@ How credits are consumed depends on how the agent run is triggered and authentic **Team API key and scheduled cloud agent runs** (fully automated or headless workflows): * Runs are not tied to any individual user. -* On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted, which can return [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. +* On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. * On Enterprise plans, these runs draw from the team-scoped credit pool, per your Enterprise contract terms. * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows. * For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Oz by Warp GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. @@ -251,6 +251,16 @@ It's the team's responsibility to manage triggers, confirm they behave as intend --- +## Troubleshooting + +If a cloud agent or integration run fails with an error code, use the error reference to narrow the fix: + +* **Missing GitHub or external authorization** - See [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. +* **Insufficient repo permissions** - See [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. +* **Credits or spend caps block a run** - See [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. + +--- + ## Related resources * [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) - How user-scoped add-on credits, auto-reload, and the team-wide spend cap work on self-serve plans. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 5eeff4db..b9651b9b 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -44,7 +44,7 @@ Team keys without GitHub App authorization are the right fit for automated workf Warp supports two types of API keys, each with different billing and identity behavior: * **Personal API keys** - Cloud agent runs authenticate as you, just like running an agent from the Warp app or triggering one via Slack or Linear. On Build, Max, and Business plans, runs draw from your plan-included credits, then your add-on credits — both scoped to your individual user. On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. -* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted ([insufficient credits error](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/)). With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. +* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. Team API keys are useful for fully automated workflows, CI/CD pipelines, and scheduled tasks where no specific user context is needed. For the full credit waterfall and how it interacts with add-on credits, see [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/).