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

# GitHub

> GitHub Scenario seeding parameters, nested fields, and examples

Use `github` in `twins` and put this configuration under `seed_config.github`.

GitHub with repos, users, orgs, branch file contents, issues, and pull requests.

## Example seed

This is the complete Scenario request body for [creating a Scenario](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`.

```json theme={null}
{
  "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

The following fields belong directly inside `seed_config.github`. Required nested fields are marked in their tables. Provider-native objects can contain service-specific fields beyond the representative record shapes below.

| Parameter | Type | Description |
| - | - | - |
| `users` | `object[]` | Users fixtures in provider-native format. |
| `orgs` | `object[]` | Orgs fixtures in provider-native format. |
| `app` | `object` | Default GitHub App permissions and subscribed event names. |
| `repos` | `object[]` | Repos fixtures in provider-native format. |
| `base_time` | `string` | Reference clock for repeatable fixtures. Omit to use the current clock. |
| `copilot` | `object` | Configured Copilot chat/review/task responses. |
| `actions_execution` | `object` | Simulated workflow timing, job conclusions, and logs keyed by workflow path. |

## Seeding behavior

Use `github` for new GitHub and GitHub Actions fixtures. `app` accepts only `permissions` and `events`. Repository imports accept a public HTTPS GitHub URL or `owner/repo`; pin `source_ref` to a commit for repeatable imports. `actions_execution` replays configured outcomes without executing shell commands. See [GitHub Actions](https://docs.argalabs.com/features/github-actions.md) for execution-mode behavior.

## Resource fields

These tables describe the record shapes used by the example. Keep native field names and casing. Map keys such as property names, IDs, and metadata keys are supplied by your fixture.

### `users[]`

| Parameter | Type | Description |
| - | - | - |
| `login` | `string` | Login. |
| `name` | `string` | Human-readable name. |
| `email` | `string` | Main account email address. |

### `orgs[]`

| Parameter | Type | Description |
| - | - | - |
| `login` | `string` | Login. |
| `name` | `string` | Human-readable name. |

### `repos[]`

| Parameter | Type | Description |
| - | - | - |
| `owner` | `string` | Owner. |
| `name` | `string` | Human-readable name. |
| `description` | `string` | Description. |
| `private` | `boolean` | Enable or set private behavior. |
| `default_branch` | `string` | Default branch. |
| `actions_artifacts` | `object` | Actions artifacts. |
| `files` | `object[]` | Files fixtures in provider-native format. |
| `branches` | `object[]` | Branches fixtures in provider-native format. |
| `labels` | `object[]` | Custom label names or objects containing name. |
| `issues` | `object[]` | Issues fixtures in provider-native format. |
| `prs` | `object[]` | Prs fixtures in provider-native format. |
| `repo_url` | `string` | Repo url. |
| `public_repo_url` | `string` | Public repo url. |
| `clone_url` | `string` | Clone url. |
| `source_repo_url` | `string` | Source repo url. |
| `source_ref` | `string` | Source ref. |
| `ref` | `string` | Ref. |
| `pull_requests` | `array or object` | Pull requests. |
| `merged_prs` | `array` | Merged prs fixtures in provider-native format. |
| `merged_pull_requests` | `array` | Merged pull requests fixtures in provider-native format. |
| `webhooks` | `object[]` | Webhook subscriptions or configurations. |

### `repos[].actions_artifacts.artifacts[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `integer` | Explicit resource identifier, when supported. |
| `name` | `string` | Human-readable name. |
| `files` | `object` | Files. |

### `repos[].files[]`

| Parameter | Type | Description |
| - | - | - |
| `path` | `string` | Path. |
| `branch` | `string` | Branch. |
| `content` | `string` | Text content. |
| `message` | `string` | Message. |

### `repos[].branches[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `from` | `string` | From. |

### `repos[].labels[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `color` | `string` | Color. |
| `description` | `string` | Description. |

### `repos[].issues[]`

| Parameter | Type | Description |
| - | - | - |
| `title` | `string` | Human-readable name. |
| `body` | `string` | Text content. |
| `labels` | `string[]` | Custom label names or objects containing name. |

### `repos[].prs[]`

| Parameter | Type | Description |
| - | - | - |
| `title` | `string` | Human-readable name. |
| `head` | `string` | Head. |
| `base` | `string` | Base. |
| `state` | `string` | State. |
| `body` | `string` | Text content. |
| `files` | `object[]` | Files fixtures in provider-native format. |
| `changed_files` | `array` | Changed files fixtures in provider-native format. |
| `draft` | `boolean` | Enable or set draft behavior. |
| `merged` | `boolean` | Enable or set merged behavior. |

### `repos[].prs[].files[]`

| Parameter | Type | Description |
| - | - | - |
| `path` | `string` | Path. |
| `status` | `string` | Status. |
| `content` | `string` | Text content. |
| `base_content` | `string` | Base content. |
| `remove` | `boolean` | Enable or set remove behavior. |

## API coverage and limitations

**Twin name:** `github`

**Supports**

* [GitHub Actions](https://docs.argalabs.com/features/github-actions.md) 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](https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest) 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](https://github.com/github/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.

**Install apps against the twin**

Use the GitHub twin when your app normally registers or installs a GitHub App and then authenticates with installation tokens.

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.

**Known limitations**

* 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](https://docs.argalabs.com/features/github-actions.md#supported-workflows-and-limits), rather than complete GitHub-hosted-runner compatibility.

**MCP tools:** `get_twin_catalog`, `provision_twins`, `start_url_validation`, `get_validation_results`.

See [Scenario seeding](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.