Use GitHub as a source for your API definitions and developer portal projects.
Connect to GitHub
Complete this process once for your organization.
Select install link
Select the link to install the Redocly GitHub app.
Connected to the wrong GitHub account?
- Go to GitHub and log in with the correct account.
- Go back to the Source Settings page and select "Switch account" to authorize the Redocly GitHub app.
- After you've authorized with the correct account, you need to install the Redocly GitHub app.
Select organization in GitHub
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 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).
Not an admin? You will see a "Request" button
If you are not an admin, you will see a "Request" button.
Your admin will need to approve the app by navigating to the "Installed GitHub Apps" within your organization's GitHub settings.
Then, your admin will scroll down the page to find the section with "Pending GitHub Apps installation requests" and select "Review request".
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.
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
apiDefinitions 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.