Connect GitHub — repos, agents, and auto-PRs

Link your GitHub account once and your agents can genuinely work on your repositories: each assigned agent runs inside its own checkout of the repo, and — if you want — its finished work is committed, pushed, and opened as a pull request automatically.

Connect your account

1. Open Settings → GitHub and click Connect GitHub.
2. Your browser opens github.com’s device sign-in; the app shows an 8-character code. Enter it, click Authorize, and you’re done — the tab shows your GitHub avatar and username.

No password ever touches the app: this is GitHub’s device sign-in, and the resulting access token is encrypted on your machine and used only by the app’s native core. Disconnect forgets it instantly.

The built-in connection is a GitHub App — fine-grained by design: the token can only reach repositories where the app is installed, with only the permissions the app declares (repo contents and pull requests). Two consequences worth knowing:

• Install the app on your account (your app page → Install App; “All repositories” is the smoothest) — if the repo list comes up empty after connecting, that’s the reason, and the tab says so.
• Short-lived tokens are handled for you: when the app is set to expire user tokens (GitHub’s default), Mastery HQ refreshes them silently in the background. Prefer zero moving parts? Untick “Expire user authorization tokens” in the GitHub App’s settings.

Bringing your own Client ID still works (Settings → GitHub → Change Client ID) — a GitHub App id or a classic OAuth App id are both accepted.

Browse and create repositories

Once connected, the same tab lists every repository you can access (searchable, with private and read-only badges). New creates a repository right there — name, optional description, private by default.

Repo creation under a GitHub App connection needs one extra permission on the app: Administration: Read & write (and an “All repositories” installation so the new repo is reachable). Without it, GitHub declines the create with a clear error — browsing and agent work are unaffected.

Assign a repo to an agent

Every agent window gets a small ⎇ Assign repo chip above its input bar. Click it, search, pick a repo — that agent now works inside its own checkout of it:

• The first assignment clones the repo into the app’s managed folder and prepares a private git worktree on a branch named mastery/<agent-name>.
• From then on, everything the agent does — reading code, editing files, running commands — happens inside that worktree.
• The chip shows the assigned repo; click it again to switch or unassign.

Prefer talking? All of this works by voice or from Hermes:

• “assign the repo masteryhq-landing to Alex”
• “put Bo on infra-ops”
• “have Alex work on the fortress repo”
• “create a private repo called billing-service”

Bare phrases work too — “assign masteryhq-landing to Alex” checks your Sprint Board cards first, then falls back to repo names. Spoken names are matched loosely, so “mastery hq landing” finds masteryhq-landing.

Keep repos maintained — the policy

Settings → GitHub → Repo maintenance decides what happens after an assigned agent finishes a run:

Policy	What happens
Manual (default)	Nothing automatic — review the agent’s worktree and push yourself.
Commit & push the agent’s branch	Changes are committed and pushed to mastery/<agent-name>.
Commit, push & open a pull request	As above, plus a PR into your default branch is opened (or updated) for you to review and merge.

Sync before each run (on by default) fast-forwards the agent’s checkout to your latest default branch before it starts, so agents work on current code. It never merges over local work — a diverged branch is left alone.

After a push you’ll see a ⎇ Pushed to owner/repo · PR #N line in the agent’s transcript, and every push and PR is written to the Audit Log.

Guardrails

• Agents push only their own mastery/<name> branch — never your default branch, never a force-push.
• Merging is always yours: the PR waits on GitHub for your review.
• The access token is DPAPI-encrypted at rest, masked by Streaming Mode’s secret redaction, and never written into any git config.