Azure Repos

Redocly is integrated with Azure Repos (which is part of Azure DevOps). You can trigger workflows in Redocly automatically when you commit or open a pull request.

attention

Azure Repos connection requires an enterprise-level Redocly plan.

Connect Azure Repos to Redocly

Redocly integrates by using a personal access token to authenticate to Azure Repos.

We recommend using a service user account. A service user is a user created in Azure Repos intended for use by a machine. You would login to the service user account to generate a personal access token for use by a 3rd party service (like Redocly). We recommend naming your service user "Redocly" or similar.

  1. Create a personal access token
attention

You must define the scopes correctly.

Set permissions for the personal access token. Select custom defined scopes.

  • Set read & write code access
  • Set Web/Service hooks permissions

azure pat scopes

Read the Azure docs to learn how to create a personal access token. Azure DevOps has a current and preview features environment which have different locations for finding where to generate your personal access token.

warning

If you set an expiration on the personal access token, set yourself a reminder to generate a new token.

  1. Navigate to the Org Settings > Source control providers page.

Org Settings

  1. Scroll down to the Azure settings section of the page, and fill the form. Enter the Organization name as it appears in your Azure account. Then, enter your personal access token that you created there. Select to Save Azure Settings.

Org Settings Azure Settings

You can update your token by selecting Change, changing your token, and then selecting Update Azure Settings.

Org Settings Azure Settings

You've connected Azure Repos to Redocly.

Create a project

You will be able to create a new project and select Azure as your source.

Choose Source Azure

Then click Next*- to continue to the next screen, where you select your **Repository.

Once you selected, you can select your production branch. We also recommend to select the *Build PR as previews- which will trigger workflows to build a preview of your docs.

Source Settings Azure

Finally, you will give your project a name.

Testing Azure Repos with your project

This section provides a follow-along demo of using the Azure Repos connection.

Prerequisites

  • An Azure Repo with a valid OpenAPI definition or Developer Portal.
  • A project, configured with the *Build PR as previews- as described above.
  • Git knowledge.

Trigger a preview

  1. Clone your repo, if you haven't already.
  2. Create a branch, and make a minor change.
  3. Commit and push to the Azure Repos origin.
  4. Open a pull request.
  5. Check the Project overview screen or the Project builds screen. A preview build should be triggered.

Project Overview Preview

  1. Upon completion you should see a comment on your pull request with a link to the preview of your docs.

In the example, we utilized a service user account. A service user is a user created in Azure Repos whose primary purpose is to generate a personal access token for use by a 3rd party service (like Redocly).

It's considered a good practice to create a service user.

When the build completes and is successful, Redocly posts a comment from the service user with the link to the preview.

Azure Build Success

If the build fails, Redocly posts a comment from the service user with a link the build logs where you can find more details for the cause of the failure (such as an invalid API definition).

Azure Build Failed

Having problems? Let us know.