External SCM - Azure Repository

This page demonstrates the process of setting up an Azure External SCM repository.

Azure is supported as an external SCM service provider.

Application Configuration

To be able to create an external SCM repository, the below configuration must be set in the Application Configuration:

"externalProviderScm" : {
	"enabled" : true
}

Access Token

For more information on Azure access tokens, see Use personal access tokens - Azure DevOps. When creating access tokens in Azure, Full access permission must be given. To create and edit access tokens in Codebeamer, Project-Admin role is required.

Create Access Tokens

To add an access token,

1. Copy and paste the token into the Token field of the new Access token tracker item.
2. Click Save.

For security reasons, the access tokens for all service providers are encrypted. The encryption is kept after upgrades as well.

On the SCM Access Token Tracker page, when pasting the access token to Token field, the token is visible. After clicking Save, the token is immediately encrypted.

Edit Access Tokens

To edit the encrypted access token,

1. Go to the SCM Access Token Tracker > click the relevant token.
2. The Token field contains the encrypted access token.
   Example: AD-95-AD-A4-F9-91-H2
3. Double-click the value of the Token field.
4. Add the new token.
5. Press Enter or click on an empty area to save the changes.

The History tab displays the changes, and due to the encryption, the actual tokens are never revealed.

If a repository has already been created, the access token can also be edited via the SCM Repositories tab:

1. Click tab SCM Repositories.
2. Click the relevant repository.
3. On the Repository Information page, click > Edit access token.
4. The SCM Access Token Tracker page opens with the encrypted access token.
5. Edit the value of the Token field.
6. Click Save.

Add a New External SCM Azure Repository

A new external SCM Azure repository can be added either in the SCM Repositories tab of a project or via the SCM Repository Tracker. Before adding a new external repository, ensure that the feature is enabled in the Application Configuration.

To add a new repository,

1. Click the SCM Repositories tab > New External Repository
2. On the SCM Access Token Tracker page,
   1. To create and save a new token in Codebeamer, add the details to the Name and Token fields, and then click Save.
   2. If the token has already been created, click Skip.
3. On the SCM Repository Tracker page, provide the mandatory values. Ensure that all the provided values are correct.
   All fields are mandatory.
   

   Field Name	Description
   Name	An arbitrary name for the repository in Codebeamer.
   Status	Enable or disable background synchronization, or show error state. Values: Enabled, Disabled, Error.
   SCM Type	The provider of the SCM repository. For Azure, set the value of this field to azurerepo.
   Access token	Select the created access token.
   Secret	The secrets are needed for the webhooks. The DEFAULT - NONE secret value is added to each repository by default. To change the secret, select the relevant one from the drop-down list. Custom secrets can also be created.
   Remote API url	The base API URL of the provider, from which Codebeamer calls the endpoints. For example: https://dev.azure.com.
   Owner/Organization name	In case of Azure, this is the organization name. For GitHub, this is the name of the GitHub user who owns the repository.
   Repository name	The actual name of the repository in Azure.
   Enable Patch synchronization	Whether commit patch synchronization is required or not.
   Project name	In case the SCM Type value is set to azurerepo, the Project name field is added to the list because of the structural differences compared to GitHub.

4. Click Validate
   Codebeamer sends a request with the provided values to the Azure API, and if the response confirms the authenticity of the values, the validation is successful. Otherwise, an error message is displayed and the Save button is disabled until the correct values are provided. For example, the following error message is displayed if the Access token field is left empty: "Validate error: Required request parameter ‘accessTokenId’ for method parameter type Integer is present but converted to null."
5. Click Save to create the new repository.

External SCM repositories can also be created via Swagger API. For further information, see page Create an External SCM Repository Item.

Edit An External SCM Azure Repository

The values provided during the creation of a repository can be updated if necessary.

To edit the details of a repository,

1. Click tab SCM Repositories and click the name of the relevant repository.
2. The Repository Information page opens, listing all the fields and field values provided for the creation of the repository.
3. Click on the top left corner to open the SCM Repository Tracker page where the field values can be edited, and make the necessary changes.
4. Click Validate to check whether the provided or updated values are correct.
   • If the validation fails, double-check and correct the values.
5. Click Save to finish editing the repository details.

External SCM repositories can also be edited via Swagger API. For further information, see page Update an External SCM Repository Item.

Repository Information

