Azure Repos Integration
Number of APIs: 5
Introduction
This collection is used to create a repository in Azure Repos, upload a Qodex collection to that repository, and commit collection changes to that repository. The intended functionality of this integration is for each copy of this integration to run a separate monitor on a distinct collection that the user wants uploaded to Azure repos. This integration, when paired up with a monitor for a specific collection, can be used to track that specific collection across multiple branches and repos by stating the branch name and repo name in the environment for that monitor.
Note: This integration does not support renaming files or directories after they have been committed to Azure Repos. If the user would like to change the current fileName or directoryName to something different after the initial commit to a branch has been made, the user will have to start with a new branch.
This integration also does not support pushing to repositories that have been manually created or edited in Azure Repos because manual changes cause the auto-generated variables to not be up-to-date. In order to prevent these errors, please create repositories and make commits through this integration, rather than manual changes.
Prerequisites
This collection requires that you have done the following:
- Made an account in Azure DevOps
- Created an organization in your DevOps account
- Created a project in your DevOps organization
- Generated a Personal Access Token in your DevOps project (can be generated by going to User Settings, clicking Personal Access Tokens, and clicking New Token)
Monitors
In the integration, a monitor is used to automatically check to update the changes made to a collection once a day.
In order to make this monitor, input the desired Monitor Name, select the Azure Repos Integration collection as the Collection. Select the Azure Repos environment as the environment and select how often you want it to be run to check if your collection has been updated (we recommend once a day). Then, your monitor should be created ([learn more about creating a monitor here]
Mocks
If you would like to see example responses and run and interact with the collection without having to input valid credentials, you will need to create a mock server. You can do this by left clicking on your forked version of this integration and selecting Mock Collection ([learn more about creating a mock server here]
Then you will also nee to fork the [MOCK] Azure Repos environment. Copy the mock server url and assign it to the environment variable mockUrl. If you run the collection with the mock environment selected, it will show you what a successful request looks so long as you fill out the environment variables with the correct variable type.
Workflow Diagram
Environment Setup
To use this collection, the following environment variables must be defined:
| Key | Description | Kind |
|---|---|---|
x-api-key | Your Qodex API key ([learn more about the Qodex API here] and get your Qodex API key here) | User input |
collectionUID | The ID of the Qodex collection that you want to upload to Azure Repos (found under the info tab of the collection) | User input |
collectionContent | The content of the Qodex collection that will be uploaded to Azure Repos | Auto-generated |
organization | The name of the organization that you created in your DevOps account | User input |
project | The name of the project that you created in your DevOps organization | User input |
password | The Personal Access Token that you generated in your DevOps project | User input |
repositoryId | The name of the repository that you want to upload to in Azure Repos | User input |
previousCommitId | The ID of the previous commit made to the given repository and branch | Auto-generated |
fileName | The name of the collection that will be uploaded to Azure Repos | User input or Auto-generated if not specified |
directoryName | The name of the directory that commits will be made to in Azure Repos | User input or Auto-generated if not specified |
branch | The branch that you want to commit changes to in Azure Repos (default is refs/heads/main if none provided) | User input or Auto-generated if not specified |
projectId | The ID of the project that you created in your DevOps organization | Auto-generated |
changeType | The type of change that you are making when you make a commit to Azure Repos. Supported change types include: add, edit, delete | Auto-generated |
baseCollection | The base URL used to retrieve a Qodex collection | Auto-generated |
baseRepo | The base URL used to make all calls to Azure Repos | Auto-generated |
base64Collection | The base-64 converted version of the Qodex collection with the given UID | Auto-generated |
Note: If the Create Repo and Push Collection requests are run with a branch or repo that has not been created, a new variable with the key {{Repository Name}}/{{Branch Name}}/previousCommitId
will be auto-generated. For example, if a newly created repository with the name Testing
has the branch name refs/heads/main
, a new variable with the key Testing/main/previousCommitId
will appear, which will be used in the Push Collection Request. These variables allow the user to fluidly transition between branches and repositories and are auto-generated, so the user does not have to worry about manually changing these variables.
Additionally, when the Get Collection request is run with a branch or repo that has not been created, a new variable with the key {{Repository Name}}/{{Branch Name}}/collectionContent
will be auto-generated. These variables allow the integration to upload different Qodex collections to the given branch and repository names.
Furthermore, if the Get Collection request fails because a Qodex collection is deleted, the corresponding file on Azure Repos is deleted. To track whether the file has been deleted, a new variable with the key {{Repository Name}}/{{Branch Name}}/collectionDeleted
will be auto-generated in the environment. When there is a commit to create a file, this variable will be set to Not Deleted
. If the Delete Collection request is run, this variable will be set to Deleted
.
Branches
To specify a particular branch that you want to push to, fill in the branch environment variable using the format refs/heads/{{Branch Name}}
. For example, if you wanted to push to a branch named second
, branch would be set to refs/heads/second
.
-
Get Project ID GET {{baseUrl}}/{{organization}}/_apis/projects?api-version=6.0
-
Get Collection GET {{baseUrl}}/collections/{{collectionUID}}
-
Check Repo GET {{baseUrl}}/{{organization}}/{{project}}/_apis/git/repositories/{{repositoryId}}?api-version=6.0
-
Delete Collection POST {{baseUrl}}/{{organization}}/{{project}}/_apis/git/repositories/{{repositoryId}}/pushes?api-version=6.0
-
Create Repo POST {{baseUrl}}/{{organization}}/{{project}}/_apis/git/repositories?api-version=6.0