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.

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

Running the sync locally

1. Ensure API access

   You need a GitHub token with access to the GraphQL API. Set it in your .env:

   GITHUB_TOKEN=ghp_your_token_here
   
2. Run the sync script

   npm run sync-graphql
   

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

3. Verify the output

   Check that the schema files were updated. The data/ghec/schema.json file should reflect the latest introspection result.

   git diff src/graphql/data/
   

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:

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:

1. Update the version list

   Add the new version to the version list in src/graphql/scripts/sync.ts.

2. Run the sync

   npm run sync-graphql
   

   A new data/ghes-X.XX/schema.json file is created.

3. Update content if needed

   Check content/graphql/ for any version-gated content that may need updates for the new version.

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

Troubleshooting

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.

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.

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.

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.

Getting help

• Slack: #docs-engineering
• Repo: github/docs-engineering