GitHub

Early access. GitHub and Slack runs start in a cloud sandbox operated by Mutagent, and cloud sandboxes are not open to every account yet: we are letting accounts in gradually while we test. There is nothing to host, and nobody has to be at a terminal.

GitHub plays two parts in Mutagent:

	What it does	How it authenticates	Status
Apply target	Helix, on your machine, ships every approved fix as a pull request on your repository.	Your own git credentials (the `gh` or SSH setup you already push with)	Available
Channel	The Mutagent GitHub App lets an issue, a mention or a failed CI run start a Helix run in a cloud sandbox. A run started from an issue posts its result back as a comment.	A GitHub App you install on the repositories you choose	Early access

Ship fixes as pull requests

Helix never writes to your default branch. When Optimize applies a remedy you approved, Helix prepares the change on a branch and opens a pull request with the diff. Markdown agents apply as file edits; code agents apply as a code change. Your merge is the final approval. Point a target at the repository and say how fixes apply. A local target uses the checkout you already have; a remote target clones from repo_url:

.mutagent/config.yaml

config_version: "0.4.0"
global:
  workspace:
    repo: your-org/your-repo
    path: .

  targets:
    - name: local-agents
      platform: local-claude        # Claude Code markdown agents
      mode: local                   # local = use this checkout · remote = clone repo_url
      root: .claude/agents          # where the agent files live
      apply:
        kind: markdown              # markdown agent files → pull request

platform selects the coding agent or framework, root scopes where fixes are written, and apply.kind is markdown for agent files or code-pr for a code change. See the config reference and apply targets. Local targets use your existing git credentials. Remote targets clone over repo_url with the credential named by credential_ref (the name of an environment variable, never the secret itself). Helix needs read access to evaluate and write access to open the pull request branch.

Start runs from GitHub

With the GitHub channel, GitHub events start Helix runs in a cloud sandbox. A run started from an issue or an issue comment reports back on that issue. Every run, including one started by a failed CI run, is listed in mutagent gateway runs.

Before you start

The mutagent CLI is installed, you are signed in, and a workspace is selected. See Sign in.
Cloud sandboxes are enabled for your account (early access).
A person who can install GitHub Apps on the account or organization that owns the repositories is at a browser. That step cannot be done from the CLI.

Connect

A person connects GitHub once for the organization, in a browser. There are three places to start:

When you sign up in the web app, at the Connect GitHub step. You can skip it and connect later.
In the web app, under Configuration › Integrations: click Connect on the GitHub card.
From the CLI:
mutagent gateway connect github --json
The command prints two links and exits 0. Open the sign-in link (data.signInUrl) first and sign in to Mutagent, then open the second link (data.url) in the same browser. Then wait for it to finish:
mutagent gateway connect github --wait --attempt <attempt-id> --json
<attempt-id> is data.attempt from the first command. Running connect again once GitHub is connected does nothing and exits 0.

Whichever you start from, you install the Mutagent GitHub App on GitHub and choose its repository access there: All repositories or Only select repositories.

Check that it worked

mutagent gateway status --json
mutagent gateway doctor --json

status shows what is connected in data.connections and the next command to run in next. doctor exits 0 when every check passes, and 1 with GATEWAY_CHECKS_FAILED and the fix for each failing check otherwise. To prove a run end to end, run mutagent gateway test-run --repo <owner/name> --wait --json. The full connect flow, including why signing in with GitHub does not install the app and what to do when a step fails, is in Connecting GitHub and Slack.

Which repositories you can use

The repositories Mutagent can work on are exactly the ones you give the Mutagent GitHub App access to on GitHub. There is no separate list to keep in Mutagent: a repository is linked to your workspace automatically the first time you use it, when you start a session on it in the web app, create a trigger or routine for it with --repo, or pick it for a Slack mention.

mutagent gateway repos            # every repository the app can reach
mutagent gateway repos --linked   # the ones this workspace has linked, by hand or by use

To add or remove repositories, change the app’s access on GitHub. mutagent gateway repos grant-more prints the GitHub page where you do that. A repository the app cannot reach is refused with REPOSITORY_INACCESSIBLE, with the instruction to give the app access to it on GitHub first. Linking by hand with mutagent gateway repos link your-org/your-repo is optional. mutagent gateway repos unlink your-org/your-repo keeps a repository out of the ones a Slack mention chooses from, and pauses the triggers and routines that run on it. See Repositories.

What the app can do

Read the repositories you granted, to check them out into the run’s sandbox. Each run gets a short-lived, read-only token for one repository.
Comment on the issue that started the run, with the run’s result.

You choose the repositories at install time and can change them later on GitHub.

What starts a run

Event	How it is set up
A mention of the app in an issue or an issue comment	Built in: on for every repository the app can reach
A new issue	A trigger you create for a repository
A failed CI run	A trigger you create for a repository
A schedule (for example weekdays at 09:00)	A routine you create, for a repository or for none

Mentions on pull requests do not start a run. There is no default repository: each trigger and routine names its repository when you create it. For example, a trigger that triages every new issue:

mutagent gateway triggers create --on github.issue.opened --repo <owner/name> \
  --instruction "Triage: label, estimate, ask one clarifying question if needed" --json

Mentions are built in, so --on github.mention is refused (TRIGGER_KIND_BUILTIN_ONLY). A failed CI run uses --on github.ci-failed. Each trigger and routine carries the instruction Helix receives when it fires. To create them, see Triggers and routines and the mutagent gateway commands. Run history, like everything the gateway stores, is kept for 90 days.

For runs on Helix Cloud, see Managed agents.

Integrations

Trace Sources

Apply Targets

General-purpose

Cloud Deployment

Ship fixes as pull requests

Start runs from GitHub

Before you start

Connect

Check that it worked

Which repositories you can use

What the app can do

What starts a run

​Ship fixes as pull requests

​Start runs from GitHub

​Before you start

​Connect

​Check that it worked

​Which repositories you can use

​What the app can do

​What starts a run

Ship fixes as pull requests

Start runs from GitHub

Before you start

Connect

Check that it worked

Which repositories you can use

What the app can do

What starts a run