Skip to main content
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. 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

1

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.
2

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.
3

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.
4

(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.
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.

​
Repository resource fields

A GitHub repository resource uses the following fields. Pass them in when you create the Session:
FieldTypeRequiredDescription
typestringYesMust be "github_repository"
urlstringYesRepository URL, e.g. https://github.com/your-org/your-repo
mount_pathstringNoPath to clone into inside the container. Defaults to a path derived from the repository name
authorization_tokenstringYesGitHub Personal Access Token used to clone and push the repository
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.

​
Mount a GitHub repository at Session creation

Call Create Session with the repository inside resources[]: 
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: 
{
  "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"
}
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.

​
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: 
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.

​
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. The table below maps common Agent actions to fine-grained PAT repository permissions. For a classic PAT, the equivalent is the repo scope.
Agent actionFine-grained PAT permission (Repository permissions)
Clone / read a private repoContents: Read
Create a branch and pushContents: Read & Write
Open / comment on Pull RequestsPull requests: Read & Write
Read IssuesIssues: Read
Create / comment on IssuesIssues: Read & Write
Read repository metadata (always required)Metadata: Read
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.

​
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.
  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: 
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."
          }
        ]
      }
    ]
  }'
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 up front.

​
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; 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 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 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