Oz > Integrations

GitHub integration

Mention @oz-agent on a GitHub issue, pull request, or review comment to start a cloud agent that replies in the thread and opens pull requests.

The GitHub integration lets your team start cloud agents from GitHub itself. Mention @oz-agent in an issue comment, a pull request review comment, or the body of a new pull request, and Warp starts a cloud agent that reads the surrounding context, works the task in your codebase, and posts its progress and results back into the same thread.

The integration is powered by the Oz by Warp GitHub App. Once a team admin installs the app and enables the GitHub organization, every teammate who has connected their GitHub account can trigger agents from GitHub without leaving a review or an issue.

What the GitHub integration does

@oz-agent mentions - Mention the agent in a comment or pull request body to start a cloud agent run with the issue or pull request as context.
In-thread status - Warp posts a status comment carrying the run link, then follows up with progress comments and a final summary in the same issue, pull request, or review thread.
Thread-aware follow-ups - Mention the agent again in the same thread and Warp continues the existing run instead of starting a new one.
Automatic repository access - The repository the event came from is cloned for the run, alongside any repositories in the environment you configure for the integration.
Team-scoped configuration - A Warp team admin controls which GitHub organizations are enabled, and which environment, model, agent, and prompt GitHub-triggered runs use.

How it works

When you mention @oz-agent, GitHub sends the event to Warp through the Oz by Warp GitHub App installation. Warp then:

Confirms the comment or pull request body contains the @oz-agent mention and that the author is a person rather than a bot.
Maps the GitHub App installation to a Warp team using the organizations enabled in the Admin Panel.
Maps the GitHub account that posted the mention to a Warp account, so the run is attributed to that person.
Posts a status comment in the thread and starts the cloud agent run with the issue, pull request, or review thread as context.
Posts progress updates and a final summary back into the thread, including any pull requests the agent opened and branches it pushed.

The agent replies through Warp’s status comments, which are posted by the GitHub App. Agent replies aren’t posted from the triggering user’s account.

Supported triggers

The integration starts or continues a run for these GitHub events when the text contains @oz-agent:

Issue comments - A new comment on an issue. Warp reads the issue title, description, labels, state, and the recent comment thread.
Pull request comments - A new top-level comment on a pull request. These continue the pull request’s existing run when one exists.
Pull request review comments - A new inline review comment or a reply in a review thread. Warp reads the pull request, the review thread, and the diff of the commented file, and replies inside the same review thread.
New pull requests - A pull request opened with @oz-agent in its description. Warp reads the title, description, and the head and base branches.

Mentions in other places don’t start a run. Editing a comment to add the mention, mentioning the agent in an issue or pull request title, and mentions posted by bots are all ignored.

Follow-ups and existing runs

Warp groups events into a single conversation per issue, pull request, or review thread:

Comments on the same issue continue that issue’s run.
Top-level pull request comments continue that pull request’s run, including a run started from the pull request description.
Replies in a review thread continue that thread’s run.

When a run for that thread is already in flight, a new mention is delivered to the running agent as a follow-up instruction rather than starting a second agent.

Requirements

Team membership - The GitHub integration requires a Warp team. Configuration is team-scoped, and runs are owned by the team associated with the GitHub App installation.
Plan and credits - Your team must be on a plan that supports integrations (Build, Max, or Business) with credits available. See Access, billing, and identity.
Oz by Warp GitHub App - A GitHub organization owner installs the Oz by Warp GitHub App on the organization or account that owns the repositories, granting it access to all repositories or a selected set.
An enabled GitHub organization - A Warp team admin adds the organization under Enabled GitHub Orgs in the Admin Panel so the installation maps to your Warp team.
A connected GitHub account - Each teammate connects their GitHub account to Warp once, so Warp can identify who triggered the run.

Setting up the GitHub integration

Complete steps 1 through 3 once per team. Step 4 is per teammate.

1. Install the GitHub App

Install the app so GitHub can deliver issue and pull request events to Warp, and so agents can read repository context and post comments.

A user with admin permissions on the GitHub organization installs the Oz by Warp GitHub App and grants it access to all repositories or selected repositories. Each installation covers a single GitHub organization or personal account, so install the app separately for every organization your team works in.

Oz by Warp GitHub App installation page showing repository access options — Installing the Oz by Warp GitHub App.

The agent can only act on repositories included in this installation.

2. Enable the GitHub organization for your Warp team

Enabling the organization is what tells Warp which team owns the runs triggered from those repositories.

In the Warp app, a team admin goes to Settings > Admin Panel > Platform and adds the GitHub organization under Enabled GitHub Orgs.

Enabled GitHub Orgs setting in the Admin Panel Platform section — Enabled GitHub Orgs setting in the Admin Panel.

Until the organization is enabled, mentions in its repositories return a comment asking a Warp team admin to enable the organization.

3. Configure how GitHub-triggered runs execute

Configure the integration so every GitHub-triggered run uses the environment and settings your team expects.

