Sources

Redocly connects to your source control to offer continuous validation and delivery of your:

  • API definitions
  • API reference docs
  • API developer portal

Contact us to learn about what else we can automate.

How it works

Redocly integrates with popular version control services such as GitHub, GitLab, Bitbucket, and Azure Repos. When you open a pull request, or commit and push to these services, Redocly can be notified automatically and perform an action. For example, we can validate your API definition and build a preview of your API reference docs.

While we recommend following a git-ops docs-like-code workflow, we also support other non-git-based sources such as file uploads, URLs, and CI/CD.

Security settings for version control services

When you connect your source to Redocly Workflows, our app will send requests to your version control service from specific IP addresses.

If you're using IP address protection as a security measure in your version control service, add the following IP addresses to your allowlist:

52.206.6.186

3.66.108.62

Allowing these addresses will ensure that Redocly Workflows can access your project repositories and run builds based on changes you and your contributors make.

Triggers by source types

Version control services (preferred)

Redocly can trigger workflows based on pushed commits, and on opened or changed pull requests.

You can connect to:

  • GitHub
  • GitHub Enterprise
  • Azure Repos
  • GitLab.com
  • GitLab self-managed
  • Bitbucket Cloud
  • Bitbucket self-managed (Server or Data Center)

Limiting builds

Note

Currently supported only for GitHub and GitHub Enterprise.

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.

CI/CD with OpenAPI CLI push

To maintain your API definitions from the CI without allowing Redocly to access your repositories, you can integrate our OpenAPI CLI push command into your pipeline and use it as a source.

File upload

Redocly can run the workflows on demand, when you upload the file(s).

URL source

Redocly can poll a URL at regular intervals. If there is a change, Redocly will validate, bundle, add it to the registry, and trigger the workflow.