GitHub

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

Connect to GitHub

Select install link

Select the link to install the Redocly 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.
3. After you've authorized with the correct account, you need to install the Redocly GitHub app.

Select organization in GitHub

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 repositories to grant access

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

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

Set up the connection

Select your organization.

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

Select from the list of branches available.

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.

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

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.

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.

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.