Open the Integrations page in the Oz web app. The GitHub integration row shows whether an installation is connected to your team.
Open the row’s settings and choose the environment the runs use, plus an optional model, agent, prompt, and secrets.
Save the configuration.

The repository that triggered the event is always cloned for the run, so an environment is optional. Configure one when runs need additional repositories, a specific Docker image, or setup commands.

4. Connect your GitHub account

Each teammate connects their GitHub account so Warp can attribute a mention to the right Warp user and run with that person’s permissions.

Connect the account from the GitHub integration row in the Oz web app, or the first time you trigger a run: when Warp can’t match your GitHub account, it replies in the thread with a link to connect.

Using @oz-agent in GitHub

Mention the agent and describe the task in the same comment:

@oz-agent this test is flaky on CI. Find the race condition and open a PR with a fix.

On a pull request review comment, the agent also receives the diff for the file you commented on, so you can ask for a targeted change:

@oz-agent rename this helper to parseRepoRef and update the call sites.

Warp responds in the thread with a status comment that links to the run, then posts progress updates as the agent works, and finally posts the agent’s summary along with any pull requests it opened and branches it pushed.

Monitoring runs

Every GitHub-triggered run is a cloud agent run:

In the thread - The status comment links to the run in the Oz web app and, once available, to the live conversation.
In the Oz web app - The Runs page shows the full transcript, status, and metadata. See Viewing cloud agent runs.
In the Warp app - GitHub-triggered runs appear alongside the rest of your team’s runs in the Agent Management Panel.

Permissions and identity

Two layers control what an agent can do in GitHub:

The Oz by Warp GitHub App installation - Determines which organizations and repositories Warp can read, and where the app can post comments. Change the repository selection at any time in your GitHub settings.
The triggering user’s permissions - Runs are attributed to the Warp account bound to the GitHub account that posted the mention, and the agent works with that person’s GitHub access. Agents can’t reach repositories the triggering user can’t access.

Warp matches the GitHub account to a Warp account through the GitHub connection each user authorizes, not by email address. The triggering user must also be a member of the Warp team associated with the installation.

For fully automated workflows that run without a triggering user, such as scheduled agents or runs started with an agent API key, see Team GitHub authorization.

Limitations

Mentions only start runs from comments and pull request descriptions. Issue and pull request titles, commit messages, and edits to an existing comment don’t trigger the agent.
Bots can’t trigger the agent. Mentions posted by GitHub bots or apps are ignored, so an agent can’t start another agent from a comment.
One run per thread at a time. While a run for an issue, pull request, or review thread is active, further mentions become follow-ups to that run.
The installation must map to a Warp team. Repositories in an organization that no Warp team has enabled can’t start runs.
Installations are scoped to one organization each. Install the app separately for every GitHub organization whose repositories your team works in.
The agent replies as the GitHub App. Progress updates and summaries are posted by Oz by Warp; pull requests and commits follow the GitHub authorization of the triggering user.

Troubleshooting

Nothing happens after mentioning @oz-agent

The event never reached Warp, or it was filtered out. Check in this order:

The comment body contains @oz-agent, spelled exactly, rather than only the issue or pull request title.
The Oz by Warp GitHub App is installed on the organization and has access to that repository.
The mention was posted by a person. Bot-authored comments are ignored.
The comment is new. Editing an existing comment to add the mention doesn’t start a run.

”Your GitHub account is not connected to Warp”

Warp received the mention but couldn’t match your GitHub account to a Warp account. Use the link in the reply to connect your GitHub account, then mention the agent again.

”This repository’s GitHub App installation is not associated with a Warp team”

The app is installed, but no Warp team has enabled that GitHub organization. A Warp team admin adds the organization under Enabled GitHub Orgs in Settings > Admin Panel > Platform in the Warp app.

”Your Warp account is not a member of any team associated with this repository”

Your GitHub account is connected, but your Warp account isn’t in the team that enabled the organization. Ask a team admin to add you to the Warp team.

The run starts but fails immediately

Use the error code in the thread’s status comment to narrow the fix. Common errors include:

feature_not_available - The team’s plan doesn’t support integrations.
external_authentication_required - GitHub authorization is missing or expired.
insufficient_credits - The billed account has no credits available.

The agent finished but opened no pull request

Confirm the triggering user has write access to the repository and that the Oz by Warp GitHub App installation includes it. Agents can read public repositories without authorization, but writing branches and pull requests requires both.

Removing or changing the integration

Change repository access - Edit the Oz by Warp installation in your GitHub settings.
Stop runs for an organization - A Warp team admin removes the organization from Enabled GitHub Orgs in the Admin Panel. Mentions in its repositories stop starting runs.
Remove the integration entirely - Uninstall the Oz by Warp GitHub App from the GitHub organization. GitHub stops delivering events to Warp for every repository in that installation.

GitHub Actions - Run agents from your own CI workflows with oz-agent-action.
Integrations overview - The full set of first-party integrations.
Access, billing, and identity - Team GitHub authorization, identity mapping, and credit usage.
Environments - Configure the runtime context for cloud agents.
Viewing cloud agent runs - Inspect and share the runs a mention starts.