Last updated

GitHub

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

Connect to GitHub

Note

Complete this process once for your organization.

Select the link to install the Redocly GitHub app.

Install the Redocly Workflows GitHub app

Connected to the wrong GitHub account?

  1. Go to GitHub and log in with the correct account.
  2. Go back to the Source Settings page and select "Switch account" to authorize the Redocly GitHub app. Switch account link
  3. After you've authorized with the correct account, you need to install the Redocly GitHub app.

Select organization in GitHub

Note

It requires GitHub admin privileges to install an app.

Select the organization. If you notice "Configure" in the link, it means the Redocly Workflows app is already installed, and you may adjust repositories granted access.

Select organization screen

Select repositories to grant access

We recommend you grant access to specific repositories (the repositories with your API definitions and developer portals).

Select organization screen

Redocly Workflows app does not create repositories (and if it did access would also be given to those).

Select organization screen

Not an admin? You will see a "Request" button

If you are not an admin, you will see a "Request" button.

Select organization screen

Your admin will need to approve the app by navigating to the "Installed GitHub Apps" within your organization's GitHub settings.

Select organization screen

Then, your admin will scroll down the page to find the section with "Pending GitHub Apps installation requests" and select "Review request".

Select organization screen

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

Set up the connection

Select your organization.

Organization screen

Select from the list of repositories available to the Redocly Workflows app for the selected organization.

GitHub select repo

Select from the list of branches available.

GitHub select branch

If you are using a redocly.yaml file, there will be options of to select your root file based on the apis configuration within the file.

Select path to root file

Note: Redocly Workflows app will detect a developer portal repo automatically and provide you with appropriate feedback.

Developer portal detected

Connect a monorepo

When connecting a monorepo or a large project where the API definitions and documentation are maintained together with the code and other resources, you can choose to limit the amount of files Workflows will check out and include in builds. This is useful for preventing build timeout issues and reduces the risk of exceeding build limits.

In the GitHub source configuration dialog, select your organization and the repository. Then, choose the production branch, and select the Connecting a monorepo? Pick a folder checkbox under Source settings. When this checkbox is selected, the Select the folder input field becomes available. Here you must either manually specify a folder in your repository (without the initial forward slash), or select a folder from the dropdown list.

GitHub source configuration dialog

The selected folder must contain at least one API definition file in YAML or JSON format. The API definition files from the selected folder are displayed in the Provide the path to your root file dropdown list. Choose one file from the list as your root API definition.

To use custom settings for your API registry and Reference docs builds, you must place your redocly.yaml configuration files into the selected folder. Once you have restricted your project to a folder in the repository, Workflows will not be able to use the redocly.yaml file(s) from the root of the repository or from any other folders.

Workflows will build and validate files only from the selected folder instead of checking out the entire repository. Any changes made outside of the selected folder will not trigger builds in your API registry or Reference docs project, and will be skipped. The GitHub interface will show all checks as passed, but validation and bundling as skipped.

To display such changes in Workflows, select the Show skipped checkbox on the Logs page.

Logs page with Show skipped checkbox selected

The Logs page shows the no-changes tag for registry builds where the API definition file has not changed since the previous build.

Skipped jobs or builds do not count towards monthly usage limits.

Lint and bundle previews

When you select to validate and bundle 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.

Lint and bundle PRs