{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"azure-repos","__idx":0},"children":["Azure Repos"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 in Azure Repos."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will need the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/pricing"},"children":["Professional or Enterprise plan"]}," to connect to Azure Repos connection."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"connect-azure-repos-to-redocly","__idx":1},"children":["Connect Azure Repos to Redocly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly integrates by using a personal access token to authenticate to Azure Repos."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 log in 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."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log into your Azure Repos account, and under User Settings, create a personal access token. For more information, read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page#create-personal-access-tokens-to-authenticate-access"},"children":["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."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set permissions for the personal access token."]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom defined"]}," scopes.",{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must define the scopes correctly."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read & write"]}," code access."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set Web/Service hooks permissions."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/azure-pat-scopes-4220d793f6a01e0f.png","alt":"azure pat scopes","title":"#width=700px;"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you set an expiration on the personal access token, set yourself a reminder to generate a new token."]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Redocly, navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Source control providers"]}," page."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Scroll down to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Azure"]}," section of the page, and complete the details."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Organization name"]}," as it appears in your Azure account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter your personal access token you created in Azure Repos."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save Azure Settings"]}," to save your changes."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/org-settings-azure-settings-4c8eea145f7798a0.png","alt":"Org Settings Azure","title":"#width=600px;"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You've now connected Azure Repos to Redocly."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-access-token","__idx":2},"children":["Update access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To update your token:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the Source control provider page, under Azure, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Change"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add in your new token, and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Azure Settings"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/org-settings-azure-settings-update-2483cb43d4bcd5c4.png","alt":"Org Settings Azure Settings","title":"#width=500px;"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"disconnect-azure","__idx":3},"children":["Disconnect Azure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To disconnect the integration between Azure Repos and Redocly, on the Source control provider page, under Azure, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Disconnect Azure"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-project","__idx":4},"children":["Create a project"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have set up Azure integration, you can create a new project and select Azure as a source for your registry."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using Workflows, from the API registry screen, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add API"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter a name and version for your API, and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next"]}," to continue."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Choose source"]}," page, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Azure"]}," as your source."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/choose-source-azure-3dae7ce1dd35e6b0.png","alt":"Choose Source Azure"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next"]}," to continue to the next screen, where you select your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Repository"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Source settings"]}," page, select the repository, and your production branch."," ","We recommend selecting the *",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Build PR as previews"]},", which will trigger workflows to build a preview of your docs."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/source-settings-azure-a6f895cb578b28e7.png","alt":"Source Settings Azure"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next"]}," to save your changes."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"test-azure-repos-with-your-project","__idx":5},"children":["Test Azure Repos with your project"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section provides a follow-along demo of using the Azure Repos connection."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prerequisites","__idx":6},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An Azure Repo with a valid OpenAPI definition or Developer portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A project, configured with the *",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Build PR as previews"]},", as described above."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"trigger-a-preview","__idx":7},"children":["Trigger a preview"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using your existing Azure tools, clone your repo."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a branch, and make a minor change."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Commit and push to the Azure Repos origin."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open a pull request."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using Redocly, navigate to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Project overview"]}," or the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Project builds"]}," screen. A preview build should be triggered."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/project-overview-preview-5cce10ffa2cc105f.png","alt":"Project Overview Preview"},"children":[]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon completion you should see a comment on your pull request with a link to the preview of your docs."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Service user accounts"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the example, we used 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 is considered a good practice to create a service user."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the build completes and is successful, Redocly posts a comment from the service user with the link to the preview."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/azure-build-success-92d854e111b6ecfb.png","alt":"Azure Build Success"},"children":[]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/azure-build-failed-9dc2f9a73933f97c.png","alt":"Azure Build Failed"},"children":[]}]}]}]}]},"frontmatter":{"excludeFromSearch":true},"tagList":["admonition","partial"],"title":"Azure Repos","lastModified":"2025-05-28T16:01:32.000Z"}