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

# GitHub

> Repos, issues, pull requests, branches, and commits.

GitHub is included in Archal's environment catalog. Use it in a sandbox for repos, issues, pull requests, branches, and commits.

|                 |                                               |
| --------------- | --------------------------------------------- |
| Environment ID  | `github`                                      |
| Transport       | REST and MCP                                  |
| State           | JSON                                          |
| Contract        | `archal.environment-state.github` version `1` |
| Channel         | Public                                        |
| Curated samples | 5                                             |

Public is the intended GA channel. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

<Note>
  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.
</Note>

* The supported route manifest remains the boundary; it is not the entire GitHub API.

## Curated starting states

List the five samples with `archal sample list github`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

<AccordionGroup>
  <Accordion title="GitHub issue baseline">
    Read one open issue in one repository, then create and reset a second issue as the authenticated user.

    **Sample ID:** `github.small-project.v1`

    **Category:** `minimal`

    **Starting state:** 5 records across `issues`: 1, `labels`: 1, `repos`: 1, `users`: 2

    **Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

    **First read:** `GET /repos/octocat/webapp/issues?state=all&per_page=30`. Expected result: HTTP 200.

    **Representative mutation:** `POST /repos/octocat/webapp/issues`. Expected result: HTTP 201.

    **Mutation input**

    ```json theme={null}
    {
      "body": "Cover duplicate delivery, Retry-After, and reset behavior before the next release.",
      "title": "Add connector retry contract coverage"
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * The supported route manifest remains the boundary; it is not the entire GitHub API.

    **Start this sample**

    ```bash theme={null}
    archal sample show github.small-project.v1 --raw > archal-github-small-project.json
    archal state validate github archal-github-small-project.json
    archal session create github \
      --state github=archal-github-small-project.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show github.small-project.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/github/small-project/state.json` and is 6,415 bytes. The CLI verifies SHA-256 `66a7dbe976cbb2868380ccf44e3389ca5384616010d76a6eb6398b944ca1c726` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="GitHub engineering organization">
    Model a small engineering organization with teams, repositories, issues, pull requests, and deployment activity.

    **Sample ID:** `github.engineering-organization.v1`

    **Category:** `small-team`

    **Starting state:** 206 records across `branches`: 14, `checkRuns`: 9, `collaborators`: 9, `comments`: 5, `commits`: 7, `commitStatuses`: 5, `deployments`: 5, `deploymentStatuses`: 7, `discussionCategories`: 4, `discussionComments`: 12, `discussions`: 4, `environments`: 3, `files`: 7, `gists`: 2, `issues`: 40, `labels`: 12, `milestones`: 4, `notifications`: 6, `organizations`: 1, `projectsV2`: 2, `pullRequests`: 4, `releases`: 3, `repos`: 5, `starredRepos`: 4, `tags`: 3, `teamMembers`: 9, `teams`: 3, `users`: 6, `webhooks`: 4, `workflowRuns`: 4, `workflows`: 3

    **Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

    **First read:** `GET /repos/admin-user/platform/issues?state=all&per_page=30`. Expected result: HTTP 200.

    **Representative mutation:** `POST /repos/admin-user/platform/issues`. Expected result: HTTP 201.

    **Mutation input**

    ```json theme={null}
    {
      "body": "Correlate delivery attempts and verify downstream idempotency before replay.",
      "title": "Investigate duplicate payment-webhook delivery"
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * The supported route manifest remains the boundary; it is not the entire GitHub API.

    **Start this sample**

    ```bash theme={null}
    archal sample show github.engineering-organization.v1 --raw > archal-github-engineering-organization.json
    archal state validate github archal-github-engineering-organization.json
    archal session create github \
      --state github=archal-github-engineering-organization.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show github.engineering-organization.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/github/engineering-organization/state.json` and is 127,360 bytes. The CLI verifies SHA-256 `d8dfb6ce56f25380cd83e44d75a9881136adbba6642bae04f508b08b7b79ae89` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="GitHub large issue backlog">
    Exercise issue listing, filtering, ordering, and pagination against fifty issues in one repository.

    **Sample ID:** `github.large-issue-backlog.v1`

    **Category:** `populated`

    **Starting state:** 56 records across `issues`: 50, `labels`: 4, `repos`: 1, `users`: 1

    **Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

    **First read:** `GET /repos/devops-lead/infrastructure/issues?state=all&per_page=10`. Expected result: HTTP 200.

    **Representative mutation:** `POST /repos/devops-lead/infrastructure/issues`. Expected result: HTTP 201.

    **Mutation input**

    ```json theme={null}
    {
      "body": "Confirm paging, rollback, and provider-rate-limit coverage.",
      "title": "Audit connector egress alerts before the production cutover"
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * The supported route manifest remains the boundary; it is not the entire GitHub API.

    **Start this sample**

    ```bash theme={null}
    archal sample show github.large-issue-backlog.v1 --raw > archal-github-large-issue-backlog.json
    archal state validate github archal-github-large-issue-backlog.json
    archal session create github \
      --state github=archal-github-large-issue-backlog.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show github.large-issue-backlog.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/github/large-issue-backlog/state.json` and is 49,825 bytes. The CLI verifies SHA-256 `6576e476b68e2aaeeb50b0d7122bb4881f37a384a84bb413b97845a80a3ba48e` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="GitHub merge conflict">
    Verify a pull request whose source and target branches contain conflicting file revisions.

    **Sample ID:** `github.merge-conflict.v1`

    **Category:** `edge-case`

    **Starting state:** 15 records across `branches`: 2, `commits`: 3, `files`: 4, `issues`: 1, `labels`: 1, `pullRequests`: 1, `repos`: 1, `users`: 2

    **Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

    **First read:** `GET /repos/dev-main/conflict-repo/pulls/1`. Expected result: HTTP 200.

    **Representative mutation:** `POST /repos/dev-main/conflict-repo/issues/1/comments`. Expected result: HTTP 201.

    **Mutation input**

    ```json theme={null}
    {
      "body": "Conflict reproduced in the configuration file. Keep the pull request blocked until the base branch is reconciled."
    }
    ```

    **Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * The supported route manifest remains the boundary; it is not the entire GitHub API.

    **Start this sample**

    ```bash theme={null}
    archal sample show github.merge-conflict.v1 --raw > archal-github-merge-conflict.json
    archal state validate github archal-github-merge-conflict.json
    archal session create github \
      --state github=archal-github-merge-conflict.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show github.merge-conflict.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/github/merge-conflict/state.json` and is 10,532 bytes. The CLI verifies SHA-256 `30274c2ec28348487ff8e3787de2db4ba835e41429fedfe0157d4e8103f07730` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="GitHub CI/CD pipeline workflow">
    Correlate INC-2027-014 with api-gateway\@3.1.0, its production deployment, failed delivery behavior, rollback evidence, and remediation PR.

    **Sample ID:** `github.ci-cd-pipeline.v1`

    **Category:** `workflow`

    **Starting state:** 102 records across `branches`: 5, `checkRuns`: 12, `collaborators`: 4, `comments`: 2, `commits`: 6, `commitStatuses`: 7, `deployments`: 7, `deploymentStatuses`: 9, `environments`: 4, `files`: 3, `issues`: 5, `labels`: 5, `milestones`: 2, `notifications`: 3, `pullRequests`: 2, `releases`: 3, `repos`: 1, `tags`: 3, `users`: 4, `webhooks`: 5, `workflowRuns`: 6, `workflows`: 4

    **Supported surface:** Stateful repository, issue, pull-request, content, workflow, and organization REST flows.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.repositories`

    **First read:** `GET /repos/archal-labs/api-gateway/issues/2`. Expected result: HTTP 200.

    **Representative mutation:** `POST /repos/archal-labs/api-gateway/issues/2/comments`. Expected result: HTTP 201.

    **Mutation input**

    ```json theme={null}
    {
      "body": "INC-2027-014: api-gateway@3.1.0 rollback is healthy. Do not replay queued deliveries until idempotency verification is complete."
    }
    ```

    **Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * The supported route manifest remains the boundary; it is not the entire GitHub API.

    **Start this sample**

    ```bash theme={null}
    archal sample show github.ci-cd-pipeline.v1 --raw > archal-github-ci-cd-pipeline.json
    archal state validate github archal-github-ci-cd-pipeline.json
    archal session create github \
      --state github=archal-github-ci-cd-pipeline.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show github.ci-cd-pipeline.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/github/ci-cd-pipeline/state.json` and is 58,614 bytes. The CLI verifies SHA-256 `6cdc20ed2682a4e7d65a30c8c372ff0ab3930af7fe51ad22aa1c26c9a2e61c0a` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>
</AccordionGroup>

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe github`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate github state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](/sandboxes/starting-state) before replacing state in an existing sandbox.