Setting Up the GitHub Connector

Path: Connectors → GitHub → Configuration

What this connector does

The GitHub connector lets agents work on your code the way a developer would. It does two things with one set of credentials:

• A signed-in workspace on your worker. When an AI step has the GitHub connector, Wazzi signs git and the GitHub CLI (gh) in before the step starts and gives it an empty folder of its own. The agent can clone a repository, make a change, run your type checks and tests, commit, push a branch, and open a pull request — like a developer at a terminal. The folder is deleted when the step ends.
• MCP tools for steps that don't need a checkout — opening, reading, merging and closing pull requests, merging one branch into another, and checking CI. That's what a "ship it" agent uses.

Wazzi authenticates as a bot account — a GitHub user you create for your agents (for example acme-agent) and add to your repositories. Everything agents do shows as that account: commits, pushes, pull requests and comments. The token is handed to the workspace directly; it never appears in the agent's prompt or in run logs.

The connector exposes 12 tools:

• Account (2 tools) — get_status (who the connector acts as, and which repositories it may touch), list_repositories.
• Pull requests (6 tools) — list_pull_requests, get_pull_request, create_pull_request, update_pull_request (including draft ↔ ready for review), merge_pull_request, add_comment.
• Branches & CI (3 tools) — merge_branch (e.g. an agent branch into staging, no PR needed), delete_branch (refuses the default branch), get_checks.
• Universal escape hatch (1 tool) — github_api for any other GitHub REST endpoint.

Before you start — the bot account and its token

1. Create the bot account. Sign up at github.com/signup with an address you can receive email at (GitHub allows one free machine account per person). If signup is blocked, use a plain address rather than a + alias and try from a different network.

2. Add it to your repositories. As a repository admin, open each repository's Settings → Collaborators (or your organization's team settings), click Add people, and give the bot Write access. Then sign in as the bot and accept each invitation — until it accepts, it can't reach the repository.

[Screenshot placeholder: repository Settings → Collaborators → Add people]

3. Create a classic personal access token. Signed in as the bot, go to Settings → Developer settings → Personal access tokens → Tokens (classic) and click Generate new token (classic).

• Note: something like Wazzi agents.
• Expiration: pick a date — GitHub emails the bot's address before it expires.
• Scopes: tick repo. Nothing else is needed.

Copy the token straight away — it starts with ghp_ and is only shown once.

[Screenshot placeholder: New personal access token (classic) with the repo scope ticked]

Why classic and not fine-grained? GitHub's fine-grained tokens can't reach repositories the account only collaborates on — and a bot account owns nothing. A classic token can only reach the repositories the bot has been added to, and the connector's Allowed Repositories narrows that further.

What this connector unlocks for your team

• "Pick up ENG-142, fix it on a branch, run the tests, and open a pull request into staging."
• "Every morning, check the open agent PRs and tell me which have failing checks."
• "Merge agent/eng-142-fix-totals into staging."
• "Open a PR from that branch into main and mark it ready for review."
• "Close the PR and delete the branch — we're not shipping this one."

Paired with the Linear connector and an on-completion decision in Slack, that becomes a full loop: an agent picks up an issue, fixes it, opens a PR, and asks a human whether to ship it.

Steps — configuring GitHub in Wazzi

1. From the Connectors catalog, click Configure on the GitHub tile.

You'll land on GitHub's Configuration tab:

2. Fill in the fields.

• Allowed Repositories — owner/repo, one per line (e.g. acme/web). Agents and tools can only touch these. Leave it blank to allow everything the bot can reach.
• Access Token — the bot's ghp_… token. Stored encrypted at rest in Wazzi.

3. Click Test Connection.

Wazzi checks who the token belongs to and that it can reach every allowed repository. On success the green Connected banner appears at the top of the page, and the health check records e.g. "Connected as acme-agent (4 repos)".

4. Click Save Configuration.

GitHub moves to the Active section of the catalog. Switch on Agents for the connector, then add it to any AI step that should work on code.

Troubleshooting

• "Connected as … but it can't reach: owner/repo." The bot hasn't been added to that repository, or hasn't accepted the invitation yet. Add it under the repository's Collaborators settings and accept the invite as the bot.
• "401 Bad credentials." The token is wrong, expired or revoked. Generate a new classic token as the bot and paste it in.
• "Repository … is not in this connector's allowed repositories." The agent tried a repository outside Allowed Repositories. Add it to the list if that's intended.
• "… is the default branch; not deleting it." delete_branch never deletes a repository's default branch.
• Merge refused with a reason about reviews or checks. Branch protection is working as intended — the PR needs the approvals or green checks your rules require.
• gh pr create says the branch must be pushed first. In a shallow clone, gh can't tell the branch was pushed. Pass --head <branch> --base <base> explicitly — agents are already told to.

Best practices

• Protect your main branches. A collaborator with Write access can push to any branch. Agents are told to push only to their own branches (e.g. agent/eng-142-…), but branch protection is what enforces it. On private repositories, branch protection needs a paid GitHub plan.
• Use Allowed Repositories even when the bot only has access to a few — it keeps tools and agent prompts focused on the repositories you meant.
• Gate shipping with a decision. Have the agent open a PR and raise an on-completion decision in Slack; only an approval starts the agent that merges.
• Set an expiry on the token and rotate it. GitHub warns the bot's email address before it lapses.
• Grant merge and delete tools sparingly — see Managing Permissions.

Frequently asked questions

Where does the agent's code run?
On your organization's own worker. Each AI step gets an empty folder that is deleted when the step ends, so nothing is shared between runs.

Can the agent see the token?
It isn't in the prompt or the logs. It is available to git and gh inside the step's workspace, which is how they sign in — so give the bot access only to the repositories agents should work on.

Does Wazzi store the token in plaintext?
No. It is encrypted at rest with per-org keys and only decrypted when a step or tool needs it.

Who do commits show as?
The bot account, using its GitHub no-reply email address so commits link to its profile.

Can I use a GitHub App instead of a bot account?
Not yet. File a feature request if your organization needs it.

What's next

• Give agents an issue queue: Setting Up the Linear Connector.
• Restrict who can merge and delete: Managing Permissions.
• Browse other connectors: Browsing the Connectors Catalog.