External SCM Services in codebeamer

External SCM Repository Overview

codebeamer enables using external SCM services. To create and manage external SCM repositories, the user must have project administrator role. The use of external SCM repositories must be enabled in the application configuration. Once enabled, the project administrator can manage the SCM-related trackers in a project. These trackers are hidden, only users with the following roles have access to them:

• Project Admin role: read and write permission
• SCM View role: read permission

The SCM - View role is available from the codebeamer 22.10-LTS (GINA) release.

Enabling External SCM Projects

To enable the external SCM feature in codebeamer, the following line is to be added to the application configuration:

"externalProviderScm" : { "enabled" : true }

For more information, see Application configuration.

Application Configuration Options

The external SCM feature options have the following default values:

"externalProviderScm" : {
	"enabled" : true,
	"repositorySynchronizationPeriodInSeconds" : 3600,
	"synchronizationCyclePeriodInSeconds" : 60,
	"fetchPageSize" : 100,
	"jobDoneCommentEnabled" : true
}

Access Tokens

For more information on GitHub access tokens, see GitHub Docs.

Only the repo segment needs to be selected.

To add an access token, do the following:

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

Add an External SCM Repository

An external SCM repository can be added either in the SCM Repositories tab of a project or in the SCM tracker. Before adding a new external repository, ensure that the feature is enabled in the application configuration.

To add a new repository in the SCM Repositories tab, do the following:

1. Go to the SCM Repositories tab of a project.
2. Click New External Repository.
3. Fill in the name of the repository and the access token. When a token already exists, skip this step and select the token in the next step.
4. Fill in the following information:
   • Name: The name of the repository in codebeamer (can be anything).
   • Status: Enable or disable background synchronization, or show error state.
   • Access token: Select the created access token.
   • SCM Type: The provider of the SCM repository. Only GitHub is supported.
   • Remote API url: Public or on-premise API URL. For GitHub URL, see https://api.github.com/.
   • Owner name: The user name or organization name of the repository owner.
   • Repository name: The name of the repository in GitHub.
   • Enable patch synchronization: Enable or disable commit file change synchronization. The result is not shown on the user interface.
5. Click [Save].

To add an external SCM repository in the SCM Repository tracker, do the following:

1. Go to the Trackers ► SCM Repository Tracker ► New item.
2. Fill in the fields.
   
   • Mandatory values:
     • Status: Enable or disable background synchronization, or show error state.
     • Access token: Select the created access token.
     • SCM Type: The provider of the SCM repository. Only GitHub is supported.
     • Remote API url: Public or on-premise API URL. For GitHub URL, see https://api.github.com/.
     • Owner name: The user name or organization name of the repository owner.
     • Repository name: The name of the repository in GitHub.
     • Enable patch synchronization: Enable or disable commit file change synchronization. The result is not shown on the user interface.
     • Summary: The given name of the repository.
   • Values to be added after synchronization:
     • Base repository: Link to the base repository if it exists in the application. The repository is a fork.
     • Remote id: The SCM internal remote id of the repository.
     • Last synchronization date: The date of the last background synchronization.
     • Html URL: Link to the repository page of the external provider.
     • Default branch: Single mandatory branch for an external repository that can be viewed in the branch section.
     • First commit hash: First, usually init, commit revision id of the repository.
     • Fork: Shows whether a repository is considered to be a fork on the external provider.
3. Click [Save].

Background Processes and UI Actions

With project administrator rights, the following actions are available for external repositories:

• Edit access token
• Scm repository update synchronization
• Scm repository full synchronization
• Scm repository cleanup
• Scm repository delete
• Scm repository dangling commit cleanup
• Scm repository commit patch synchronization
• Scm repository full commit patch synchronization

If the background synchronization is enabled, it periodically updates the repository. (Fetching missing branches, commits, removing deleted ones, remove dangling commits, and update commits patches). These background processes can be triggered by opening the options on the Repository Details view, and by bulk on the Repository Tracker table view. The update processes only fetch changes that are new to the repository, while the full synchronizations remove all items and re-synchronize the whole repository. The dangling commit cleanup removes the remaining commits after branch deletion. The cleanup job removes all the related items from the repository (commits, branches, tags), and disables the repository preventing further synchronization.

Webhook

Webhook can be configured to send changes made in the external repository to codebeamer application.

• The Webhook path is: /scm/webhook/{projectKey}/{provider}.json
• The GitHub path is: /scm/webhook/github.json

Setting New SCM User Keys in the User Account

To record a new SCM user keys, do the following:

1. Go to My Start ► My Account ► Edit Account.
2. Fill in the related details once the external repository is created.
3. Click [Save].