Once an Azure repository is created, its details can be checked and edited:

1. Click tab SCM Repositories and click the relevant repository.
2. The Repository Information page opens.

In case of Azure, clicking the link in the Url field, for example Repository #12345, opens the last visited branch in Azure, instead of the main branch.

Synchronization of the Azure Repository Details

Set up the synchronization details in the Application Configuration.

Example configuration:

"externalProviderScm" : {
	"enabled" : true,
	"jobDoneCommentEnabled" : true,
	"repositorySynchronizationPeriodInSeconds" : 1800,
	"synchronizationCyclePeriodInSeconds" : 1800,
}

The following table lists and describes the parameters of the configuration:

Update Synchronization - Limitation

When performing an SCM repository update synchronization, the Azure API response returns only the creation and merge dates. The last update date of the pull requests is not returned as this function is not supported by the API.

Full Synchronization

The SCM repository full synchronization option has been added to the context menu of the Repository Information page.

The SCM repository full synchronization first deletes the available data, then retrieves the whole dataset again. Since using the SCM repository full synchronization option is much more time-consuming than the SCM repository update synchronization, the following warning is displayed: "Are you sure that you want to do full synchronization? It will retrieve all the details again."

To perform a full synchronization,

1. Click tab SCM Repositories.
2. Click > SCM repository full synchronization.
3. Click Yes on the pop-up warning dialog.

Webhooks

To set up a Webhook in Azure,

1. Go to Project Settings > General > Service Hooks.
2. Click to create a new subscription, or > Edit to update an existing one.
3. The NEW SERVICE HOOK SUBSCRIPTION or EDIT SERVICE HOOK SUBSCRITPTION wizard opens.
4. Select the relevant option from the Trigger on this type of event drop-down list.
   For example: Pull request created.
   When a pull request is created in Azure, a payload including the item ID is sent to Codebeamer. After Codebeamer validates the sent JSON file, the change made in Azure is displayed under the SCM Commits tab of the related Codebeamer item.
5. In section Filters, set further conditions if necessary. For example: Repository, Target branch.
6. Once the relevant options are selected, click Next.
7. On the next page of the wizard, go to section Settings > URL field.
8. Add the payload URL in the following format:
   testInstanceURL/scm/webhook/{projectKey}/{azure}.json
   Where projectKey is the KEY value which can be set on the Admin page of the relevant Codebeamer project.
9. Secrets can be added to the HTTPS headers field in the following format:
   X-Secret:mysecret
   Where mysecret is the same value as the secret saved in Codebeamer.
10. Set other optional filters if necessary.

For further information, see Webhooks with Azure DevOps.

Update Codebeamer Item Statuses Based on Pull Request Statuses

The statuses of Codebeamer items are updated based on the statuses of pull requests. Status updates must be set in the Application Configuration.

Application Configuration

The followings must be set in the Application Configuration:

 "statusMapping" : {
        "inOpenTransition" : "In Progress",
        "inMergedTransition" : "Resolve",
        "inClosedTransition" : "Close",
        "projectId" : 12,

    },

The following table lists and describes the parameters of the configuration:

To apply different status update settings for another project, the proper parameters with the correct values as well as the relevant project ID must be defined separately in the Application Configuration.

For example:

 "statusMapping" : {
        "inOpenTransition" : "In Progress",
        "inMergedTransition" : "Resolve",
        "inClosedTransition" : "Close",
        "projectId" : 12,

        "inOpenTransition" : "In Progress",
        "inMergedTransition" : "Resolve",
        "inClosedTransition" : "QA Pass",
        "projectId" : 14,
    },

Assign Reviewers to Pull Requests

Required and Optional reviewers can be assigned to pull requests in Azure. Reviewers can be users, teams and groups as well.

To assign reviewers to a pull request,

1. Click Repos > Pull requests
2. On the right-hand side Reviewers section, add the Required and, if needed, Optional reviewers.

If reviewers are assigned to a pull request in Azure, the user, team or group set as reviewers are indicated along with the pull request details under the SCM Commits tab of the related Codebeamer tracker item.

The Required Reviewers in Azure and the Optional Reviewers in Azure fields have been added to the item details page of the SCM Pull Request Tracker items.

The name of the reviewers in the Required Reviewers in Azure or Optional Reviewers in Azure fields are clickable links. By clicking the name of a reviewer, the Azure profile of the reviewer opens.