BuildMaster Documentation

Issues and Project Tracking

Many projects rely on issue tracking tools to manage changes in applications, and integrating these tools into BuildMaster offers several advantages:

  • Prevent deployment unless all related issues are resolved/closed
  • Automatically change the status of related issues
  • Add comments to issues indicating when they were deployed
  • Create new issues to indicate that testing is required
  • See all relevant issues on the release dashboard in BuildMaster

The Issue tracking integration is implemented through an extensible feature, and additional tools may be supported by building extensions.

Issue Tracker Automation

Most issue tracking tool extensions have operations that can be use in a deployment plan to create, query, and modify issues. Each issue tracking tool is different, but there are generally four operations available in each extension:

  • Create New Issue
  • Change Status/State
  • Append Comment/Note
  • Query/Find Issues

The create, change, and append operations each will target a single issue by ID, which is why the query operation is important: it returns a list of issues that you can use to update multiple issues.

For example, you can use the following OtterScript to query for all Tested issues in the current release, and then change their status to Deployed while adding a comment.

  • Visual Mode
  • Text Mode (OtterScript)
An Issue operation Plan Block (Visual Mode)
YouTrack::Find-Issues
(
    Credentials: CorpYouTrack,
    Project: HDARS,
    Filter: Fix version: $ReleaseNumber State: Tested,
    Output => @YouTrackIssueIDs
);
        
foreach $IssueId in @YouTrackIssueIDs
{
    YouTrack::Change-Issue-State
    (
        Credentials: CorpYouTrack,
        IssueId: $IssueId,
        State: Deployed
    );
        
    YouTrack::Add-Comment
    (
        Credentials: CorpYouTrack,
        IssueId: $IssueId,
        Comment: Automatically updated by BuidMaster
    );
}                                                   

This same approach can be used with other extensions as well.

Issues in BuildMaster

BuildMaster has an internal issue store that is periodically synchronized with external issue tracking tools that you've configured. This issue store tracks the following information about each issue:

Issue Id: the human-readable identifier, such has HDARS-1281
Type: text representing the category of issue, such as Bug or Feature
Status: text representing the issue's status, such as Open or Resolved
Closed: A boolean indicating whether the issue is considered closed; several statuses may indicate this state
Title: a brief description of the issue, such as "FIX: Account Status may be incorrect"
Description: a longer description of the issue, containing details
URL: URL directly linking to the issue in the tool, so that it can be clicked on from the BuildMaster user interface

You can view all issues associated with an application by going to the "Issues" tab on the application navigation bar. Issues related to a particular release or release package are displayed on those pages.

Issues Sources

The Inedo Execution Engine uses issue sources to perform background synchronizations with external issue tracking tools. Issue sources act as a filter that lists issues that are relevant for a particular release. Depending on the type of issue tracking tool, each issue source will have different fields that are specific to the tool.

A synchronization is always performed within the context of an active release. For example, if you configured an issue source for the HDARS application group, then BuildMaster would perform a synchronization for each active release in each application.

Creating Issue Sources

Issue sources can be configured at the application level on the "Issues" tab by clicking the "configure issue source" link, or under Administration > Issue Sources. Issue sources created outside of an application can target an application group instead of just a single application.

Issue sources require that you create a resource credential that provides connection information to the issue tracking tool, such as a URL, API key, username, etc. These credentials are generally shared across issue sources of the same type.

Variables and Issue Source Context

Because synchronization occurs within the context of a release, this means you can use any of the variable functions that rely on a release to be in context: $ApplicationName, $ReleaseNumber, $ReleaseName, $ReleaseNumberPart(), etc.

You can also use any configuration variables that are accessible from a release context: release, application, application-group, or system.

Automatically Blocking Deployments

There are two automatic approvals you can configure to on a pipeline that will prevent release packages from being deployed to a particular stage unless all issues are closed, or have a certain status such as "Resolved". Prior to deployment, these approvals will evaluate each issues associated with the release, and block the deployment if the approval is not met.

  • Issues in Status; if you specified a specific status texts (such as Resolved and Complete), any issue that doesn't have one of those statuses will cause the approval to be not met
  • Require Issues Closed; any non-closed issue will cause this approval to be not met

Like all automatic approvals, a release package may be forced into a stage even if issues aren't closed or in the appropriate status. However, this requires a special action and a specific permission.

Issue Synchronization

An issue synchronization will automatically occur when you visit the release or release package overview page. This is mostly transparent: a "please wait" status image is displayed while the execution engine runs the synchronization with the issue source. Once complete, the freshly synchronized issues that are stored within internal issue storage are displayed.

Manually Synchronization

When automatic issue synchronization behaves unexpectedly, (either due to an error or misconfiguration) you can perform a manual refresh. This will provide detailed logging to help troubleshoot the behavior.

To perform a manual refresh, open the "edit issue source" dialog (either from the Issues tab under the application, or under Administration > Issue Sources) and then click "Manually Refresh…". This will navigate to a page that allows you to specify:

  • Issue Source: either a specific issue source, or all issue sources
  • Application: either a specific application, or all applications
  • Release: either a specific active release within the specified application, or all applications

Clicking the "Refresh Issues" button will initiate an execution and provide scoped logs.

Internal Issue Tracker

You can use BuildMaster's issue store as a lightweight issue tracker, allowing you to add issues and associate them with specific release and release packages. While this certainly isn't as advanced as a proper issue tracking tool, it may be perfectly adequate for small applications and components with few changes.

You can add and edit issues from the Issues tab, the release overview, and the release package overview pages. The internal issue tracker can be enabled or disabled under Application > Settings > Advanced.

Issues in Release Packages

Issues are always associated with release, but they may also be associated with up to two release packages:

  • Opened: Release Package that the issue was opened for, or discovered in
  • Closed: Release Package that successfully resolved, or closed the issue

These associations may be useful when there are multiple release packages that are being tested at the same time.