diff --git a/package-lock.json b/package-lock.json index 9a09f9ea..7752201d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -594,6 +594,7 @@ "resolved": "https://registry.npmjs.org/@astrojs/markdown-satteri/-/markdown-satteri-0.3.4.tgz", "integrity": "sha512-6Lvt/bQZEBW+zzdhPblvfZEy5PGEYJaUsUqaCgwHeRPxZJL1gc9I+DRLKWJjjYTWDzVUTzXlMq4WwSK+X34CVw==", "license": "MIT", + "peer": true, "dependencies": { "@astrojs/internal-helpers": "0.10.1", "@astrojs/prism": "4.0.2", @@ -729,6 +730,7 @@ "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.41.4.tgz", "integrity": "sha512-cRCKZhM2BKYViCakBiN68aVwPn5qj/XtMMq//G54xOWdXXcvic1gMMEI+veNlIKOqqC4QmIjcjk4jiFtlZ3mMg==", "license": "MIT", + "peer": true, "dependencies": { "@astrojs/markdown-satteri": "^0.3.2", "@astrojs/mdx": "^7.0.0", @@ -903,6 +905,7 @@ "resolved": "https://registry.npmjs.org/@babel/core/-/core-8.0.1.tgz", "integrity": "sha512-5FgxM4dLQpMJHSiVATk8foW263dVHQHBVpXYiimNECVWG01f4nFyEbQixeT6Mwvg7TayREJ2gpKl3o2RoMdnqw==", "license": "MIT", + "peer": true, "dependencies": { "@babel/code-frame": "^8.0.0", "@babel/generator": "^8.0.0", @@ -1569,28 +1572,6 @@ "dev": true, "license": "MIT" }, - "node_modules/@emnapi/core": { - "version": "1.11.2", - "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.2.tgz", - "integrity": "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA==", - "license": "MIT", - "optional": true, - "peer": true, - "dependencies": { - "@emnapi/wasi-threads": "1.2.2", - "tslib": "^2.4.0" - } - }, - "node_modules/@emnapi/runtime": { - "version": "1.11.1", - "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.1.tgz", - "integrity": "sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==", - "license": "MIT", - "optional": true, - "dependencies": { - "tslib": "^2.4.0" - } - }, "node_modules/@emnapi/wasi-threads": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.2.tgz", @@ -3644,8 +3625,7 @@ "optional": true, "os": [ "android" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-android-arm64": { "version": "4.60.2", @@ -3658,8 +3638,7 @@ "optional": true, "os": [ "android" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-darwin-arm64": { "version": "4.60.2", @@ -3672,8 +3651,7 @@ "optional": true, "os": [ "darwin" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-darwin-x64": { "version": "4.60.2", @@ -3686,8 +3664,7 @@ "optional": true, "os": [ "darwin" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-freebsd-arm64": { "version": "4.60.2", @@ -3700,8 +3677,7 @@ "optional": true, "os": [ "freebsd" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-freebsd-x64": { "version": "4.60.2", @@ -3714,8 +3690,7 @@ "optional": true, "os": [ "freebsd" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-arm-gnueabihf": { "version": "4.60.2", @@ -3728,8 +3703,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-arm-musleabihf": { "version": "4.60.2", @@ -3742,8 +3716,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-arm64-gnu": { "version": "4.60.2", @@ -3756,8 +3729,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-arm64-musl": { "version": "4.60.2", @@ -3770,8 +3742,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-loong64-gnu": { "version": "4.60.2", @@ -3784,8 +3755,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-loong64-musl": { "version": "4.60.2", @@ -3798,8 +3768,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-ppc64-gnu": { "version": "4.60.2", @@ -3812,8 +3781,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-ppc64-musl": { "version": "4.60.2", @@ -3826,8 +3794,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-riscv64-gnu": { "version": "4.60.2", @@ -3840,8 +3807,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-riscv64-musl": { "version": "4.60.2", @@ -3854,8 +3820,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-s390x-gnu": { "version": "4.60.2", @@ -3868,8 +3833,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-x64-gnu": { "version": "4.60.2", @@ -3882,8 +3846,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-linux-x64-musl": { "version": "4.60.2", @@ -3896,8 +3859,7 @@ "optional": true, "os": [ "linux" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-openbsd-x64": { "version": "4.60.2", @@ -3910,8 +3872,7 @@ "optional": true, "os": [ "openbsd" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-openharmony-arm64": { "version": "4.60.2", @@ -3924,8 +3885,7 @@ "optional": true, "os": [ "openharmony" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-win32-arm64-msvc": { "version": "4.60.2", @@ -3938,8 +3898,7 @@ "optional": true, "os": [ "win32" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-win32-ia32-msvc": { "version": "4.60.2", @@ -3952,8 +3911,7 @@ "optional": true, "os": [ "win32" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-win32-x64-gnu": { "version": "4.60.2", @@ -3966,8 +3924,7 @@ "optional": true, "os": [ "win32" - ], - "peer": true + ] }, "node_modules/@rollup/rollup-win32-x64-msvc": { "version": "4.60.2", @@ -3980,8 +3937,7 @@ "optional": true, "os": [ "win32" - ], - "peer": true + ] }, "node_modules/@shikijs/core": { "version": "4.3.1", @@ -4680,6 +4636,7 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz", "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==", "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -4825,6 +4782,7 @@ "resolved": "https://registry.npmjs.org/astro/-/astro-7.1.3.tgz", "integrity": "sha512-4dhPyAAXthf3xLEYnG8SeL7yr/nTPPABfY7e9YF0yuO+vK9Xp+8Q5j4xzsmL3GueukQv4oNwGNTBepLOiDGeJA==", "license": "MIT", + "peer": true, "dependencies": { "@astrojs/compiler-rs": "^0.3.1", "@astrojs/internal-helpers": "0.10.1", @@ -5068,6 +5026,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "baseline-browser-mapping": "^2.10.38", "caniuse-lite": "^1.0.30001799", @@ -5538,8 +5497,7 @@ "version": "3.2.3", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz", "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/debug": { "version": "4.4.3", @@ -9164,6 +9122,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "nanoid": "^3.3.16", "picocolors": "^1.1.1", @@ -9217,6 +9176,7 @@ "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==", "dev": true, "license": "MIT", + "peer": true, "bin": { "prettier": "bin/prettier.cjs" }, @@ -9276,6 +9236,7 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==", "license": "MIT", + "peer": true, "engines": { "node": ">=0.10.0" } @@ -9285,6 +9246,7 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz", "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==", "license": "MIT", + "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -9890,52 +9852,6 @@ "@rolldown/binding-win32-x64-msvc": "1.1.5" } }, - "node_modules/rollup": { - "version": "4.60.2", - "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.2.tgz", - "integrity": "sha512-J9qZyW++QK/09NyN/zeO0dG/1GdGfyp9lV8ajHnRVLfo/uFsbji5mHnDgn/qYdUHyCkM2N+8VyspgZclfAh0eQ==", - "license": "MIT", - "optional": true, - "peer": true, - "dependencies": { - "@types/estree": "1.0.8" - }, - "bin": { - "rollup": "dist/bin/rollup" - }, - "engines": { - "node": ">=18.0.0", - "npm": ">=8.0.0" - }, - "optionalDependencies": { - "@rollup/rollup-android-arm-eabi": "4.60.2", - "@rollup/rollup-android-arm64": "4.60.2", - "@rollup/rollup-darwin-arm64": "4.60.2", - "@rollup/rollup-darwin-x64": "4.60.2", - "@rollup/rollup-freebsd-arm64": "4.60.2", - "@rollup/rollup-freebsd-x64": "4.60.2", - "@rollup/rollup-linux-arm-gnueabihf": "4.60.2", - "@rollup/rollup-linux-arm-musleabihf": "4.60.2", - "@rollup/rollup-linux-arm64-gnu": "4.60.2", - "@rollup/rollup-linux-arm64-musl": "4.60.2", - "@rollup/rollup-linux-loong64-gnu": "4.60.2", - "@rollup/rollup-linux-loong64-musl": "4.60.2", - "@rollup/rollup-linux-ppc64-gnu": "4.60.2", - "@rollup/rollup-linux-ppc64-musl": "4.60.2", - "@rollup/rollup-linux-riscv64-gnu": "4.60.2", - "@rollup/rollup-linux-riscv64-musl": "4.60.2", - "@rollup/rollup-linux-s390x-gnu": "4.60.2", - "@rollup/rollup-linux-x64-gnu": "4.60.2", - "@rollup/rollup-linux-x64-musl": "4.60.2", - "@rollup/rollup-openbsd-x64": "4.60.2", - "@rollup/rollup-openharmony-arm64": "4.60.2", - "@rollup/rollup-win32-arm64-msvc": "4.60.2", - "@rollup/rollup-win32-ia32-msvc": "4.60.2", - "@rollup/rollup-win32-x64-gnu": "4.60.2", - "@rollup/rollup-win32-x64-msvc": "4.60.2", - "fsevents": "~2.3.2" - } - }, "node_modules/satteri": { "version": "0.9.5", "resolved": "https://registry.npmjs.org/satteri/-/satteri-0.9.5.tgz", @@ -10449,6 +10365,7 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "devOptional": true, "license": "Apache-2.0", + "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -10932,6 +10849,7 @@ "resolved": "https://registry.npmjs.org/vite/-/vite-8.1.5.tgz", "integrity": "sha512-7ULLwsCdYx/nRyrpiEwvqb5TFHrMVZyBt+rg/OAXT7rgj/z+DtTDyKFeLAdDkubDVDKD8jOsndmy7m55XcfUsw==", "license": "MIT", + "peer": true, "dependencies": { "lightningcss": "^1.32.0", "picomatch": "^4.0.5", @@ -11349,6 +11267,7 @@ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==", "license": "ISC", + "peer": true, "bin": { "yaml": "bin.mjs" }, @@ -11388,6 +11307,7 @@ "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", diff --git a/src/content/docs/guides/agent-workflows/github-repo-access-for-cloud-agents.mdx b/src/content/docs/guides/agent-workflows/github-repo-access-for-cloud-agents.mdx new file mode 100644 index 00000000..bb239f1e --- /dev/null +++ b/src/content/docs/guides/agent-workflows/github-repo-access-for-cloud-agents.mdx @@ -0,0 +1,220 @@ +--- +title: How to grant GitHub repo access to cloud agents +description: >- + Choose the right GitHub repo access pattern for your cloud agents — Oz GitHub + App for automated SA-scoped runs or a GitHub token secret for flexible + environments where the agent handles its own cloning and setup. +sidebar: + label: "Grant GitHub repo access to cloud agents" +tags: + - "cloud-agents" + - "environments" + - "github" +--- + +Cloud agents need GitHub access to clone repositories, push branches, and open pull requests. Warp supports two patterns for granting this access, and choosing the right one depends on how your environment is configured and how your runs are triggered. + +This guide explains both patterns, when to use each, and how to set them up — including the **flexible base environment** pattern, where the agent handles all cloning and setup dynamically rather than using pre-configured repos. + +## The two patterns at a glance + +**Pattern 1 — Oz GitHub App (recommended for automated runs)** + +Install the Oz by Warp GitHub App and configure team GitHub authorization in the Admin Panel. Warp automatically mints a GitHub App installation token for agent API key runs and uses it to authenticate with GitHub. No token management required; Warp handles rotation. + +Best for: fully automated workflows triggered by an agent API key, scheduled agents, CI/CD pipelines. + +**Pattern 2 — GitHub personal access token (PAT) as a Warp-managed secret** + +Create a GitHub PAT, store it as a Warp-managed team secret, and the token is injected as an environment variable into every cloud agent run. The agent can use it to clone any repo the PAT can access. + +Best for: flexible environments where repos are not pre-configured, user-triggered runs, cross-organization repo access, or when you need fine-grained token control. + +--- + +## Choosing a pattern + +Use this table to decide which pattern fits your setup. + +| Factor | Pattern 1: GitHub App | Pattern 2: PAT secret | +|--|--|--| +| Recommended trigger type | Agent API key (SA-scoped) | All types: user, agent API key, scheduled | +| Repos must be pre-configured in the environment | Yes | No | +| Token rotation | Automatic | Manual | +| GitHub attribution on PRs/commits | Oz by Warp GitHub App | Whoever owns the PAT | +| Cross-org repo access | One org per installation | Any repos the PAT can access | +| Flexible base environment (agent clones on the fly) | Only if repos are configured | Yes | + +:::note +If you are running a **flexible base environment** — one Docker image with no repos pre-configured, where the agent handles all cloning and setup — use **Pattern 2**. The GitHub App token is only generated when repos are declared in the environment configuration, so it is not available for environment-less or repo-less setups. +::: + +--- + +## Pattern 1: Oz GitHub App + agent API key + +This is the recommended approach for fully automated workflows that use an agent API key. Warp automatically mints a short-lived GitHub App installation token and configures git credentials in the agent's sandbox. You don't manage the token. + +### How it works + +When a run starts with an agent API key, Warp looks up the team's Oz by Warp GitHub App installation and generates a token scoped to the repos declared in the environment. The token is used to clone repos during environment setup and is available to the agent for any additional GitHub operations during the run. + +Commits and pull requests are attributed to the Oz by Warp GitHub App rather than any individual user. + +### Prerequisites + +- Admin access to your GitHub organization +- A Warp team admin to configure the Admin Panel +- An [agent API key](/reference/cli/api-keys/) for automated runs + +### Setup steps + +1. **Install the Oz by Warp GitHub App.** + + A GitHub organization admin installs the [Oz by Warp](https://github.com/apps/oz-by-warp) GitHub App. + + During installation, choose the repositories the app can access: + - **All repositories** — grants the app access to every current and future repo in the org. Use this when you want agents to work across many repos without updating the installation. + - **Selected repositories** — restricts access to specific repos. Use this for tighter scoping. + + :::tip + If you want agents to be able to clone different repos across runs without updating the GitHub App installation each time, choose **All repositories**. + ::: + +2. **Enable the GitHub organization in the Admin Panel.** + + A Warp team admin opens **Settings** > **Admin Panel** > **Platform** in the Warp app and adds the GitHub organization under **Enabled GitHub Orgs**. This associates the app installation with your Warp team. + +3. **Configure repos in your environment.** + + Open the [Environments page in the Oz web app](https://oz.warp.dev/environments) and add the GitHub repos your agent needs. The GitHub App token is scoped to these repos and is only generated when at least one repo is configured. + + ```sh + oz environment update --repo owner/repo + ``` + +4. **Use an agent API key for runs.** + + Create and use an [agent API key](/reference/cli/api-keys/) when triggering runs. Tasks initiated with an agent API key use the GitHub App token automatically. + +For full setup instructions, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). + +--- + +## Pattern 2: GitHub PAT as a Warp-managed secret + +Store a GitHub Personal Access Token (PAT) as a Warp-managed team secret. The token is injected as an environment variable in every cloud agent run, and the agent can use it to clone any repo the PAT can access. + +This pattern works for all run types and does not require repos to be pre-configured in the environment, making it ideal for flexible base environments. + +### How it works + +Warp-managed secrets are injected as environment variables at run start. When you store a GitHub PAT as a team secret, the agent process has access to it as `$YOUR_SECRET_NAME` and can use it to authenticate git operations. + +### Prerequisites + +- A GitHub account with access to the repositories your agents need to clone + +### Setup steps + +1. **Create a GitHub Personal Access Token.** + + In your GitHub account settings, create a Personal Access Token: + + - **Classic PAT**: Go to **Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)**. Grant the `repo` scope (or `public_repo` for public repos only). + - **Fine-grained PAT** (recommended for tighter scoping): Go to **Settings** > **Developer settings** > **Personal access tokens** > **Fine-grained tokens**. Choose the resource owner, select the repos it can access, and grant **Contents** read permission (and **Pull requests** write permission if the agent will open PRs). + + :::caution + Classic PATs are scoped to a single GitHub account, not an organization. If you want the agent to work across all repos in your org, you may also need to authorize the PAT for your organization's SSO (if enabled). + ::: + +2. **Store the token as a Warp-managed team secret.** + + Use the Oz CLI to create a team secret. The secret name becomes the environment variable name the agent receives. + + ```bash + oz secret create --team GH_TOKEN + ``` + + You will be prompted to enter the token value securely. Alternatively, create the secret in the [Oz web app](https://oz.warp.dev/secrets): open the **Secrets** page, click **Add secret**, enter `GH_TOKEN` as the name, paste the token value, choose **Team** scope, and click **Create secret**. + + :::note + Use a service account or a dedicated bot GitHub account rather than a personal account, so access isn't disrupted if a team member leaves. + ::: + +3. **Use the token in your environment or agent workflow.** + + The token is automatically injected as the `GH_TOKEN` environment variable in every cloud agent run. You can reference it in setup commands or in the agent's workflow: + + ```sh + # Clone a repo using the injected token + git clone https://x-access-token:$GH_TOKEN@github.com/your-org/your-repo.git + + # Or configure git to use the token globally for all HTTPS operations + git config --global url."https://x-access-token:$GH_TOKEN@github.com/".insteadOf "https://github.com/" + ``` + + Adding the global git config to your environment's setup commands lets the agent clone any repo by URL without explicitly referencing the token each time. + +4. **Add git credential configuration to your setup commands (optional).** + + For flexible environments where the agent will clone repos dynamically, add git credential configuration as a setup command so it's ready before the agent starts: + + ```sh + # In your environment's setup commands: + git config --global url."https://x-access-token:$GH_TOKEN@github.com/".insteadOf "https://github.com/" + ``` + + To add this to an existing environment: + + ```sh + oz environment update \ + --setup-command 'git config --global url."https://x-access-token:$GH_TOKEN@github.com/".insteadOf "https://github.com/"' + ``` + +--- + +## Flexible base environment pattern + +A **flexible base environment** uses a single Docker image and no pre-configured repos. The agent handles all repository cloning and setup dynamically at run time — useful when you want one environment that can work across any repository without reconfiguring the environment for each project. + +To use this pattern: + +1. Create an environment with your base Docker image but **no repos configured**. + + ```sh + oz environment create \ + --name "flexible-base" \ + --docker-image your-org/dev-image:latest + ``` + +2. Store a GitHub PAT as a Warp-managed team secret (Pattern 2 above). + +3. Add git credential configuration as a setup command: + + ```sh + oz environment update \ + --setup-command 'git config --global url."https://x-access-token:$GH_TOKEN@github.com/".insteadOf "https://github.com/"' + ``` + +4. When triggering a run, include repository and setup instructions in the prompt: + + ```text + Clone https://github.com/your-org/your-repo.git, install dependencies, and fix the failing test in src/auth. + ``` + +The agent will use the injected `GH_TOKEN` to clone the repo and proceed with the task. + +:::note +Pattern 1 (GitHub App) is not suitable for environment-less or no-repo setups because the GitHub App token is only minted when at least one repo is declared in the environment configuration. +::: + +--- + +## Related resources + +- [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) — full setup guide for the Oz GitHub App +- [Cloud agent environments](/platform/environments/) — how to create and configure environments +- [Agent secrets](/platform/secrets/) — how to create, scope, and manage Warp-managed secrets +- [API keys](/reference/cli/api-keys/) — creating agent API keys for automated workflows +- [Integration setup](/reference/cli/integration-setup/#authorizing-github) — GitHub authorization for Slack and Linear integrations diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index 4a1a84c7..546d3697 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -135,7 +135,7 @@ You can create environments in three ways: from the Oz web app, using the guided Make sure you have: * One or more GitHub repositories that the agent should clone and work in. -* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. +* **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. If you need a **flexible base environment** where the agent clones repos dynamically at run time, see [Grant GitHub repo access to cloud agents](/guides/agent-workflows/github-repo-access-for-cloud-agents/) for the recommended approach. * A publicly-accessible Docker image that can build and run your code. Official images like [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), or [rust](https://hub.docker.com/_/rust) work for many projects. You can also use one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). :::caution @@ -306,7 +306,7 @@ If your setup commands depend on secrets or credentials, configure them through * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization. * Solution: Configure credentials with [Agent Secrets](/platform/secrets/). * **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. + * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup. For a comparison of both GitHub access patterns — including how to set up a flexible base environment where the agent handles cloning — see [Grant GitHub repo access to cloud agents](/guides/agent-workflows/github-repo-access-for-cloud-agents/). * **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. 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/platform/team-access-billing-and-identity.mdx b/src/content/docs/platform/team-access-billing-and-identity.mdx index 2d38e7d9..28c6f627 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -151,6 +151,10 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm * **Environment repo list** - "This agent needs repos A, B, and C." * **Enabled GitHub Orgs** - "This team can use the Oz by Warp GitHub App to access repos in this GitHub organization." +:::note +**Flexible base environments**: The GitHub App installation token is only minted for agent API key runs when the environment has at least one repo configured. If you are using a **flexible base environment** with no repos pre-configured — where the agent handles all cloning dynamically at run time — the GitHub App token is not available for those runs. In that case, store a GitHub Personal Access Token (PAT) as a [Warp-managed team secret](/platform/secrets/) instead. The injected token is then available to the agent for cloning any repo the PAT can access. See [Grant GitHub repo access to cloud agents](/guides/agent-workflows/github-repo-access-for-cloud-agents/) for a full comparison and setup steps. +::: + ### Personal tokens vs. GitHub App tokens Team GitHub authorization is complementary to the existing personal token flow: diff --git a/src/sidebar.ts b/src/sidebar.ts index 1394d88c..f3b36619 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -667,6 +667,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'guides/agent-workflows/how-to-review-ai-generated-code', label: 'Review AI-generated code' }, { slug: 'guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs', label: 'Attach agent context to PRs' }, { slug: 'guides/agent-workflows/how-to-run-unattended-agents', label: 'Run agents unattended' }, + { slug: 'guides/agent-workflows/github-repo-access-for-cloud-agents', label: 'Grant GitHub repo access to cloud agents' }, { slug: 'guides/agent-workflows/how-to-run-multiple-ai-coding-agents', label: 'Run multiple AI coding agents' }, { slug: 'guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents', label: 'Use voice and images to prompt agents' }, { slug: 'guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase', label: 'Explain your codebase with agents' },