> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Trigger tasks from GitHub issues and iterate on pull requests with Replicas.

Replicas responds to GitHub issue comments and PR comments. Whether starting new work from a GitHub issue, iterating on a PR from Linear, or working on any existing PR, it maintains context across all interactions.

## Setup

1. Go to [Organization → Integrations](https://app.replicas.dev/dashboard/integrations)
2. Find **GitHub**, click **Install**, and authorize your account
3. If prompted, install the Replicas GitHub App on your repositories
4. Add repositories to an [environment](https://docs.replicas.dev/features/environments.md#repository-binding) with **Add repository**

Use **Manage repository access** to change which repositories the app can access, then add newly allowed repositories to an environment with **Add repository**.

Reconnecting GitHub refreshes the App installation used by repositories already connected to your organization, preserving their environments and default branches. If the App was removed, restore its repository access before reconnecting.

If GitHub rejects the saved authorization, for example after you revoke the Replicas app in your GitHub settings, the connection shows **Reconnect required** in **Organization → Integrations** and **Personal → Connections**. Reconnect it there to restore access. Approving pull requests from the workspace header uses your personal GitHub connection.

That's it! Once a repository is added to your organization, anyone with write access to that repository can use `@tryreplicas` mentions on its issues and PRs. If your organization turns on [Require Replicas account](https://docs.replicas.dev/admin/security.md), each person must instead connect their own GitHub account under [Personal → Connections](https://app.replicas.dev/dashboard/account/connections).

> [!NOTE]
>
> Each repository can only be connected to one Replicas organization. If you need to transfer a repository to a different organization, remove it from the current organization first.

### Default branch

Each repository has a configurable default branch that controls which branch new workspaces clone, which branch the *Changes* view diffs against, and which branch warm pools sync to. It defaults to `main`. When you create a task from Home, you can choose a different starting branch for that workspace without changing the repository default.

To change it, open **[Organization → Integrations → GitHub](https://app.replicas.dev/dashboard/integrations/github)**, find the repository under **Repositories** (which also lists the environments using it), click the pencil icon next to the branch name, enter the new branch (e.g. `staging`, `develop`), and confirm. The setting is organization-scoped and applies to every workspace and warm pool that uses the repository.

Use it for repositories where your primary branch isn't `main`, so workspaces start from the right branch and PR diffs are computed against the branch you actually merge into. A per-task branch choice changes only that workspace's checkout and *Changes* baseline.

## How It Works

Workspaces created from GitHub triggers use your organization's [default coding agent and model](https://docs.replicas.dev/admin/defaults.md).

### Trigger from GitHub Issues

Add `@tryreplicas` to any comment on a GitHub issue to start a new task.

* Replicas creates a new workspace to work on the issue
* The agent provides an implementation plan before making changes
* When complete, the agent creates a PR and comments on the original issue with:
  * A link to the PR
  * A summary of the changes made
* When the issue is closed, the associated workspace is [archived](https://docs.replicas.dev/features/workspaces/overview.md#sleep-and-wake), keeping its conversation history; closing an issue never deletes the workspace

Each issue is linked to one workspace. All interactions on the issue route to the same workspace. Follow-up comments mentioning `@tryreplicas` [wake or restore](https://docs.replicas.dev/features/workspaces/overview.md#sleep-and-wake) that workspace automatically.

If the agent cannot complete a turn started from an issue comment, Replicas posts the concrete error on the issue when available.

### Trigger from Pull Requests

Add `@tryreplicas` to any pull request review (e.g requesting changes) or comment.

* If the pull request was made by a Replicas agent, it will see it, make changes, and respond directly to you.
* If the pull request was made by someone else, a new workspace and Replicas agent will be spun up.

Each PR is linked to one workspace. All interactions route to the same workspace, so the agent remembers previous work. Sleeping workspaces wake automatically. Follow-up messages also [restore](https://docs.replicas.dev/features/workspaces/overview.md#sleep-and-wake) archived workspaces.

If Replicas cannot start the workspace agent, deliver its initial task, or complete a later turn from a GitHub comment or review, it posts the concrete error when available.

Pull Request Cleanup has two independent toggles in [Defaults](https://docs.replicas.dev/admin/defaults.md): one [archives](https://docs.replicas.dev/features/workspaces/overview.md#sleep-and-wake) the workspace when a user merges its PR, the other when a user closes its PR without merging. Each can be overridden per workspace. PRs closed by Replicas leave the linked workspace open. Archived workspaces keep their conversation history and can be explicitly restored at any time; closing a PR never deletes the workspace (archived workspaces may still be removed later by the retention policy).

### Auto Respond To Review Bots And Users

You can configure an allowlist in **Organization → Settings → Preferences → Review bots** to automatically react to specific GitHub accounts (bots or users) without requiring `@tryreplicas`.

Search for reviewer bots like `greptile-apps[bot]`, `coderabbitai[bot]`, and `copilot-swe-agent[bot]` (the GitHub Copilot coding agent), or paste an exact login to add a non-bot user account, then add them to the allowlist.

Accounts not on the allowlist cannot trigger Replicas. When a known review bot (Greptile, CodeRabbit, Copilot, and others) comments on a Replicas PR without being on the list, Replicas replies once on the PR, and admins can turn the bot on from that PR's workspace chat. If an unauthorized bot attempts to interact, it will receive a message directing org admins to add the login under **Review bots**.

After Replicas addresses actionable feedback from an enabled review bot, it always replies and tags the same bot account that sent the review. It does not reply to clean or acknowledgment-only bot messages.

On linked PRs, bot feedback—including Greptile reviews—runs in the same separate chat as [CI fixes](#ci-failure-response). Human comments continue in the main chat.

### Silence Replicas On A Single PR

To stop Replicas from auto-responding on one specific pull request without changing any org-wide setting, add the label `replicas-skip` to the PR, or include a marker like `[skip replicas]` in the PR title or body. Replicas then stays quiet on that PR across every auto-respond path: review-bot and allowlisted-user comments, human PR reviews, and CI/CD failures.

An explicit `@replicas` mention still works and overrides the marker, so you can pull Replicas back in for a one-off reply. Accepted labels: `replicas-skip`, `skip-replicas`, `replicas-ignore`, `no-replicas`. Accepted title/body markers: `[skip replicas]`, `[replicas skip]`, `[no replicas]`. The same marker also mutes [automations](https://docs.replicas.dev/features/automations.md#github-triggers) on the PR.

### Human PR Review Auto-Response

By default, human PR reviews and inline review comments on Replicas-linked PRs do not trigger Replicas unless the reviewer mentions `@tryreplicas`, `@replicas`, or `@replicas-connector`.

Admins can turn on **Organization → Settings → Preferences → CI failures and reviews → Respond to human PR reviews** when they want Replicas to react to all human PR reviews on linked PRs. This does not affect [auto responders](#auto-respond-to-review-bots-and-users) or [CI failure response](#ci-failure-response).

Bot reviewers must still be enabled under [Review bots](#auto-respond-to-review-bots-and-users); non-allowlisted bots do not auto-trigger from PR reviews.

### CI failure response

When a CI/CD check fails on a pull request linked to a Replicas workspace, the agent is automatically notified and investigates the failure. It reads the failure logs, diagnoses the issue, pushes a fix, and comments on the PR.

CI failures and review-bot feedback share a **PR #… fixes** chat forked from the main chat. Later feedback reuses that fork, keeping your main conversation uninterrupted. With Claude Code and Codex, the fork copies the main chat's session, and re-copies it when the main chat has finished new turns, so it knows everything you've said there. Decisions you make about the PR (what to keep, avoid, or do a certain way) are also listed in its notes file. The fork won't undo them just to satisfy a check or bot; it skips that fix and asks you to decide. Opening the workspace lands in the main chat. While only the fork is working, the sidebar shows a pull request icon instead of the loader, and the main chat shows a notice. The fork fixes the PR in its own git worktree, so it never touches the files the main chat is changing. With Claude Code, it tells the main chat what it's fixing and when it pushes, and those messages show in both chats. Workspaces created from older sandbox images keep receiving this feedback in the main chat.

CI failures wake a sleeping workspace automatically. Archived workspaces stay paused and must be [restored](https://docs.replicas.dev/features/workspaces/overview.md#sleep-and-wake) before Replicas can respond to later failures.

If the CI-triggered agent turn fails, Replicas posts the concrete error on the originating PR when available.

This works with two sources of CI failures:

* **GitHub Actions workflows**, triggered via `workflow_run` events when a workflow completes with a failure.
* **External CI checks**, triggered via `check_run` events from any non-Actions provider that posts results through the GitHub Checks API (e.g. Mintlify, CircleCI, Buildkite).

Both sources can be independently toggled in **Organization → Settings → CI Failure Response**:

* **Respond to CI workflows**: controls auto-response for GitHub Actions failures (enabled by default).
* **Respond to CI checks**: controls auto-response for external CI check failures (enabled by default).

> [!NOTE]
>
> CI providers that report status via the Statuses API or Deployments API (e.g. Vercel deployment status) are not yet covered by this feature.

The agent posts one tracker comment per PR with a table of all CI failures, their status, and notes. New failures append a row to the same comment.

When several CI failures, PR comments, or PR reviews arrive while the agent is busy, the engine folds consecutive entries of the same kind into one combined turn instead of running them back-to-back. For example, if three CI jobs fail on the same PR seconds apart, the agent gets one bundled message and fixes them in a single turn. The chat history renders these as a *Bundled* card with one expandable sub-card per original message, and the queue panel shows an *N messages* badge on the entry.

### PR Attribution

Pull requests created by Replicas agents use the Replicas bot by default.

Organizations can require user attribution with **Organization → Settings → Security → Require PR user attribution**. When enabled, the code host tooling inside the workspace uses the triggering user's personal code-host OAuth token, so `gh pr create`, GitLab merge request push options, pushes, and commit identity resolve to that user instead of the Replicas bot.

Turning on the organization policy automatically enables and locks **Require code host connected** and **Require Replicas account** because attribution cannot work without both.

Users can also require attribution for their own workspaces with **Personal → Preferences → Require PR user attribution**. This works even when the organization policy is off.

Commits made as you use your GitHub profile's public email, or your GitHub noreply address when it has none. To use another email, pick one of your verified GitHub emails in **Personal → Preferences → Commit email**, and optionally set **Commit name**. This also applies to your co-author trailer. Services that match commit emails to accounts, like Vercel, need the email they know you by. Running workspaces switch on their next push or credential refresh.

Required attribution needs Replicas to resolve the triggering user and that user's connected code-host account. Workspace creation and code-host token refresh fail closed until both are available.

Automation and API-key workspaces have no attached user and fall back to the Replicas bot for PR attribution.

Agents require the configured co-author trailers as one final block on every commit and include the same trailers at the end of pull request descriptions. Replicas checks each commit a command runs, whether its message comes from `-m`, a heredoc, `-F <file>`, `--trailer`, or `--amend --no-edit`; text that only mentions a commit, merge commits, and commits in a scratch repository the command creates are not checked. For repositories that squash merges, set the default squash commit message to **Pull request title and description** so GitHub preserves both user and Replicas attribution.

### PR Merge Blocking

When the organization security policy `block_agent_pr_merges` is enabled, agents are blocked from merging pull requests or merge requests. This prevents agents from bypassing human review by auto-merging their own work.

Blocked commands include `gh pr merge`, direct GitHub or GitLab API merge calls, and `git push` to the default branch, including after checking it out. When an agent attempts a blocked command, it receives a policy-blocked response naming this setting.

Agents can still update a feature branch from the default branch (`git merge origin/main`, `git pull origin main`, or `git rebase origin/main`) and push that feature branch.

This is controlled by **Organization → Settings → Security → Block agent PR/MR merges**. It is separate from **Require PR user attribution**, so organizations can enforce attribution without blocking merges, or block merges without changing attribution behavior.

### Draft Pull Requests

Workspace agents can be instructed to open every new pull request as a draft. When enabled, the agent's system prompt includes a clause telling it to use `gh pr create --draft` (or set `"draft": true` when hitting the GitHub REST API directly).

This feature is **off by default** and resolves in the standard order:

* **User preference** (`auto_draft_prs`): Toggle **Open new PRs as drafts** in **Personal → Preferences** to draft PRs for your own workspaces.
* **Organization preference** (`auto_draft_prs`): Falls back to the org-level value when no user preference is set.
* **Default**: `false` (PRs are opened as normal pull requests).

You can still ask the agent to open a non-draft PR on a specific task. The setting controls the default, not a hard ceiling.

### Pull Request Discovery

On harnesses with post-tool hooks, Replicas links a pull request to its workspace as soon as the agent creates or pushes it, rather than waiting for the turn to end, so the workspace header, [footer verification](#replicas-footer), and PR-linked triggers apply right away. Discovery also runs at the end of every turn, so pull requests opened outside a tool call or by harnesses without post-tool hooks are still picked up.

Discovery only links PRs confirmed by the code host for branches used in the workspace. Viewing a PR, reading it through the API, or citing its URL in tool output or a report does not link it.

Repositories the agent clones outside the workspace folder are included once it pushes from them, and appear in the workspace by their full path. External and nested Git worktrees are included. Claude publication events and successful Codex or OpenCode publishing-tool results also preserve PR links after a temporary worktree is removed. Commands with missing output or mixed results continue to use branch discovery.

Pull requests in repositories that aren't part of the workspace get no webhooks, so Replicas checks their status itself: every few minutes while they're new, less often as they age. If Replicas can't read one, for example because the GitHub App can't access the repository or GitLab isn't connected, the workspace's pull request list says why its status won't update.

The same applies to [GitLab merge requests](https://docs.replicas.dev/features/gitlab.md).

### Replicas Footer

Every pull request opened from a workspace carries a footer crediting the person who started it and linking back to the workspace:

```html theme={null}
Created by <b>Name</b> (name@example.com) with Replicas
[Replicas | Workspace] [Linear | REP-398] [Slack | Thread]
```

Workspace, Linear, and Slack destinations render as compact badge buttons.

The agent writes the footer as part of the description, and Replicas verifies it when the pull request is discovered and whenever its description is edited. If it is missing, the footer is appended automatically. An existing Replicas workspace footer is preserved, even when another workspace works on the same pull request. Only pull requests on repositories attached to the workspace are verified, and merged and closed pull requests are left untouched. Workspace footer links use `app.replicas.dev/workspaces/...`. Older `replicas.dev/workspaces/...` links still redirect; include both domains when counting Replicas-authored pull requests.

The same footer guarantee applies to [GitLab merge requests](https://docs.replicas.dev/features/gitlab.md#replicas-footer), including eligible repositories cloned during a task.

### Screenshots and GIFs

Agents add screenshots of visible changes to the description, and a looping GIF for motion or interactions, made with [`replicas media gif`](https://docs.replicas.dev/features/cli#media). Both render inline on GitHub. GitHub can't play videos, so a GIF links to the full recording when there is one.

In a workspace, `gh pr create`, `gh pr edit`, and `gh pr comment` (and the `gh issue` equivalents) accept `--attach <image>`. GitHub's own attachment upload doesn't accept the workspace's GitHub App credential, so Replicas uploads the image as [media](https://docs.replicas.dev/features/cli.md#media) and puts its link in the body. The link is unguessable but public: anyone who has it can view the image, including in private repositories. Images only; turn recordings into GIFs.

### Graphite Pull Request Links

Enable **Open pull requests in Graphite** in **Personal → Preferences** to open GitHub pull requests in Graphite instead of GitHub. This turns **Open on GitHub** in the web and mobile apps into **Open in Graphite**, and Slack follow-ups and merged or closed PR notifications use Graphite links. In the app, pull request links still open the Replicas review first. Replicas continues to track the canonical GitHub URL, and GitLab merge request links are unchanged.

[Graphite merge queues](https://graphite.com/docs/merge-queue-optimizations) close PRs on GitHub after landing them, and Replicas counts those PRs as merged. For other tools that close PRs after merging them, apply the `externally-merged` label. Replicas counts closed PRs with this label as merged in [Analytics](https://docs.replicas.dev/admin/analytics.md). Adding the label after closure also corrects the tracked outcome.

### Branch Rules

Merging from Replicas follows the base branch's protection and [rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). **Merge** is the main action unless GitHub is waiting on a review, when **Approve** leads instead. Hover a disabled merge button to see what's missing, such as **Requires 1 approving review** or a failed required check. Replicas offers only the merge methods the repository and branch allow, starting with your default on GitHub. When the repository allows [auto-merge](https://docs.github.com/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request), **Enable auto-merge** merges the pull request once its requirements pass.

If GitHub lets you bypass the branch's rules, a blocked pull request shows **Bypass rules and merge**. Replicas merges it right away with your connected GitHub account, skipping any merge queue. When **Enable auto-merge** is the main action, the bypass is in the **⋯** menu.

### GitHub Merge Queues

When a branch requires a [merge queue](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue), the merge button reads **Add to merge queue**. GitHub merges it with the queue's merge method once the queue's checks pass.

Adding to a merge queue needs the Replicas GitHub App's **Merge queues** permission. If GitHub asks your organization to approve an updated permission for the app, an organization owner approves it under **Settings > GitHub Apps**.

### Stacked Pull Requests

When GitHub pull requests in a workspace belong to a stack, the workspace header groups them in stack order and shows their shared base branch. Open each pull request from the stack view to review it in Replicas, and merge it on GitHub. Replicas disables the direct workspace merge action for stacked pull requests because the stack must be merged in order.

### Context

For **issues**, the context includes:

* Issue number, title, and description
* Your comment body

For **pull requests**, the context includes:

* PR number and branch
* Your comment or review body
* Review state (approved, changes requested, etc.)
* File path and diff hunk (for line comments)

## Intended Usage

Use GitHub Issues to:

* Start new features or bug fixes directly from issue tracking
* Get implementation plans before code changes
* Track work from issue to PR automatically

Use GitHub PRs to:

* Request changes on PRs
* Comment on specific lines
* Ask for fixes or improvements

Start your comment with `/plan` to request a planning-only response with a plan link. See [Plan Mode](https://docs.replicas.dev/features/workspaces/plan-mode.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.