---
title: GitHub

sidebar:
  label: GitHub
  order: 0
---

Metaphor connects to GitHub through a **GitHub App**.

Install the app for the organizations and repositories you want to use with Metaphor. Once connected, those repositories become available when creating a task.

## What the GitHub App does

With the GitHub App installed, Metaphor can:

- Access repositories you choose
- Clone repositories for tasks
- Push task branches
- Create and update pull requests
- Read pull request comments so agents can respond to review feedback

Repository access is limited to the organizations and repositories you grant to the GitHub App.

## Install the GitHub App

1. **Connect GitHub**

    Connect GitHub from Metaphor or the web dashboard.

2. **Choose repository access**

    GitHub asks which organizations and repositories Metaphor can access. Select
    the repositories you want to use with Metaphor.

3. **Return to Metaphor**

    Once the installation is connected, those repositories become available
    when creating a task.

You can update repository access later from your GitHub App settings.

## Repository permissions

You can give Metaphor access to specific repositories instead of every repository in an organization.

If access to a repository is removed, Metaphor can no longer start new work or perform GitHub operations for that repository.

:::note
Metaphor only has access to repositories granted through the GitHub App. You can change or revoke that access from GitHub at any time.
:::

## Pull requests

Metaphor uses the GitHub integration to create and update pull requests as tasks move through their workflow.

With [Handoff](/handoff) on, Metaphor verifies the work, commits and pushes the changes, and creates the pull request for you.

With Handoff off, you decide when the changes are ready. When you choose **Commit & Push**, Metaphor pushes the changes and creates the pull request.

## Pull request feedback

Pull request feedback can become part of the task.

When a teammate or review tool leaves feedback on a pull request, Metaphor can send the relevant comments back to an agent so it can continue working on the changes.

The agent continues from the task's existing [worktree](/worktree), so the work stays with the same task.

## Troubleshooting

**Repositories don't appear**

Make sure the GitHub App is installed for the organization that owns the repository and that the repository is included in its access.

**A pull request can't be created**

Check that Metaphor still has access to the repository and that the GitHub App installation has the required permissions.

**Connected the wrong account**

Make sure you're signed in with the GitHub account associated with the installation you want to use.