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

# Using GitHub as a Tool or Trigger

> Configure GitHub triggers and the GitHub API tool on your Cosmos Experts — listen for PRs, pushes, CI failures, and slash commands.

GitHub is the integration most teams reach for first. Wire it up and your Expert can wake on PRs, pushes, CI failures, or slash commands, and call back into the GitHub REST API from inside the session.

## Prerequisites

GitHub has two integration flavors. Pick the one that matches how your Expert should act:

| Flavor                       | Capability   | When to use                                                                                                       |
| ---------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| **GitHub App (org install)** | `GITHUB_APP` | Expert posts as Augment — acts as a tenant-wide bot identity across every repository in your organization         |
| **GitHub user OAuth**        | `GITHUB`     | Expert acts as the human user who triggered it — e.g. a personal review Expert running under your own credentials |

To connect a team-wide install:

1. Go to **Configuration → Integrations** in the sidebar.
2. On the **GitHub** tile, click **Connect**.
3. Authorize the Augment Code GitHub App and pick which repositories it can access.

To connect personal GitHub OAuth (so a session can act as you):

1. Open **My settings → Integrations** from the user menu.
2. On the **GitHub** card, click **Connect** and complete the OAuth flow.

To remove a connection later, click **Disconnect** on the corresponding tile. To remove a GitHub App install entirely, uninstall the Augment Code GitHub App from **GitHub → Organization Settings → Applications**.

Both can coexist. `GITHUB_APP` and `GITHUB` are independent capabilities, and different Experts in the same tenant can pick whichever fits.

## Enabling GitHub as a Tool on an Expert

In the Expert editor, the **Capabilities** section lists every capability you can grant the Expert. Toggle on **GitHub App** (or **GitHub** for per-user) and save. Saving adds a `github-app-api` (or `github-api`) tool to the Expert — a thin wrapper around `api.github.com`. Nothing else to configure.

The capability mode determines authentication and the tool name:

* **GitHub App** → tool name **`github-app-api`**, signed with the org-level GitHub App installation token
* **GitHub** → tool name **`github-api`**, signed with the invoking user's OAuth token

Both tools accept the same input shape:

```json theme={null}
{
  "path": "/repos/{owner}/{repo}/pulls/{number}/reviews",
  "method": "POST",
  "data": { "body": "LGTM", "event": "APPROVE" },
  "summary": "Approve PR #1234"
}
```

`method` defaults to `GET`. `summary` is required and surfaces in run logs and the Expert UI. Set `details: true` to receive the full GitHub response payload instead of the trimmed default.

<Note>GitHub's `/issues` endpoints return both issues **and** pull requests. Filter on `pull_request != null` in the response if you only want one or the other.</Note>

## Configuring GitHub Triggers

GitHub triggers are added from the **Triggers** section of the Expert editor. Pick **GitHub** as the trigger type, set **Event type** to a GitHub webhook event name, and (optionally) write a **Filter** — a [JSONLogic](https://jsonlogic.com) expression evaluated against the raw GitHub webhook payload. The trigger fires only when the filter returns true.

Top-level keys available to filter on vary by event type, but commonly include: `action`, `repository`, `sender`, `pull_request`, `issue`, `comment`, `ref`, `head_commit`, `workflow_run`, `installation`.

**Available event types:**

* **Pull requests**: `pull_request`, `pull_request_review`, `pull_request_review_comment`
* **Issues**: `issues`, `issue_comment`
* **Code**: `push`
* **CI / checks**: `check_suite`, `status`, `workflow_run`, `workflow_job`, `workflow_dispatch`

### PRs Ready for Review

Pick **Event type** `pull_request` and use this filter to fire on direct opens of non-draft PRs and on `ready_for_review` transitions out of draft:

```json theme={null}
{"or": [
  {"==": [{"var": "action"}, "ready_for_review"]},
  {"and": [
    {"==": [{"var": "action"}, "opened"]},
    {"==": [{"var": "pull_request.draft"}, false]}
  ]}
]}
```

### Push to main

Pick **Event type** `push` and filter on the ref and repository:

```json theme={null}
{"and": [
  {"==": [{"var": "ref"}, "refs/heads/main"]},
  {"==": [{"var": "repository.full_name"}, "myorg/myrepo"]}
]}
```

### Slash Command in a PR or Issue Comment

To match `/augment <something>` in a comment, pick **Event type** `issue_comment` and filter:

```json theme={null}
{"and": [
  {"==": [{"var": "action"}, "created"]},
  {"in": ["/augment ", {"var": "comment.body"}]},
  {"!": [{"==": [{"var": "comment.user.type"}, "Bot"]}]}
]}
```

<Warning>The bot-type guard is critical here. If your Expert posts comments back via the GitHub API tool, those comments will themselves be delivered as `issue_comment` events — without the filter you'll create a feedback loop.</Warning>

### Workflow Failure on main

Pick **Event type** `workflow_run` and filter on the conclusion and branch:

```json theme={null}
{"and": [
  {"==": [{"var": "action"}, "completed"]},
  {"==": [{"var": "workflow_run.conclusion"}, "failure"]},
  {"==": [{"var": "workflow_run.head_branch"}, "main"]}
]}
```

### Common Filter Recipes

```json theme={null}
// Action filtering
{"==": [{"var": "action"}, "opened"]}
{"in": [{"var": "action"}, ["opened", "reopened", "synchronize"]]}

// Repository / org scoping
{"==": [{"var": "repository.full_name"}, "myorg/myrepo"]}
{"==": [{"var": "repository.owner.login"}, "myorg"]}

// Branch and ref scoping
{"==": [{"var": "ref"}, "refs/heads/main"]}
{"==": [{"var": "pull_request.base.ref"}, "main"]}

// Label match (pull_request.labels is an array of objects)
{"some": [{"var": "pull_request.labels"}, {"==": [{"var": "name"}, "needs-review"]}]}

// Skip events authored by the Augment bot (avoid feedback loops)
{"!": [{"==": [{"var": "sender.login"}, "augment-app[bot]"]}]}
```

<Tip>A typo like `pulll_request.draft` silently never matches and the trigger will look broken. To test a filter against real GitHub events, go to **Configuration → Events log**, filter by source = GitHub and the event type you care about, and inspect the payload before saving the trigger.</Tip>

## Disabling GitHub Access

You can scale back GitHub access at three levels, from least to most disruptive:

1. **Remove a single trigger.** Delete the trigger row from the Expert editor and save. The Expert keeps the GitHub API tool but no longer wakes up on that event.
2. **Remove the GitHub capability.** Toggle off **GitHub App** (or **GitHub**) in the Expert's **Capabilities** section. The Expert loses the GitHub API tool and any remaining GitHub triggers will be rejected when you save.
3. **Disconnect the integration.** From **Configuration → Integrations**, click **Disconnect** on the **GitHub** tile. For a GitHub App install, also uninstall the Augment Code app from **GitHub → Organization Settings → Applications**. This revokes the token for every Expert in the tenant using that capability.