Issue and Project Tracking

BuildMaster is designed to continuously deliver your applications and components from source code to production, helping everyone track changes made to each release. Unlike monolithic CI/CD platforms like Azure DevOps or GitLab, BuildMaster works with any combination of issue and project tracking tools like JIRA or YouTrack.

By integrating BuildMaster with your issue and project tracking tools, you can help developers, testers, and business analysts work closely together by providing shared visibility into the changes they're working on and leveraging automation to enable immediate feedback. Ultimately, this will help:

• reduce production errors by preventing deployments without fully tested issues
• save time by eliminating tedious, manual status changes on issues
• give testers more information about where their changes are deployed to
• quickly identify the issues and changes that are blocking a release
• create fully automated deployments using issue statuses as checks and balances

Connecting to Your Issue or Project Tracking System

A combination of Issue Sources and Resource Credentials are used to connect BuildMaster to your Issue or Project Tracking System, whether that's a public issue tracker on a GitHub repository or a self-managed JIRA instance. Each supported issue tracker has its own type of Issue Source, and that type is defined in the corresponding extension.

For example, installing the JIRA extension will allow you to create a

• Resource Credential that contains a server URL and an API key to connect to your JIRA server
• Issue Source that identifies which JIRA issues belong in which BuildMaster release; in JIRA, this is done in one of two ways:
  • Field mapping: choosing a project in JIRA and then picking a field in that project (like fixFor) that BuildMaster will use to search for issues associated with the release
  • Custom mapping: using JIRA's powerful JQL language to search using any number of fields (such as fixFor, issueType, etc.) or even across multiple JIRA projects

Both Resource Credentials and Issue Sources can be configured at the application level, application group level, and system level. This means that you can have multiple issue sources per application, or use one issue source for multiple applications that can all use the same resource credential.

Synchronizing Issues to BuildMaster

After connecting to your issue or project tracker, BuildMaster will periodically synchronize with its own built-in issue tracking system. You can view these by going to the Issues tab in the application's navigation bar.

This issue store tracks the following information about each issue:

• Release - a specific Release of a BuildMaster Application
• Issue ID - a human-readable identifier, such has HDARS-1281
• Type - the category of issue, such as Bug or Feature
• Status - the issue's status, such as Open or Resolved
• Closed - a true/false value that indicates the issue is closed
• 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

Example: Inedo Use Case

On our public instance of BuildMaster, we have dozens of nearly identical applications configured that are designed to build/deploy the various extensions to our products. We've configured just a single issue source as follows:

This issue source will only be active for applications within the Extensions application group we've configured. Each of the applications in this group are named similarly to the repository; for example, there is a Subversion application in BuildMaster and a inedox-subversion repository in GitHub. The expression inedox-$ToLower($ApplicationName) maps these together when the issue source is synchronized.

This issue source will periodically synchronize with GitHub. We've configured an automatic check that prevents deployments until all issues are resolved.

Variable and Issue Sources

BuildMaster will automatically and periodically perform one synchronization for each active release in the system. This means that a release is always in context and you can use any of the variable functions that rely on a release to be in context: ReleaseNumber, ReleaseNumberPart(), etc.

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

Blocking Deployments with Untested/Unresolved Changes

Once you've connected BuildMaster to your Issue or Project Tracking System, the next step should be ensuring that releases with unclosed or unresolved issues aren't deployed. This is an incredibly important part of "pushing left," making sure that problems are caught earlier in the CI/CD process where they are cheaper and faster to repair and are less damaging to the business.

This can be done by configuring one of two automated checks on your release pipeline that will prevent builds from being deployed to a particular stage unless all issues are closed. You can also permit builds to move forward after a certain status such as Resolved appears. Prior to deployment, these approvals will evaluate each issue associated with the release and block the deployment if the approval is not met or is unresolved. For example:

• 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; issues still open (i.e., with any status other than closed) will fail to be approved and will be blocked from moving on

Like all automatic approvals, a build 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 to be manually taken by a human actor (i.e., forcing issues forward is not an automated process).

Automatically Changing Issue Status

After you've connected BuildMaster to your Issue or Project Tracking System, you can use BuildMaster to automatically change issue statuses as part of a deployment using operations in OtterScript.

BuildMaster not only reduces the tedious work of changing issue statuses after a deployment (e.g. moving all issues from "In Progress" to "Ready to Test"), but also allows you to leverage the full power of custom statuses/workflows in your issue tracker to give instant status to all team members.

Using the Operations

The specifics of issue status or state changing operations are documented in the corresponding Tool & Service Integrations pages but they are all used similarly. Essentially, you specify various options using parameters.

Example: Basic JIRA Workflow Transition

For example, JIRA uses workflow transitions to change an issue's status and then helps define a business process instead of just an arbitrary list of status fields. If you defined a workflow for the ProfitCalc project in your JIRA instance that allowed issues to be transitioned from Ready for Release to Released, you could accomplish this automatically with the following OtterScript:

Jira::Transition-Issues
(
    Credentials: Jira,
    Project: ProfitCalc,
    From: Ready for Release,
    To: Released,
    FixFor: $ReleaseNumber
);

Example: Advanced Workflow to Provide Immediate Status

Business stakeholders want as much information as possible about the changes they want, while developers want to avoid as much tedious, manual work as possible.

Instead of forcing business stakeholders to use a simple issue tracker (such as the one built into GitHub) or forcing developers to constantly change issue statuses by hand, BuildMaster lets you automatically change issue statuses on deployment using a workflow like this:

By using these states, it's pretty easy to set up some basic processes and procedures:

