> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Connect a repository so Helix can read agent code and ship approved fixes as pull requests.

GitHub is Helix's transport for your agent's source. It reads your agent from a repo and ships every
approved fix back as a **pull request** — it never writes to your default branch.

## What Helix does with your repo

* **Reads the subject.** Helix resolves the agent it's working on from the repo — harness markdown
  (e.g. `.claude/agents/*.md`) or agent code — so Spec, Build, and Evaluate reason over the real
  definition, not a copy.
* **Writes via PR only.** When Optimize applies an approved remedy, Helix prepares the change on a
  branch and opens a pull request with the diff. Markdown targets apply as file edits; code targets
  apply as a code change. Review and merge on GitHub — the apply gate is your merge.

<Note>
  Every apply is **approval-gated**. Helix proposes; GitHub is where you accept. Nothing lands on
  your default branch without your merge.
</Note>

## Configure it

Point a target at the repo and how fixes apply. A `local` target uses a checkout you already have; a
`remote` target clones from `repo_url`:

```yaml .mutagent/config.yaml theme={null}
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 → PR
```

`platform` selects the harness or framework; `root` scopes where fixes are written; `apply.kind` is
`markdown` for agent files or `code-pr` for a code change. See the
[config reference](/helix/reference/config#globaltargets) for every key, and
[apply targets](/integrations/targets/harness) for the harness vs code split.

## Authentication

Local targets use your existing git credentials — the same `gh`/ssh setup you push with. Remote
targets clone over `repo_url` using the credential named by `credential_ref` (an env-var name, never
the secret itself). Helix needs only read access to evaluate and write access to open the PR branch.

<Tip>
  For the hosted loop, GitHub is also how Managed Agents reaches your code. See
  [Managed Agents](/platform/agents/overview).
</Tip>