Track pull requests in your SCM system

If your CI server works with a source control management (SCM) system using pull requests, ALM Octane can help you track pull requests that are related to your backlog items. ALM Octane enables you to track pull requests in your SCM system via Jenkins, GitLab, or GitHub Actions.

Overview

ALM Octane enables you to track pull requests in your SCM system via Jenkins, GitLab, and GitHub Actions, to get details on their impact on release and build quality. For example, if QA wants to verify that a feature is complete, they can check that all pull requests were merged and there are no open pull requests.

You can also see details on pull requests made in the context of a feature and its user stories, and whether it was merged to the master branch.

The following SCM tools are currently supported:

  • Bitbucket Server

  • Github Cloud

  • Github Server

Back to top

Prerequisites

To track pull requests you must fill the following prerequisites:

  • Pull requests are supported in ALM Octane using Jenkins plugin version 6.2 and later, and GitLab service v1.1.125 and later.

  • ALM Octane associates a pull request with a related feature, user story, quality story or defect, based on its commit patterns, title, and description. Features also show pull requests based on the commits of child entities, and those manually associated with the feature.

  • When committing a change to your SCM system, the commit message or pull request should include one of the patterns defined on the DevOps > SCM Change Patterns settings page. You can modify the default commit message and pull request patterns using Java regular expressions. For details, see Customize SCM change patterns.

Back to top

Configure a pull request collector job in Jenkins

To begin, create a job in Jenkins to collect pull request details from your SCM into ALM Octane.

To configure a pull request collector job:

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

  2. In the ALM Octane area, enter the ALM Octane URL and workspace where pull requests will appear.

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

  3. In the 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. Select the checkbox Use SSH format if all the jobs that use this repository, and are connected to ALM Octane pipelines, use SSH format.

    It is important to be 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. (Optional) Each pull request has a source branch and a target branch. To filter specific branches in the repository (for example to filter out private branches), use regex to define the Source branch filter. To filter the master branch, define the Target branch filter.

Modify default settings

By default, ALM Octane collects the pull requests that were added from the most recent data collection. To trigger a full collection of pull request data, set the parameter pullrequests_min_update_time to zero (0).

To turn off association of pull requests based on commits, set the parameter pullrequests_max_commits_to_collect to zero (0).

You can use other parameters as described in the plugin UI to modify the maximum number of pull requests, or commits per pull request.

Back to top

Get merge request data from GitLab

To get merge request data from GitLab, set up the integration between ALM Octane and GitLab as described in ALM Octane GitLab CI service. The following section describes this procedure at a high level.

Get merge request data from GitLab:

  1. Configure the ALM Octane GitLab CI service as described in the readme file.

    To get merge request data, define the following properties, as described in the readme file:

    • gitlab.mergeRequests.variables.publishMergeRequestVarName

    • gitlab.mergeRequests.variables.destinationWorkspaceVarName

    • gitlab.mergeRequests.variables.useSSHFormatVarName

    • gitlab.mergeRequests.mergeRequestHistoryFolderPath

  2. In your GitLab project, configure variables for each of the above properties, as described in the readme file.

Back to top

Get merge request data from GitHub Actions

To get merge request data from GitHub Actions, set up the integration as described in the integration readme file.

Add the pull_request triggering event to the workflow configuration.

Back to top

Track pull requests in ALM Octane

You can track pull requests in the context of features, backlog items, or teams.

Pull requests on Backlog entities

Within the Backlog module, the Development > Pull Requests tab displays details on the pull requests that are associated with ALM Octane features and backlog items using SCM commit messages. For each entity, you can see the following:

  • The pull request ID, name, and state.

  • When the pull request was created, whether it was merged, and when 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.

    By default, the SCM committer coming from the Jenkins plugin is the committer, and not the author. If your methodology requires you to get the author rather than the committer, you can use the property authorOrCommitter in the GitChangeLogParser of the Jenkins plugin. In the Jenkins job, select Additional Behaviors > Use commit author in changelog.

You can drill down to a pull request's details to see its source and target branch, and to access a link to the pull request in the SCM.

To manually associate a pull request with a feature or backlog item, within the pull request 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).

Note: Within a feature you see its directly associated pull requests, and those propagated by its user stories. At the feature level, you can only unlink pull requests that are directly associated with the feature (and not those that were propagated).

Pull requests in Team Backlog

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

You can filter these by team, team member, release, milestone, and so on.

Back to top

See also: