Using GitHub as a Tool or Trigger

Connect GitHub to let your Cosmos Experts work with repositories, pull requests, and issues. Use the GitHub API tools during a session, or create an automation that starts an Expert when a PR, push, CI failure, or comment arrives.

Prerequisites

Choose a connection based on the identity your Expert should use:

Connection	Capability	Identity	When to use
GitHub App	`GITHUB_APP`	Augment’s bot identity	Expert posts as Augment — acts as a tenant-wide bot identity across every repository in your organization
GitHub personal OAuth	`GITHUB`	The session owner’s GitHub identity	Expert acts as the human user who triggered it — e.g. a personal review Expert running under your own credentials

Connect the GitHub App

A Cosmos tenant admin must set up the team connection. The installer also needs permission to install the App on the target GitHub organization.

Open Settings → Connectors → Browse Connectors and search for GitHub.
Select the GitHub App connector and click Add installation. If GitHub Enterprise Cloud configuration is also shown, choose Add GitHub.com installation.
Complete the GitHub installation flow for the Augment Code GitHub App and select the repositories it can access.
Return to the connector page and click Refresh to check the installation and repository list.

Installing the App does not automatically grant access to every repository. To change repository access later, open the installation’s actions menu (3 dots) on the connector page, choose Open on GitHub, and update the repository selection there.

Connect your personal GitHub account

Open Settings → Personal → Linked Accounts.
On the GitHub card, click Connect and complete the OAuth flow.

The App and personal connections are separate and can coexist. Connecting your personal account does not replace the App installation needed for GitHub automations. For self-hosted GitHub, see GitHub Enterprise Server.

Enabling GitHub as a Tool on an Expert

Open Settings > Experts, select your Expert, and edit it.
In Tools → Integrations, turn off Automatically include all managed integrations if you want to choose specific integrations.
Select GitHub App for the shared bot connection, or the personal GitHub integration to act as the session owner.
Save the Expert.

The selected integration determines authentication and the tool name:

GitHub App → github-app-api, authenticated with the GitHub App installation token
Personal GitHub → github-api, authenticated with the session owner’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

You shouldn’t manually edit triggers. Always use Cosmos Advisor for that.

Connect the GitHub App and save an Expert with the GitHub App integration before creating a trigger.

Open Settings > Automations and click Create automation.
Select the existing Expert you want to run.
Choose GitHub as the Trigger source and enter a Trigger name.
Select an Event using a GitHub webhook event name from the list below. If the event is not a preset, choose Custom event type and enter its name, such as issue_comment.
Optionally add a Filter — a JSONLogic expression evaluated against the raw GitHub webhook payload. The trigger fires only when the filter returns true.
Click Save.

To add another trigger to the same Expert, open Settings > Automations, expand its automation, and click Add trigger. See Configuring Triggers for permissions and other trigger settings. 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. Open Settings > Automations → Event Log tab, filter by GitHub, and use Advanced Filter to select the event type. Inspect a captured payload to confirm your field paths and filter before saving the trigger.

Disabling GitHub Access

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

Pause or remove a trigger. Open Settings > Automations, select the automation, and use its Triggers controls to disable or remove the trigger. The Expert keeps its GitHub API tool.
Remove GitHub from an Expert. Disable or remove its GitHub triggers first. Open Settings > Experts and edit the Expert. Under Tools → Integrations, turn off Automatically include all managed integrations if enabled, deselect the GitHub integration, and save.
Remove a connection. For personal OAuth, click Disconnect on the GitHub card in Settings → Personal → Linked Accounts. For the team App, open Settings → Connectors, select GitHub App, and use the installation’s actions menu to Open on GitHub and uninstall the App. An admin can also choose Remove installation and complete the confirmation. Removing an installation affects every Expert and automation that relies on it.

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

Using GitHub as a Tool or Trigger

Prerequisites

Connect the GitHub App

Connect your personal GitHub account

Enabling GitHub as a Tool on an Expert

Configuring GitHub Triggers

PRs Ready for Review

Push to main

Slash Command in a PR or Issue Comment

Workflow Failure on main

Common Filter Recipes

Disabling GitHub Access

​Prerequisites

​Connect the GitHub App

​Connect your personal GitHub account

​Enabling GitHub as a Tool on an Expert

​Configuring GitHub Triggers

​PRs Ready for Review

​Push to main

​Slash Command in a PR or Issue Comment

​Workflow Failure on main

​Common Filter Recipes

​Disabling GitHub Access

Prerequisites

Connect the GitHub App

Connect your personal GitHub account

Enabling GitHub as a Tool on an Expert

Configuring GitHub Triggers

PRs Ready for Review

Push to main

Slash Command in a PR or Issue Comment

Workflow Failure on main

Common Filter Recipes

Disabling GitHub Access