Skip to main content

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.

Wire your Cosmos Experts up to GitHub to listen for repository activity — a new PR, a push to main, a CI failure, or a slash command in a comment — and to read and update GitHub data through a built-in REST API tool.

​
Prerequisites

GitHub has two integration flavors. Pick the one that matches how your Expert should act:
FlavorCapabilityWhen to use
GitHub App (org install)GITHUB_APPExpert posts as Augment — acts as a tenant-wide bot identity across every repository in your organization
GitHub user OAuthGITHUBExpert 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. You can connect both — GITHUB_APP and GITHUB are independent, and different Experts in the same tenant can use either.

​
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. Cosmos automatically wires up a GitHub API tool — a REST-style wrapper around api.github.com — with no further setup required. 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: 
{
  "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.
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.

​
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 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: 
{"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: 
{"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: 
{"and": [
  {"==": [{"var": "action"}, "created"]},
  {"in": ["/augment ", {"var": "comment.body"}]},
  {"!": [{"==": [{"var": "comment.user.type"}, "Bot"]}]}
]}
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.

​
Workflow Failure on main

Pick Event type workflow_run and filter on the conclusion and branch: 
{"and": [
  {"==": [{"var": "action"}, "completed"]},
  {"==": [{"var": "workflow_run.conclusion"}, "failure"]},
  {"==": [{"var": "workflow_run.head_branch"}, "main"]}
]}

​
Common Filter Recipes

// 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]"]}]}
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.

​
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.