Last updated 9 months ago

GitHub

Use GitHub as a source for your API definitions and developer portal projects.

Connecting the source

Start connection process

Connect GitHub

Click the link to install the Redocly GitHub app. Complete this process once for your organization. It requires GitHub admin privileges to install an app.

Organization screen

Select the organization you wish to install the GitHub app on.

Organization screen

We recommend you only grant access to specific repositories (the repositories with your API definitions and developer portals). Our app currently does not create repositories (and if it did access would also be given to those).

Organization screen

Once the app is installed and authorized by an admin of your GitHub account, then you can utilize it.

Complete the connection

Organization screen

When you select the organization, the list of repositories will be populated with those available to the Redocly app.

GitHub select repo

When you select the repository, the list of branches available will be populated.

GitHub select branch

For an API definition, if you are using a .redocly.yaml file, there will be options of to select your root file based on the apiDefinitions configuration within the file.

Select path to root file

For a developer portal, it will detect it automatically and provide you with appropriate feedback.

Developer portal detected

Build other branches as previews

When you select to build other branches as previews, it will trigger a build when a new branch is pushed or a new commit is pushed to an existing non-default branch. If a commit is pushed to your default branch, it will trigger a production build.

If your API version has other usages, it will trigger subsequent cascading preview builds of other APIs, reference docs, and developer portals.

Build other branches as previews

Build PRs as previews

When you select to build PRs as previews, it will trigger a build when:

  • a new pull request (PR) is opened
  • a new commit is pushed to any open PR

If your API version has other usages, it will trigger subsequent cascading preview builds of other APIs, reference docs, and developer portals.

Build PRs as previews