Skip to content
Metaphor
Esc
↑↓navigate↵open⌘Jpreview
On this page

GitHub

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

Connect GitHub

Connect GitHub from Metaphor or the web dashboard.

Choose repository access

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

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.

Pull requests

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

With 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, 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.

Was this page helpful?