Remote content

Remote content is a feature that copies content from other file sources into your Redocly project. The sources can be Git repositories, public URLs, or any other file sources if they have a way to push the files to the Redocly cloud platform.

Visit the Remote content page in Reunite to see the remote content sources and their statuses.

Remote content is for subsections inside a project, not a whole project

Remote content is a different concept to using a separate Git repository as the source of truth for your Redocly project. Use remote content to bring in additional sources to add to your main project. Read more information about content sources.

The following diagram shows how a remote content source can fit into your Redocly project:

In this example, extra/ is the mount folder. The contents of the mount folder are copied from the contents of the remote content source whenever it updates. Changes should not be be made in this directory in the project, but instead update the remote content source and the changes are copied in.

Mount folder

The mount folder or mount point is where the remote content is placed relative to the root of your repository. When you use the New remote folder command, you create a folder that serves as the mount point for the remote content.

For example, adding a remote folder to docs and naming it openapi, creates a remote folder the contents of which are pulled into your Reunite project from a remote location.

├── docs
│   └── openapi
│       ├── index.md
│       └── translations.yaml

Remote content overwrites existing files/folders

If a remote content source is created using a non-empty folder as a mount path, the existing content will be overwritten.

There are some restrictions on how remote content folders can be used:

The mount path cannot be changed after it has been created. Create a new remote content entry and remove the existing one if you need to rename it.
Each mount point can only contain one remote content source.

Nested remote content

If you add a remote content folder inside of another remote content folder, Redocly overwrites the nested remote content each time the parent remote content folder is updated. The nested remote content folder is re-created when it receives its own update.

If a nested remote content folder has the same name as a folder on the same level, it overwrites the contents of that folder each time it receives updates.

Content sources

Remote content can be added from a Git repository, a publicly-available URL, or pushed from your own platforms to Redocly in the following ways:

Use our GitHub application on the organization where the remote content is for the simplest setup.
For other Git integrations, use an access token to grant Redocly access to the remote content.
Remote file sources can be fetched by URL if the resource is publicly available. Use this approach to include API descriptions that are already published in your documentation.
For projects where Redocly does not have access, use CI/CD integration to push changes to your project in Redocly. This approach is also appropriate if the content is in a Git repository that Redocly doesn't have any access to.

More information about each type of content source can be found in the following sections.

Use a Git integration

Git as a remote content source allows you to connect to and continuously synchronize either an entire repository or a specific sub-folder in that repository.

To add remote content from Git, you need to supply a number of details:

repository organization (GitHub/Azure) or namespace (GitLab)
repository (GitHub/Azure) or project (GitLab) name
branch name
(optional) folder name if the content to use is in a single folder

Read the how-to guide for setting up remote content on your provider.

Remote contents repository folder

If you select to only include a specific folder from a repository, only files listed in the folder are included in your Redocly project. Project builds are started only when a branch contains changes to connected folder.

Pull requests and remote branches

When you open a pull/merge request against the branch that is a remote content source, Reunite fetches the proposed changes and does the preview changes verification process with the branch.

When a pull/merge request is merged to the branch that is a remote content source, Reunite performs the production changes verification with the new changes on that branch.

Use a URL for a remote file

Use a URL as remote content to synchronize a publicly-available file with the project's repository. To set up the URL as a remote content source, you need to specify:

the URL that the file is found.
the fetch frequency (from 15 mins to 12 hours), set a smaller interval for resources that change often.

The file is downloaded at the specified interval and compared to the existing file revision. If the files differ, Reunite does the production changes verification stage ("branching" does not exist in the scope of URL remotes).

Read the how-to guide for adding remote content by URL for detailed instructions.

Push content to Redocly

CI/CD (Continuous Integration / Continuous Deployment) is a remote content configuration where you can push content from another source to your Redocly project. The responsibility for configuring and executing the pushes is with the user; Redocly will receive and process the push events that are sent.

Add a CI/CD remote content source in Reunite and you will be guided through setting up either a GitHub action or a CLI push command that you can run in your CI/CD pipeline.

When changes are pushed, if the push --branch and --default-branch values match, Reunite runs the production changes verification steps. For any other branch, the preview changes verification process is triggered. The "auto-sync" setting does not apply to this type of remote content.

Read how to push remote content to Redocly for detailed instructions.

Auto-sync and Auto-merge

There are some options to configure how the remote content is adopted into the Redocly project.

Auto-sync: configures the system behavior when changes are made to remote content:
- For remote content in Git repositories, enabling Auto-sync means that pull requests are created automatically in Redocly when pull requests or branch changes are detected on the remote content repository. For changes to the default source branch for remote content, the Auto-merge rules then apply.
- For remote content on a URL, a pull request will be created with the updated content, and auto-merge rules apply.
- For pushed content, the auto-sync setting is not used.
Auto-merge: automatically merges the pull request to the default branch if all tests pass.

Branch protection rules and auto-merge

In order for Auto-merge to be used, the destination repository must not have branch protection rules that cannot be met. Make sure that there are no manual checks, required reviews, or other steps that could block Redocly from merging the changes.

Remote content statuses

Remote content sources are listed under "Remote content" page in the project dashboard, and the status for each is shown there.

In preview: An "In preview" status means the remote content has been added to the project's non-default branch. All subsequent remote content updates are applied in place to the same branch and pull request (as long as Auto-sync is enabled) until the pull request with the remote content files is reviewed and merged.

Enabled: When the remote content files are merged to the main branch, the status is "Enabled". If Auto-merge is enabled, it takes effect at this point.

How to add remote content to your project.
Remote content verification processes are performed automatically.
Connect a Git remote to source an entire project from an external repository while still using the editor and other Reunite features.