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

# Access GitHub

> Mount GitHub repositories into a Session container so the Agent can read, modify code, and open Pull Requests.

Qoder Cloud Agents lets you attach a GitHub repository to a Session as a resource. When the Session starts, the platform clones the repository into the container at the path you choose. The Agent can then read, edit, commit, and push code as if working in a local checkout, and open a Pull Request via the [`gh` CLI](https://cli.github.com/).

Repository resources share their lifecycle with the owning Session. If you need to change the URL or `mount_path`, create a new Session — mounted repositories cannot be swapped on a running Session.

## Workflow

<Steps>
  <Step title="Prepare a GitHub token">
    Generate a GitHub Personal Access Token (a fine-grained PAT is recommended) that grants the repository scopes required for the task — read, write, Pull Request creation, etc. The token is a required field on every GitHub repository resource.
  </Step>

  <Step title="Mount the repository when creating the Session">
    Add a `type: "github_repository"` entry to `resources` in the create-Session request, including the URL and PAT.
  </Step>

  <Step title="Agent works on the code">
    Once the Session boots, the Agent can read code at the mount path and modify files via `Bash`, `Read`, `Write`, `Edit`, etc.
  </Step>

  <Step title="(Optional) Open a Pull Request">
    Have the Agent push a branch with `git push` and open a PR using the `gh` CLI from inside the repository directory.
  </Step>
</Steps>

<Note>
  Repository clones live on the container's ephemeral disk. After 24 hours of inactivity the platform may reclaim the disk; the Session can still resume conversation, but uncommitted changes on disk are lost. See [Container reference — File persistence](/cloud-agents/container-reference#file-persistence).
</Note>

## Repository resource fields

A GitHub repository resource uses the following fields. Pass them in when you create the Session:

| Field                 | Type   | Required | Description                                                                                  |
| --------------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `type`                | string | Yes      | Must be `"github_repository"`                                                                |
| `url`                 | string | Yes      | Repository URL, e.g. `https://github.com/your-org/your-repo`                                 |
| `mount_path`          | string | No       | Path to clone into inside the container. Defaults to a path derived from the repository name |
| `authorization_token` | string | Yes      | GitHub Personal Access Token used to clone and push the repository                           |

<Note>
  `authorization_token` is supplied only on the create request or token-rotation request. It is not returned when you fetch Session details or Session resources. Use a least-privilege PAT for each Session and revoke it when finished.
</Note>

## Mount a GitHub repository at Session creation

Call [Create Session](/cloud-agents/api/sessions/create) with the repository inside `resources[]`:

```bash theme={null}
curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5", "type": "agent", "version": 2},
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
    "title": "Fix bug in your-repo",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/your-repo",
        "mount_path": "/app/your-repo",
        "authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    ]
  }' | jq .
```

A successful response is **HTTP 200 OK** and the `resources` array contains the normalized mount description. The token is not returned:

```json theme={null}
{
  "id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "type": "session",
  "agent": {
    "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "type": "agent",
    "name": "code-reviewer",
    "description": "",
    "model": {"id": "ultimate", "effective_context_window": 200000},
    "system": "You are a code review expert.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
      }
    ],
    "skills": [],
    "version": 2
  },
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "Fix bug in your-repo",
  "metadata": {},
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/your-org/your-repo",
      "mount_path": "/app/your-repo",
      "checkout": null,
      "created_at": "2026-05-18T12:00:00Z",
      "updated_at": "2026-05-18T12:00:00Z"
    }
  ],
  "vault_ids": [],
  "deployment_id": null,
  "outcome_evaluations": [],
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "environment_variables": {},
  "archived_at": null,
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}
```

<Tip>
  Agent commands run with cwd `/app`. Setting `mount_path` to `/app/<repo-name>` lets the Agent reference relative paths such as `your-repo/...` directly in system prompts and user messages without changing directories.
</Tip>

## Mount multiple repositories

A single request can attach several repositories under different `mount_path` values, for example to bring frontend and backend code into the same Session:

```bash theme={null}
curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5", "type": "agent", "version": 2},
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
    "title": "Full-stack debugging",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/frontend",
        "mount_path": "/app/frontend",
        "authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/backend",
        "mount_path": "/app/backend",
        "authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    ]
  }' | jq .
```

You can mix repositories with files, Memory Stores, and Vaults; see [Sessions — Attach resources at creation](/cloud-agents/sessions#attach-resources-at-creation).

## Token permission model

GitHub offers two PAT flavours: fine-grained PATs (recommended) and classic PATs. Whichever you choose, follow the principle of least privilege and grant only the scopes the task needs.

### Recommended permissions

The table below maps common Agent actions to fine-grained PAT repository permissions. For a classic PAT, the equivalent is the `repo` scope.

| Agent action                               | Fine-grained PAT permission (Repository permissions) |
| ------------------------------------------ | ---------------------------------------------------- |
| Clone / read a private repo                | `Contents: Read`                                     |
| Create a branch and push                   | `Contents: Read & Write`                             |
| Open / comment on Pull Requests            | `Pull requests: Read & Write`                        |
| Read Issues                                | `Issues: Read`                                       |
| Create / comment on Issues                 | `Issues: Read & Write`                               |
| Read repository metadata (always required) | `Metadata: Read`                                     |

<Tip>
  A fine-grained PAT can be scoped to specific repositories — even specific organization resources — making it safer than a classic PAT. Issue a fresh, short-lived PAT for each Agent task.
</Tip>

### Security guidance

1. Keep the Session creation request body and any response containing `resources` out of logs, screenshots, and version control — they include the plaintext PAT.
2. Revoke the PAT in GitHub settings as soon as the task ends; fine-grained PATs also support short `Expiration` values.
3. The PAT is required even for public repositories; for those, prefer a read-only, short-lived token to minimize the exposure surface.
4. Use distinct PATs across environments (development vs production) so audit trails remain meaningful.

## Pull Request workflow

Inside a mounted repository directory, the Agent can run `git` and `gh` commands directly. The runtime image ships both `git` and the `gh` CLI, and the platform automatically wires the repository resource's `authorization_token` into the container as `GH_TOKEN` — there is no need to install `gh` or export the token yourself. To drive the full "edit -> push -> open PR" flow:

1. Enable the `agent_toolset_20260401` toolset on the Agent and include at least `Bash`, `Read`, `Write`, and `Edit`. See [Tools](/cloud-agents/tools).
2. State the task, repository path, and target branch clearly in the user message.

The example below assumes Session ID `sess_019e5ce0bf9074b69c3481e93771a522` with a repository mounted at `/app/your-repo`:

```bash theme={null}
curl -s -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Please fix issue #128 in /app/your-repo (users cannot refresh their token after login). Full flow:\n1) cd /app/your-repo;\n2) git checkout -b fix/refresh-token;\n3) fix the bug in src/auth/refresh.ts and add unit tests;\n4) git add the changes and git commit -m \"fix(auth): rotate refresh token on login\";\n5) git push -u origin fix/refresh-token;\n6) run gh pr create --base main --head fix/refresh-token --title \"fix(auth): rotate refresh token on login\" --body \"Fixes #128\" to open the Pull Request."
          }
        ]
      }
    ]
  }'
```

<Note>
  The platform auto-configures `GH_TOKEN` inside the container from the repository resource's `authorization_token`, so `gh pr create` works out of the box. PR creation fails if that PAT lacks `Pull requests: Read & Write`; provision the PAT with the scopes listed in [Recommended permissions](#recommended-permissions) up front.
</Note>

## Best practices for Agent configuration

* Enable `Bash`, `Read`, `Write`, `Edit`, `Glob`, and `Grep` in the Agent's `tools` to cover code search and modification.
* State the mount path explicitly in the Agent's `system` prompt, e.g. "Your working directory is `/app/your-repo`. Run all `git` and `gh` commands inside this folder."
* For long tasks, ask the Agent to run `git status` at the end of each turn so nothing is left uncommitted.
* To carry artefacts across Sessions, have the Agent upload key outputs (patches, reports) via the [Files API](/cloud-agents/files); otherwise unuploaded intermediate files are lost when the container disk is reclaimed after 24 hours of inactivity.

## FAQ

**Q: The repository is huge — how do I speed up cloning?**

A: Repository resources currently use a full clone; there is no shallow-clone switch on the resource object. For very large monorepos, narrow the task scope or upload the relevant subdirectories/files via the [Files API](/cloud-agents/files) as supplemental context.

**Q: What if the PAT expires or is revoked?**

A: Subsequent git / `gh` calls return 401. Create a new Session with a fresh PAT. If you have local changes that have not been pushed, ask the Agent to emit a `git diff` patch first and upload it via the [Files API](/cloud-agents/files) for safekeeping.

**Q: Are private forks or organization-internal repositories supported?**

A: Yes — as long as the PAT has `Contents: Read` on the target repository. If the organization enforces SSO, you must authorize the PAT (Authorize button) before it can clone.

**Q: Are git submodules supported?**

A: Repository resources do not expose a separate submodule field. If you need submodules, have the Agent run `git submodule update --init --recursive` inside the repository, and make sure the PAT has read access to every submodule repository.

**Q: Can I swap repositories on a running Session?**

A: No. Once a Session is created with a particular repository mount, that mount cannot be replaced via update calls. Create a new Session if you need a different repository or `mount_path`.

**Q: Will the Agent automatically push changes back to GitHub?**

A: No. Unless the Agent runs `git push` in its turn, edits remain on the container's ephemeral disk. Spell out "push the branch" or "open a PR" in the user message.

**Q: Is GitHub Enterprise Server (GHES) supported?**

A: GitHub repository resources expose only `url`, `mount_path`, and `authorization_token`; there is no separate GHES configuration field. For GitHub Enterprise Server, confirm the GHES endpoint is reachable from the platform and that the token works with `gh`/git for that host.

## Next steps

* [Sessions — Attach resources at creation](/cloud-agents/sessions#attach-resources-at-creation) — overview of resource mounts
* [API — Create a session](/cloud-agents/api/sessions/create) — full request body for Session creation
* [Skills](/cloud-agents/skills) — reuse code review and PR workflows
* [Container reference](/cloud-agents/container-reference) — directory layout and disk behaviour