GitHub

​

Example seed

{
  "name": "GitHub eval fixture",
  "twins": [
    "github"
  ],
  "seed_config": {
    "github": {
      "users": [
        {
          "login": "developer",
          "name": "Developer",
          "email": "developer@example.com"
        }
      ],
      "orgs": [
        {
          "login": "example-org",
          "name": "Example Org"
        }
      ],
      "app": {
        "permissions": {
          "actions": "read",
          "metadata": "read"
        },
        "events": [
          "workflow_run"
        ]
      },
      "repos": [
        {
          "owner": "example-org",
          "name": "repo-name",
          "description": "Short repo description",
          "private": false,
          "default_branch": "main",
          "actions_artifacts": {
            "run": {
              "id": 1001,
              "head_branch": "main"
            },
            "artifacts": [
              {
                "id": 1002,
                "name": "test-results",
                "files": {
                  "report.txt": "All tests passed\n"
                }
              }
            ]
          },
          "files": [
            {
              "path": "README.md",
              "branch": "main",
              "content": "file body text"
            }
          ],
          "branches": [
            {
              "name": "feature-branch",
              "from": "main"
            }
          ],
          "labels": [
            {
              "name": "bug",
              "color": "d73a4a",
              "description": "A defect"
            }
          ],
          "issues": [
            {
              "title": "Issue title",
              "body": "Issue description",
              "labels": [
                "bug"
              ]
            }
          ],
          "prs": [
            {
              "title": "PR title",
              "head": "feature-branch",
              "base": "main",
              "state": "open",
              "body": "PR description",
              "files": [
                {
                  "path": "src/app.ts",
                  "status": "modified",
                  "content": "complete file contents on the PR head branch"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

​

Parameters

​

Seeding behavior

​

Resource fields

​

users[]

​

orgs[]

​

repos[]

​

repos[].actions_artifacts.artifacts[]

​

repos[].files[]

​

repos[].branches[]

​

repos[].labels[]

​

repos[].issues[]

​

repos[].prs[]

​

repos[].prs[].files[]

​

API coverage and limitations

• GitHub Actions workflows, runs, jobs, logs, and artifacts in the same GitHub twin. Simulation is the default; eligible internal accounts can enable real execution for supported workflows in private environments.
• GitHub REST API operations for repositories, branch-aware file contents, pull requests, issues, branches, commits, check runs, check suites, git references, labels, pull request reviews, review comments, commit statuses, search, organizations, users, and webhooks.
• Raw file downloads served as public content (no bearer token required) for both https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path} and https://github.com/{owner}/{repo}/raw/{ref}/{path}. The twin gateway intercepts raw.githubusercontent.com and the resolver matches the longest known branch prefix so slash-containing branch names (for example, feature/deep) and refs/heads/... / HEAD/... refs are handled correctly. Responses use the file’s guessed MIME type (defaulting to application/octet-stream).
• GitHub App endpoints for installations, access tokens, repository listings, app metadata (GET /app, GET /apps/{app_slug}), and the GitHub App manifest registration flow for creating multiple GitHub Apps at runtime (GET/POST /settings/apps/new, GET/POST /organizations/{org}/settings/apps/new, POST /app-manifests/{code}/conversions).
• Multi-app support: each installation is scoped to its owning GitHub App, JWT and installation tokens resolve the correct app, and per-app bot users, webhook secrets, and RSA key pairs are tracked independently.
• Deterministic seeding for repos, files, issues, PRs, checks, and GitHub App configuration.
• Token authentication, OAuth flows, scope enforcement, signed webhook delivery, admin state export, and stub-hit tracking.
• GitHub CLI (gh) and GitHub MCP server compatibility. The twin accepts requests at the standard api.github.com paths as well as the GitHub Enterprise-style /api/v3/... REST prefix and the /api/graphql endpoint, so gh and MCP clients can be pointed at the twin’s base URL without code changes.
• Extended REST coverage used by gh and the MCP server: GET /meta, GET /rate_limit, GET /zen, GET /api/v3, repository archives (/zipball/{ref}, /tarball/{ref}), releases, search for repositories, users, issues, and code, gists (list, get, create, update, delete), notifications and thread subscriptions, projects v2 (org and user fields and items), org and repo Actions workflows, workflow runs, jobs, and artifacts, Actions cache, variables, and secrets, codespaces (list, get, update, stop, delete, ports), user SSH and signing keys, GPG keys, starred repositories, sub-issues and issue types, repository security advisories, global security advisories, Dependabot alerts, code scanning alerts, and secret scanning alerts.
• GraphQL surface at POST /graphql (also reachable through POST /api/graphql) covering the queries and mutations used by gh and the GitHub MCP server, including viewer, repository, issue, and pull request lookups, search, and the corresponding mutations backed by the same store as the REST handlers.

1. Provision the github twin and seed at least one user or organization plus the repositories your app should see.
2. Point your app’s GitHub API and web URLs at the provisioned twin. The wizard handles the standard api.github.com, github.com, and raw.githubusercontent.com rewrites automatically.
3. Register a GitHub App with the manifest flow at GET or POST <github_twin_url>/settings/apps/new, or use GET or POST <github_twin_url>/organizations/{org}/settings/apps/new for an org-owned app. Exchange the returned code with POST <github_twin_url>/app-manifests/{code}/conversions to receive the app id, client id, client secret, webhook secret, and PEM private key.
4. Install the app through the browser flow at <github_twin_url>/apps/{app_slug}/installations/new. Choose the account, repository access, optional webhook URL, and optional webhook secret.
5. For a programmatic setup, create the installation with POST <github_twin_url>/admin/installations using account, app_slug or app_id, repository_selection, optional repositories, optional webhook_url, and optional webhook_secret.
6. From your app, sign a GitHub App JWT with the returned private key, call POST /app/installations/{installation_id}/access_tokens, and use the returned installation token for repository, issue, PR, check, and webhook workflows.

• Endpoints without a full stateful implementation return explicit stub responses with X-Twin-Stub, _twin_stub, and _twin_warning.
• Stub hits can be audited through GET <admin_url>/admin/stub-hits and cleared with POST <admin_url>/admin/stub-hits/clear.
• The GraphQL surface targets the operations used by gh and the official GitHub MCP server. Queries and mutations outside that set may return structured stub responses.
• Strict 100% live gh and MCP coverage is gated by external GitHub fixtures and explicit mutation consent flags. The scripts/validate_github_cli_mcp_compat.py verifier reports any remaining blockers directly.
• Actions API coverage and seeded success results do not imply real workflow execution. The optional execution worker supports a bounded workflow subset, rather than complete GitHub-hosted-runner compatibility.