Skip to main content
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

FilePurpose
lib/non-schema-scalars.jsonCustom scalar types from graphql-ruby that are not in the GraphQL spec
lib/types.jsonHigh-level type taxonomy used in rendering
lib/validator.tsTypeScript 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

Check that your GITHUB_TOKEN is set in .env, has the correct scopes, and has SSO authorized for the github org.
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.
  • 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.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us