• Unless all Issues are Ready for Production, the release cannot be deployed to production.
• Immediately after a successful deployment to Integration, all issues in Checked In should be changed to Deployed to Integration.

It would be incredibly bothersome to update all of these statuses by hand. With automation, it's trivial.

Adding Comments/Notes During Build/ Deploy Time

Similar to Automatically Changing Issue Statuses, you can use BuildMaster to automatically add notes or comments to issues as part of a deployment. This can be used to communicate more information to testers or business analysts that rely on the issue or project tracker for status, such as:

• The server/URL a particular build was deployed to
• The name of the user that initiated the deployment and when
• Link back to build in BuildMaster
• A note entered in BuildMaster, at deployment time, by the user who deployed the build

Example: Disposable Infrastructure

A common deployment pattern is to deploy software to disposable environments, i.e., environments that are created and destroyed ad hoc. These types of environments are typically managed to:

• speed up creation of test environments
• ensure new environments are fresh, i.e., they might not have dependencies on data or configuration other than a default setup
• allow multiple environments to exist at the same time

A common problem with these types of environments is that you simply do not know they even exist once they are created, or how to find the environments in the first place. This can cause problems for test teams, as they may not know which environment to test.

BuildMaster helps solve this problem by integrating with defect tracking tools that already help test teams manage their processes. For example, you can add a comment to all issues in the "Ready for QA" status that lets testers know how to access the environments. For example, this OtterScript used in a plan includes a URL to an environment created in a previous pipeline stage:

YouTrack::Find-Issues
(
    Credentials: YouTrack,
    Filter: Fix version: $ReleaseNumber State: Ready for QA,
    Output => @YouTrackIssueIDs
);
foreach $IssueId in @YouTrackIssueIDs
{
    YouTrack::Change-Issue-State
    (
        Credentials: YouTrack,
        IssueId: $IssueId,
        State: Deployed to QA
    );
    YouTrack::Add-Comment
    (
        Credentials: YouTrack,
        IssueId: $IssueId,
        Comment: >>The fix for this issue ($IssueId) was automatically deployed by BuildMaster on $Date to [$EnvironmentName]([https://us-web-01.$ApplicationName-$ReleaseNumber-$BuildNumber.corp/](https://us-web-01.%24applicationname-%24releasenumber-%24buildnumber.corp/)) >>
    );
}

Creating New Issues Automatically

Many teams use issue and project tracking tools like JIRA for more than just code changes.

Most issue/project tracking tools available today are extremely flexible and can therefore be used to model virtually any business process, such as deployment tracking. For example, issue trackers have audit trails that do not require a high level of technical expertise to use, unlike source code work.

Teams are already familiar with the process of creating new issues, but they want to automate it. BuildMaster lets you model this workflow by automatically creating and linking to new issues. This saves the manual effort of creating new issues and also avoids human errors that are possible with manual processes.

Example: Creating a Deployment Tracking Issue

Some companies use issues as a means of deployment throughout a release. This allows the business and test teams to track the progress of the deployment, report issues on that issue, and be notified of status changes through the issue tracking tool's notification features.

Although issue tracking tools aren't really designed for this, it's generally easier to automate an existing process rather than force a new one. This is easy to do with BuildMaster. You can use an operation to create an issue.

Each integration has different features, but here is an example of how you can do this in JIRA:

JIRA::Create-Issue(
	Credentials: Jira7Local,
	Project: HDARS,
	Title: QA Testing Required for $ApplicationName,
	Description: This issue was created by BuildMaster on $Date,
	Type: ReadyForQA,
	JiraIssueId => $JiraIssueId
);

Set-BuildVariable DeploymentIssueId
(
	Value: $JiraIssueId
);

The second operation will then set $JiraIssueId as a build variable, which means it will be not only visible on the build page but you can also use it in all future deployments on that build.

You can then use the $JiraIssueId in later operations to automatically change issue status or add comments and notes.

Tip: Use a Variable Renderer for User-friendly Display

You can do this in BuildMaster with Variable Value Renderers. These are essentially instructions for how to render variables in the UI that have certain names (such $JiraIssueId). Because you can specify HTML in a value renderer, you link directly to your issue tracker. This provides easy navigation for users.

Troubleshooting: Issue Synchronization

An issue synchronization happens automatically when you visit the release or build overview page. This is mostly transparent: a "please wait" status screen is displayed while the execution engine runs the synchronization with the issue source. Once the synchronization is complete, BuildMaster displays the freshly synchronized issues stored in the internal issue storage.

Manual Synchronization

If the automatic issue synchronization behaves unexpectedly (either due to an error or incorrect configuration), you can perform a manual update. This will give you a detailed log that will help you troubleshoot the problem.

To perform a manual refresh, open the "edit issue source" dialog box (either on the Issues tab in the application or at Administration > Issue Sources), and then Manually. This will take you to a page where you can enter the desired information:

• 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.

Using BuildMaster's Internal Issue Tracker

You can use BuildMaster's Issue Store as a lightweight issue tracker that allows you to add issues and associate them with specific releases and builds. While this is certainly not as advanced as a dedicated issue tracking tool, it can be perfectly adequate for small applications and components with few changes.

You can add and edit issues on the Issues tab, the Release Overview, and the Build Overview page. The internal issue tracker can be enabled or disabled at Application > Settings > Advanced.

Issues and Builds

Issues are always associated with a release, but can also be associated with up to two builds. Associating an issue to a build provides additional contextual information for end-to-end visibility. You can associate the issue to Opened and Closed builds:

• Opened: Indicates in which build the issue was discovered or that it was opened for that build
• Closed: Indicates in which build an issue was successfully fixed or closed (like a patch)

These associations can be especially useful when testing multiple builds at once.