Track changes committed to your Source Control Management system

If your Jenkins or Bamboo server is set up to work with a Source Control Management (SCM) system, such as Git or Subversion (SVN), ALM Octane can help you track committed changes. See also Supported CI and SCM systems.

ALM Octane pipelines display the commits associated with each run of the pipeline.

In your SCM system, use commit messages to associate changes with specific ALM Octane stories (user stories, quality stories, or defects).

You can then view the following information in ALM Octane

  • In a pipeline run, the list of stories and commits associated with the pipeline run.

  • Inside a story, the list of commits related to the story.

  • Inside an epic or feature, the list of commits associated with stories defined under the epic or feature.

Use cases for tracking commits 

Here are a few ways that you can use commit tracking information:

  • As a developer, when you commit a change to your SCM system, enter a commit message with the ID of the defect, user story, or quality story related to this change.

    When the pipeline associated with your change runs, this information is passed to ALM Octane.

    When you open the stories in ALM Octane, you and your team leader get a clear picture of the files that you changed for each story you developed.

  • As a developer or DevOps engineer, match build failures to specific changed files and specific stories.

  • As a tester, after verifying that a pipeline build was successful and automated tests passed, determine the areas that contain significant changes and require manual testing.

Back to top

Prerequisites

  • Make sure the workspace admin or DevOps admin has created a pipeline on a CI server that works with an SCM system. For details, see Create and configure pipelines.

  • If you want to associate changes with ALM Octane stories, include the ID of the related ALM Octane story in your commit message.

    When committing a change to your SCM system, the commit message should include one of the Commit message patterns defined on the DevOps > Commit Patterns settings page. A workspace administrator can modify the default commit message patterns using Java regular expressions. For details, see Customize commit message patterns.

    The default commit message patterns are:

    defect #<defect id>

    user story #<user story id>

    quality story #<quality story id>

    The message syntax is not case sensitive.

    You can also associate your commit with multiple stories, like in these examples:

    Defect #1001, User story #1002: I changed all of the blue icons to green ones.

    Fixed the issue of screen not refreshing. Defect #1001, Defect #1002.

Back to top

Track commits associated with a pipeline run

  1. In the Pipelines module, open the Pipelines tab and select a pipeline.

  2. Open a specific pipeline run:

    • To open the last or current run, click the number to the right of the pipeline name.

    • To open a previous run, click the pipeline's ID to open the pipeline. In the Runs tab, click the ID of a specific run.

You can find the following information:

  • In the Commits tab, view the commits associated with the pipeline run. For more details, see Use the Commits tab to track committed changes.

  • In the Stories tab, view the stories that were associated with the pipeline run using commit messages in the correct syntax.

    For each story, you can see information about the story and the associated commit. For example:

    • The story's ID, name, and phase.

    • The number of commits associated with the story.

    • The names of the users who committed the changes.

    • The number of files added, modified, or deleted by those commits.

    Click a story's ID if you want to open the story and view more details.

If the build is configured to notify committers upon build failure, users receive an email if a build that included their commits fails.

You can edit this option in the pipeline's Details tab. DevOps admin permissions are required.

Each user receives an email about their own commits. The email lists the commits, the failed builds, and the failed tests (limited to a certain number of items). It also includes a link to the relevant pipeline run's Failure Analysis tab.

Back to top

Track commits associated with backlog items

To track commits associated with backlog items, do one of the following:

Back to top

Use the Commits tab to track committed changes

The Commits tab displays all changes that were associated with ALM Octane stories using SCM commit messages in the correct syntax.

You can find the Commits tab inside a pipeline run or a backlog item:

  • In a pipeline, click the pipeline ID to open the pipeline. In the Runs tab, click the ID of a specific run to open it. Select the Commits tab to see the commits associated with this pipeline run.

  • Open a backlog item by clicking its ID.

    Tip:  You can open backlog items from many places in ALM Octane. For example: Backlog, Team Backlog, Defects.

    Select the Commits tab in stories (defects, user stories, and quality stories) to see the commits associated with the story.

    Select the Commits tab in epics and features to see commits associated with stories defined under this epic or feature.

In the Commits tab:

For each commit, you can see additional information, such as the name of the user who committed it, the commit message (comment), and more.

  1. Optionally, add columns to the grid to see more information.

    Note: The Repository column is only relevant if you are working with Git or SVN.

  2. You can filter the information in this tab, for example, by the name of the user who committed the change.

    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 are the user who committed the change, but your SCM user is not yet mapped to your ALM Octane user, click Map SCM user to my ALM Octane user to create the mapping.

  3. Select a specific commit. The list of files included in this commit is displayed on the right. If the SCM system provides the information, ALM Octane differentiates between edited, added or deleted files.

  4. For each changed file listed in a Commits pane, ALM Octane can provide HTTP links to the file view and diff view in your repository viewer. To enable this, a workspace administrator must configure templates for the HTTP links. For details, see Enable linking to your repository viewer (Git or SVN only).

Back to top

Use the dashboard to analyze your commit activity

Create custom widgets based on commits in the Dashboard or the Backlog Overview.

Alternatively, use the predefined widgets that ALM Octane provides in the Dashboard's DevOps & Analytics category.

For example: 

  • Use the Commits by feature, Commits by story, and Commits by application module widgets to discover the impact of source code changes.

    Discover which backlog items and application modules were worked on recently, and see the number of commits related to each. This can also give you an idea of the areas that need to be tested more thoroughly.

    Note: The association of commits with features and application modules is made via the user story or defect mentioned in a commit's message.

  • Use the Commits by team and Daily commits by repository to analyze commit activity and understand trends of commits over time.

Note: By default, several of these widgets include commits made in the last 30 days. You can change the time frame in the Scope tab of the widget editor.

Back to top

Map SCM users to ALM Octane users

Identifying the users who commit SCM changes as ALM Octane users enables you to analyze the commit information using ALM Octane widgets, filters, and so on.

If the email address defined for an SCM user is identical to the one defined for an ALM Octane user, the users are mapped automatically when changes they commit are discovered.

Otherwise, your shared space administrator can map the users manually. For details, see Map ALM Octane users to SCM users.

Alternatively, individual ALM Octane users can map themselves to unmapped SCM users listed in Commits tabs. For details, see Use the Commits tab to track committed changes.

Back to top

Troubleshooting

  • I don't see any commit information on a pipeline step

    Information about commits is displayed on a pipeline step only after the step finishes running.

  • On-premise: I don't see any commit information on the pipeline

    If the ALM Octane server was restarted while the pipeline was running, change information will be available only after the pipeline runs. Try running the pipeline again.

  • I don't see any commits associated with my backlog items, or vice versa

    Make sure your commit messages follow the correct syntax.