Track branches in your SCM system

ALM Octane can help you track branches that are related to your backlog items.

For example, if you create a custom branch to develop a feature, you can check commits and pull requests in the branch. QA can then verify whether the branch is merged.

Overview

ALM Octane enables you to track branches in your SCM system via Jenkins, and get details on their impact on release and build quality. For example, you can see details on branches in the context of a feature and its user stories, and whether it was merged to master.

When a branch is injected by the Jenkins plugin, all of its related data is displayed in ALM Octane. If a branch is injected via a commit or a pull request injection, only the branch name and related item appear.

The following SCM tools are currently supported:

  • Bitbucket Server

  • Github Cloud

  • Github Server

Back to top

Prerequisites

To inject branches and associate them with backlog items, ALM Octane requires the following:

  • Branch injection is supported with Jenkins plugin version 6.9 and later.

  • ALM Octane associates a branch with a related feature, user story, quality story or defect, based on its message patterns. Features also show branches based on the commits of child entities, and those manually associated with the feature.

  • When committing a change to your SCM system, the branch name should include one of the patterns defined on the DevOps > SCM Change Patterns settings page. This enables ALM Octane to associate a branch with a related feature, user story, quality story or defect, based on its branch name pattern. For details, see Customize SCM change patterns.

Back to top

Configure a branch collector job in Jenkins

Create a job in Jenkins to inject branch details from your SCM into ALM Octane.

To create a branch collector job:

  1. In Jenkins, configure a job with a post-build action called ALM Octane branch collector.

  2. ALM Octane area. Enter the ALM Octane URL and workspace where branches should be injected.

    You can copy the URL from the address bar of the browser in which you open ALM Octane.

  3. SCM Tool area. Enter your SCM tool type, repository URL, and repository credentials.

    Bitbucket Server and Github Server support both user/password and PAT (Personal access tokens). Github Cloud supports PAT only. For further details, refer to the help inside the Jenkins plugin.

  4. Use SSH format. Select the checkbox if all the other jobs that use this repository, and are connected to ALM Octane pipelines, use SSH format.

    Note: Make sure that the SSH format setting is consistent with other jobs that use this repository. This ensures that ALM Octane correctly identifies the SCM repository associated with commits, branches and pull requests.

  5. Branch filter (Optional). Use regex to filter specific branches in the repository.

To modify default settings:

By default, ALM Octane collects branches that were active during the last 90 days. To modify, use the parameter branches_active_branch_days.

Back to top

Track branches in ALM Octane

You can track branches in ALM Octane in the context of features, backlog items, or teams.

Branch details in Backlog

In the Backlog module, the Development > Branches tab displays details on the branches that are associated with ALM Octane features and backlog items using SCM commit messages. For each item, you can see the following:

  • The branch ID, name, and repository.

  • Last commit version, last committer, and whether it was merged.

  • The associated backlog items. Click a backlog item's ID if you want to open the item and view its details.

  • The pull request message, source branch, and SCM user.

    Tip: To filter by user, make sure your SCM users are mapped to ALM Octane users. For details, see Map SCM users to ALM Octane users.

If you see partial details on a branch, this indicates that the details came from an associated commit or pull request, and not from the branch injection.

You can drill down to branch details to access a link to the branch in the SCM.

To manually associate a branch with a feature or backlog item, within the branch details pane click Link to Backlog Items. To remove a link, click Unlink to Backlog Items (in the context of a feature, user story, quality story, or defect).

You can also click Link to Branches from the context of a feature, user story, quality story, or defect. Automatically any related items will also be linked to the branch, giving you traceability.

Note: ALM Octane associates a features both with its directly associated branches, and those propagated by its user stories. At the feature level, you can only unlink branches that are directly associated with the feature (and not those that were propagated).

Branches in Team Backlog

In the Team Backlog module, the Development > Branches tab shows all the branches in the workspace, including those that are not associated with a specific feature or backlog item.

You can filter branches by team, team member, release, and milestone.

Back to top

Create Branch external action

You can use the Create Branch external action to create a branch in your SCM repository from within an ALM Octane entity. This enables you (for example) to create a feature in ALM Octane, and then select the Create Branch menu command to create a branch in your repository for this feature. For details, see Add external actions.

You can use the SCM Change Pattern settings to name the branch using your branch naming template. For details, see Customize SCM change patterns.

The following SCM systems are currently supported: Bitbucket Server, Bitbucket Cloud, and Github Cloud.

For configuration details, see ALM Octane Create Branch External Action.

Back to top

See also: