# GitHub

> Install the Ace GitHub App so Ace can read recent code changes, deploys and CI runs during investigations and, after approval, open fix and revert pull requests or roll back a deploy.

Source: https://tryace.dev/docs/integrations/github

Ace uses GitHub to tie an incident to the code change or deploy that caused it, and you connect it by installing the Ace GitHub App on the repositories you choose.

| | |
| --- | --- |
| Category | Recent code changes, deploys and CI context |
| Ace reads | Commits, diffs, pull requests, file contents, code search, workflow runs, job logs, check annotations, deployments |
| Ace can change | Opens fix and revert pull requests, and runs your deploy workflow to roll back or redeploy, after approval or under your action policy |
| Opens incidents | No |
| Setup | GitHub App |

## What Ace reads

During an investigation, Ace reads these from the repositories mapped to the incident's workload:

- Commits, commit patches, comparisons between revisions, and the pull requests for a commit.
- File contents and code search results.
- GitHub Actions workflow runs, jobs, the tail of job logs and check annotations.
- Deployments and their status.

Ace records each deployment status on a mapped repository as a change on that workload, and a successful deploy updates the workload's open incidents.

## What Ace can change

| Action | What it does | Can be undone |
| --- | --- | --- |
| Fix pull request | Opens a pull request with a code or configuration fix | Yes |
| Revert pull request | Opens a pull request that reverts a change | Yes |
| Roll back deploy | Runs your deploy workflow at an earlier revision | Yes |
| Redeploy | Runs your deploy workflow again at the current revision, with no code change | No |

Ace proposes these on the incident, and each one runs only after a person approves the exact plan or when your action policy lets it run automatically for that workload. See [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals).

Your team merges the pull requests a person approved. Ace merges its own pull request only when the action ran under an automatic policy with **Auto-merge pull requests** on, every Ace reviewer passed, checks are green and Ace announced the merge in Slack first, which gives anyone the chance to stop it.

**Roll back deploy** and **Redeploy** need a deploy workflow for the workload, which you connect under **Rollback workflow** in **Settings** > **Actions**. The repository must be mapped to the workload, and the workflow must be active and deploy to an existing GitHub environment.

## What opens an incident

GitHub doesn't open incidents. CI failures and deploys add evidence to incidents that other sources open.

## Before you start

- The **admin** role in Ace.
- Permission to install GitHub Apps on the account or organization, which means an organization owner, or a repository admin if your organization allows it.
- One GitHub App installation per Ace workspace.

## Credentials and permissions

Ace uses a GitHub App and never a personal access token or an OAuth user token, so access doesn't depend on any one person's account. You choose which repositories the app can see, and GitHub lists its permissions on the install page before you approve.

The Ace GitHub App gets read-only access to the repositories you choose, and Ace opens pull requests and runs your deploy workflow only for the approved actions above.

## Set up

1. In Ace, go to **Settings** > **Data sources** > **GitHub**.
2. Under **Install the Ace GitHub App**, choose **Install GitHub App**. GitHub opens in a new tab.
3. Choose the account or organization, then **All repositories** or **Only select repositories**.
4. Review the permissions and choose **Install**. GitHub returns you to Ace, which shows **GitHub App connected**.
5. In each workload's settings, map its repositories under **Code context**. Only workspace admins can change these mappings.
6. Optional: for each workload you want Ace to roll back, set up a **Rollback workflow** in **Settings** > **Actions**.

## Confirm it's working

- The GitHub panel shows the connected account and the number of repositories with access.
- **Repositories with access** lists each repository with its visibility and default branch.
- If it shows **No repositories with access yet.**, choose **Add repositories on GitHub** and select repositories in the installation settings.

## Disconnect

In Ace, choose **Disconnect** in **Settings** > **Data sources** > **GitHub**. Ace deletes the connection and its repository mappings, but the app stays installed on GitHub.

To change access in GitHub, choose **Manage on GitHub** in Ace, or open your account or organization settings > **GitHub Apps**, and then do one of these:

- **Uninstall** the app to remove all access. Ace deletes the connection and mappings when GitHub reports it.
- **Suspend** the app to pause access. Ace marks the connection suspended until you unsuspend it.
- Remove single repositories from the installation. Ace drops them and their mappings.

## Next steps

- [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals): approval, automatic policies and undo.
- [How Ace works](https://tryace.dev/docs/concepts/how-ace-works): how code fits into an investigation.
- [Ace MCP server](https://tryace.dev/docs/mcp): give your coding agent the same incident details.