Our REST pipeline creates autogenerated REST API documentation for docs.github.com/rest from the OpenAPI stored in the open-source repository github/rest-api-description
.
The pipeline is used to generate data that is used by the docs.github.com site when deployed locally, in preview environments, or in production.
A workflow is used to trigger the automation of the REST documentation. The workflow runs automatically on a schedule. The workflow that triggers the REST pipeline also triggers other automation pipelines that use the OpenAPI as the source data:
- GitHub Apps
- REST
- Webhooks
The workflow automatically creates a pull request with the changes (for all three pipelines) and the label github-openapi-bot
. The workflow runs the npm run sync-rest
script, which creates, deletes, or updates Markdown files in the content/rest
directory.
You can manually run the workflow leaving the source branch input parameter with the default value of main
. Running the workflow creates a new pull request in the github/docs-internal
repo with the changes.
If there is a pull request that is still unmerged in github/rest-api-description
that needs to be propagated to the docs.github.com site, manually run the workflow and provide the branch name of the pull request in the github/rest-api-description
repo that you would like to get the changes from. This will create a new pull request in the github/docs-internal
repo with the changes.
You will need to first wait for the OpenAPI to be merged into github/rest-api-description
.
Then, you can manually sync the data used by the REST, Webhooks, and GitHub App pipelines before the scheduled daily run here. Use the default input options.
To run the REST pipeline locally:
- Clone the
github/rest-api-description
repository inside your localdocs-internal
repository. - Set a
GITHUB_TOKEN
in your.env
with (classic)repo
scopes & enable SSO for the github org. - Run
npm run sync-rest -- -s rest-api-description -o rest
. Note, by default-o rest
is specified, so you can omit it.
src/github-apps/api
- API endpoints used by source code insrc/rest
.src/github-apps/components
- The React source code.src/rest/data
- The automatically generated data files created by running this pipeline.src/rest/lib
- The source code used in production for the automated documentation generated by the REST pipeline and configuration files edited by content and engineering team members.src/rest/lib/config.json
- A configuration file used to specify metadata about the REST pipeline.
src/rest/scripts
- The scripts and source code used run the REST pipeline, which updates thesrc/rest/data
directory.src/rest/scripts/update-files.ts
- The entrypoint script that runs the REST pipeline.
src/rest/tests
- The tests used to verify the REST pipeline.
The src/rest/lib/config.json
file contain metadata used by the content and engineering team to configure the REST pipeline. The file contains the following properties:
api-versions
- A list of the calendar-date API versions that are available for each version.versionMapping
- A mapping of the API version name used in the OpenAPI schema ingithub/rest-api-description
to the version short name used in thegithub/docs-internal
repo.frontmatterDefaults
- A list of default frontmatter values to append to each Markdown file incontent/rest
.targetDirectory
- The directory incontent
where the Markdown files that correspond to this pipeline are located.indexOrder
- The order of the children in theindex.md
file in thetargetDirectory
. ThestartsWith
keyword lists the directories undertargetDirectory
that should be listed first. All other automatically created directories are appended to this list.sha
- The SHA of the commit ingithub/rest-api-description
that was used to generate the data insrc/rest/data
and Markdown files incontent/rest
. This value is automatically updated when the pipeline runs.
The content writers can manually update parts of the autogenerated Markdown files in content/rest
. When new Markdown files are added they will get all of the frontmatter properties defined in the defaultFrontmatter
property in src/rest/lib/config.js
.
When a new Markdown file is created, a writer can manually change any of the frontmatter except versions
. The pipeline will overwrite the versions
property on subsequent runs, but will not modify any other frontmatter properties.
Writers can also add an introduction paragraph above the following Markdown comment:
<!-- Content after this section is automatically generated -->
Slack: #docs-engineering
Repo: github/docs-engineering
If you have a question about the REST pipeline, you can ask in the #docs-engineering
Slack channel. If you notice a problem with the REST pipeline, you can open an issue in the github/docs-engineering
repository.