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

# GraphQL docs

> How GraphQL schema documentation is generated, validated, and rendered.

The GraphQL API documentation at docs.github.com/graphql is generated by fetching schema data directly from GitHub's GraphQL API. The sync script produces version-specific JSON files in `src/graphql/data/`, which are then consumed at render time by Next.js pages.

## How the pipeline works

The sync script in `src/graphql/scripts/sync.ts` performs an introspection query against GitHub's GraphQL API for each supported version. It writes:

* **`src/graphql/data/schema-VERSION.json`** — One schema file per version (e.g., `ghec`, `ghes-3.13`)
* **`src/graphql/data/previews.json`** — Preview features available across versions
* **`src/graphql/data/upcoming-changes.json`** — Upcoming breaking changes
* **`src/graphql/data/changelog.json`** — GraphQL API changelog entries

A `.github/workflows/sync-graphql.yml` workflow runs on a schedule to keep these files current.

## Directory structure

```
src/graphql/
├── components/        # React components rendering GraphQL reference pages
├── data/              # Auto-generated JSON schema files (do not edit manually)
│   ├── ghec/
│   │   └── schema.json
│   ├── ghes-3.13/
│   │   └── schema.json
│   ├── previews.json
│   ├── upcoming-changes.json
│   └── changelog.json
├── lib/
│   ├── index.ts           # Data-loading functions for Next.js pages
│   ├── non-schema-scalars.json  # Custom scalars from graphql-ruby
│   ├── types.json         # High-level GraphQL types and kinds
│   └── validator.ts       # Schema structure validation
├── pages/             # Next.js page files
└── scripts/
    └── sync.ts        # Pipeline entrypoint
```

Content files for the GraphQL docs are Markdown files in `content/graphql/`. Those files use Liquid to loop over the context data injected by the Next.js pages.

<Note>
  All files inside `src/graphql/data/` are generated. Edit `lib/*.json` and `scripts/*.ts` instead. Do not commit manual changes to data files.
</Note>

## Running the sync locally

<Steps>
  <Step title="Ensure API access">
    You need a GitHub token with access to the GraphQL API. Set it in your `.env`:

    ```bash theme={null}
    GITHUB_TOKEN=ghp_your_token_here
    ```
  </Step>

  <Step title="Run the sync script">
    ```bash theme={null}
    npm run sync-graphql
    ```

    This fetches the current schema for all versions and writes the output to `src/graphql/data/`.
  </Step>

  <Step title="Verify the output">
    Check that the schema files were updated. The `data/ghec/schema.json` file should reflect the latest introspection result.

    ```bash theme={null}
    git diff src/graphql/data/
    ```
  </Step>
</Steps>

## Schema validation

The project uses `@graphql-inspector/core` (a dev dependency) to validate GraphQL schema structure. The validator is configured in `src/graphql/lib/validator.ts` and runs as part of the test suite:

```bash theme={null}
npm run test -- src/graphql/tests
```

The validator catches structural issues in the schema data before they can affect rendered pages.

### Editable configuration files

| File                          | Purpose                                                                  |
| ----------------------------- | ------------------------------------------------------------------------ |
| `lib/non-schema-scalars.json` | Custom scalar types from `graphql-ruby` that are not in the GraphQL spec |
| `lib/types.json`              | High-level type taxonomy used in rendering                               |
| `lib/validator.ts`            | TypeScript validator used in `tests/graphql.ts`                          |

Do not manually edit any file inside `data/` — regenerate it with `npm run sync-graphql`.

## How rendering works

GraphQL data is loaded in Next.js pages using `getServerSideProps`. The `getGraphqlSchema()` function from `lib/index.ts` provides:

* The schema for the requested version
* Preview features for that version
* Upcoming breaking changes
* The changelog

Markdown files in `content/graphql/` use Liquid to loop over the context data and call HTML includes in the `includes/` directory for rendering individual schema items.

## Adding a new GHES version

When a new GHES version releases, you need to add a new schema file for it:

<Steps>
  <Step title="Update the version list">
    Add the new version to the version list in `src/graphql/scripts/sync.ts`.
  </Step>

  <Step title="Run the sync">
    ```bash theme={null}
    npm run sync-graphql
    ```

    A new `data/ghes-X.XX/schema.json` file is created.
  </Step>

  <Step title="Update content if needed">
    Check `content/graphql/` for any version-gated content that may need updates for the new version.
  </Step>

  <Step title="Commit the generated file">
    Commit the new schema file. It is large (100 KB+) but must be committed because the site reads it at runtime.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sync fails with an auth error">
    Check that your `GITHUB_TOKEN` is set in `.env`, has the correct scopes, and has SSO authorized for the `github` org.
  </Accordion>

  <Accordion title="Schema not loading in the browser">
    Verify that the file `src/graphql/data/VERSION/schema.json` exists for the version being requested. Check that the version detection logic in `lib/index.ts` maps correctly to the file name.
  </Accordion>

  <Accordion title="Content not rendering">
    * Check Liquid syntax in the relevant `content/graphql/` file.
    * Confirm the expected context properties (`context.graphql.*`) are available.
    * Check the HTML includes in the `includes/` directory.
  </Accordion>

  <Accordion title="Validation errors in tests">
    Schema structure must match the JSON schema defined in `lib/validator.ts`. If you see validation failures after a sync, compare the generated schema shape to what the validator expects and update `validator.ts` accordingly.
  </Accordion>
</AccordionGroup>

## Getting help

* Slack: `#docs-engineering`
* Repo: `github/docs-engineering`