Upgrading to BuildMaster 2022

BuildMaster 2022 is a major update, and this article contains information about what will change, how it will affect your instance, and how you can minimize risk during the upgrade.

Planning for Your Upgrade

BuildMaster 2022 is a major upgrade, and many of the changes were additional features, platform updates (library upgrades, etc.), and UI changes. Several existing features are considered deprecated.

There are some important things to consider before upgrading:

1. Reworked integration of Git servers (GitHub, GitLab, etc.) and CI servers (Jenkins, TeamCity), which may affect the use of Operations, Repositories, and Monitors
2. Pipeline Event Listeners and Variable Prompts have been added to replace Pre/Post Steps and Release Templates
3. PowerShell Operation Changes can cause scripts in BuildMaster to issue warnings
4. Hybrid User Directories have been replaced, and you will need to manually delete old entries
5. The platform (.NET 4.5.2) has been updated to .NET 6, which may mean you need to update the hosting configuration and directories. Extensions you have created yourself must be recompiled

You can also revert to BuildMaster 7.0 if there are problems without restoring your database.

Upgrading from BuildMaster 7.0

No major features have been removed, so the upgrade should be relatively easy and no preparation is required. However, given the changes to the pipelines and execution engine, we recommend testing builds and deployments after the upgrade.

You can safely downgrade to BuildMaster 7.0 without rolling back the database, but new data, such as Git connections, that you created in BuildMaster 2022 may not work in the older version.

Upgrading from BuildMaster 6.2

If you're using BuildMaster 6.2, we generally recommend a direct upgrade to BuildMaster 2022 instead of incrementally upgrading to BuildMaster 7.0.

No major features were removed or changed in BuildMaster 7.0, so an incremental upgrade makes little sense. See the Upgrading to BuildMaster 7.0 guide for all the changes.

Most of the changes will be in BuildMaster 2022. So read through exactly what has changed to see how it might affect you. If you have problems after upgrading to BuildMaster 2022, you can downgrade to BuildMaster 7.0 without restoring the database, or simply roll back to BuildMaster 6.2 after restoring the database.

Upgrading from BuildMaster 6.1 or Earlier

In BuildMaster 6.2, all Legacy Features were removed from the product. See Upgrading to BuildMaster 6.2 to learn more about what else changed in that release. Alternatively, you may want to consider an application-by-application migration approach.

You wont be able to upgrade to BuildMaster 2022 until the Legacy Feature Detector has reported no legacy features. This is only available in the latest versions of BuildMaster 6.1, which means you will need to upgrade to BuildMaster 6.1 first.

Because upgrading from BuildMaster 6.1 is more involved than previous upgrades, special support for it has been included with paid licenses. Simply use the Submit Ticket Form, put 2022 UPGRADE in the "How can we help" section, and include the Legacy Features Dashboard Report Logs in the text body of the ticket.

New Features in BuildMaster 2022

New Feature: First-Class Git Server (GitHub, GitLab, etc.) Integration

BuildMaster 2022 is now tightly integrated with Git services such as GitHub, GitLab, Azure DevOps, and BitBucket. This allows you to:

• Browse branches/commits directly from BuildMaster to quickly create new builds
• Compare commits (code changes) between two builds/releases
• Tag commits on release
• Create and merge pull requests
• Monitor repositories to create or deploy builds

See our Git integration documentation to learn more.

This feature required significant changes to the various Git extensions (Git, GitHub, GitLab, and AzureDevOps). Instead of using service-specific operations like GitHub::Get-Source, you can simply use operations like Git::Checkout-Code. The service-specific operations will still work, but will issue a warning.

Git repositories (which are still managed via Secure Resources) can now be synced with BuildMaster. Your existing repositories will show as remote only and you will be prompted to sync them. This is not required.

Builds can now be associated with a Git commit of a synchronized repository; this eliminates the need to record variables such as $Branch or $Commit in your build. However, if you need the branch or commit associated with a build, you can use $Branch or $Commit - they are now variable functions that return the associated information.

Repository Monitors were also been rewritten/replaced with Resource Monitors. They behave essentially similarly, but it is no longer possible to specify credentials (user name/password) directly in the monitor, run the monitoring on a different server, or use git.exe. The old Repository Monitor configuration will remain in the database for rollback purposes.

New Feature: First-Class CI Server (Jenkins, TeamCity) Integration

See our CI Server integration documentation to learn how BuildMaster 2022 lets you:

• Browse builds on Jenkins and TeamCity to see parameters and artifacts
• Import artifacts from builds you select
• Create monitors that will automatically import when new builds

This feature also involved substantial changes to Jenkins and TeamCity extensions, but the operations are still the same (e.g. it’s still Jenkins::Import-Artifacts).

CI Projects (still managed by Secure Resources) are now regularly synced with BuildMaster, which means you will be able to see build information directly in BuildMaster. This can cause problems if you are using older versions of Jenkins or TeamCity.

Builds can now be associated with a CI Build; this eliminates the need to capture variables such as $JenkinsBuildNumber, and if you need this information, you can use the $CIBuild variable function.

New Feature: Application Onboarding & Navigation Changes

Both top-level and application-level navigation has changed significantly. Of particular note:

• Global Pipelines and Global Scripts are accessible in each application (under the Global tab) or via a link in Administration
• The single Application Settings page combines many other pages, such as variables, resources, credentials, and monitors

When creating a new application, users are now guided through configuring a Git repository or CI Server connection. They can still create Blank Applications or Clone existing ones, or use Templates and Samples.

New Feature: Pipeline Event Listeners

Pipelines now have Event Listeners that can perform actions such as sending emails, setting statuses, or tagging Git repositories when certain things happen to a build:

• Pipeline Complete; when a build has reached the last stage of the pipeline. This is often used to set statuses and create new versions.
• Build Rejected; when a build has been rejected and will not exit the pipeline. This is commonly used for tearing down temporary environments/resources.
• Failed Deployment; when there are errors deploying to a stage. This is commonly used for notifications.
• Successful Deployment; when a successful deployment has occurred at a stage. This is often used for notifications.
• Before Deployment; immediately before deployment at a stage. This is commonly used for setting variables.

Any Pre- and Post-deployment steps that you've created will be converted to Event Listeners.

• Pre-deployment Step → Before Deployment Event Listener
• Post-deployment step (Failed) → Failed Deployment Event Listener
• Post-deployment step (Success) → Successful Deployment Event Listener

Post-deployment options will also be converted to Event Listeners:

• Cancel earlier (lower-sequenced) releases → Pipeline Complete Event Listener
• Create a new release → Pipeline Complete Event Listener
• Mark as deployed → Pipeline Complete Event Listener

The conversion happens when the pipeline is loaded, either at UI or at execution time. This means that you'll always get an Unsaved Changes notice when you want to edit a pipeline with Pre or Post steps or options.

New Feature: Pipeline Variable Prompts

Users have always been able to prompt for variable values at build, release, and deployment time.

• In BuildMaster 5.3, we introduced Release Templates to allow users to define different prompts based on different release types.
• In BuildMaster 7.0, we added more variable prompts types.
• In BuildMaster 2022, we added variable prompts to Pipelines, which let you prompt users for values at build, release, and deployment time.

We have a utility that can perform the migration for you. You can access it by navigating to Release Templates in any application. This migration is relatively low risk, as it simply moves the variable prompts you define from the release template into the pipeline.

New Feature: Expanded Scripting Language Support

BuildMaster 2022 has first-class support for multiple scripting languages: PowerShell, Python, Windows Batch, and OtterScript.

This will allow you to upload your existing scripts and run them directly in your build and deployments.

New Feature: BuildMaster Basic Edition

This is a new edition of BuildMaster supported via a new license key in BuildMaster 2022. BuildMaster Basic and BuildMaster Enterprise have almost all the same features. However, BuildMaster Enterprise adds the ability to run in a high availability cluster, use SAML Sign-on, and support more users.

New Feature: SAML & Security Management Overhaul

We have increased the flexibility of logging into BuildMaster and made managing security much easier:

• Improved UI for managing security and users
• Allow multiple user directories to be searched at once
• Integration with SAML providers such as Azure and PingID
• Import/export Permissions and Built-in Users
• Allows multiple login options at once: Built-in user name/passwords, Windows Authentication, SAML Authentication

These changes have changed some of the login/authentication codes, which may cause errors/regressions where users cannot log in or a connected system (build/CI server) reports authentication errors.

Several task attributes were also renamed/combined:

• ChangeControls_Manage was removed, since the feature was removed in BuildMaster 6.2
• Notes_Manage became Builds_EditNotes, and Builds_AddNotes was added
• Issues_Manage was renamed to Release_ManageIssues
• ScriptAssets_Manage and Plans_Manage was merged into Scripts_Manage
• ScriptAssets_ViewContents and Plans_ViewContents were merged into Scripts_ViewContents
• Applications_ViewSources was added

Also, if you are using the Hybrid User Directory (which allows you to query multiple user directories), these user directories will be enabled and you will get an error message on the User Directories page if you had one configured. You can safely delete this directory.

New Feature: Script Templates

When you create a new script, in many cases you'll be prompted to use a Script Template such as Build . NET Application or Deploy IIS Site to use. Under the hood, these are regular OtterScripts that use a simplified editor.

New Feature: New OtterScript Editor

We have completely rewritten the OtterScript editor. In addition to greatly improved usability, the most notable changes are the following:

• New "statement searcher" for adding statements and operations
• Automatic saving of draft changes with the ability to return to them later and edit them
• Commit/review changes before finalizing/saving them
• Autocomplete (i.e. like IntelliSense) when editing OtterScript in Text Mode

PowerShell Operation Changes

To standardize usage/syntaxes across different scripting languages, PowerShell Operations (PSEnsure, PSVerify, and PSCall) were rewritten and have a slightly different syntax:

• A file extension (`.ps1) needs to be used
• Script parameters need to be specified as a map within the Parameters argument

Generally, BuildMaster users will only use the PSCall operation, which executes a PowerShell script stored in BuildMaster. However, if you're sharing scripts between Otter, it's possible that you'll use PSEnsure, which would effectively be the same thing. BuildMaster will not execute a PSVerify operation.

To minimize the impact on your existing OtterScript-based scripts, BuildMaster can detect if you're using the old syntax by looking for a file extension.

• At Runtime, BuildMaster will use the old operations
• In the Visual Editor, BuildMaster will automatically convert to the new style

:::(Info) How to Migrate
The easiest change is to explicitly use the old operation (i.e., PSEnsure1, PSVerify1, and PSCall1). Just change PSCall to PSCall1.

Alternatively, you can edit the parameters to follow the new format.
:::

Syntax Differences

# Old Syntax
PSCall CreateLocalAdmin
(
    User: $PSCredential(LocalAdminAlex)
);

# New Syntax
PSCall CreateLocalAdmin.ps1
(
    Parameters: %(User: $PSCredential(LocalAdminRich))
);

Implementation Details

Behind the scenes, these changes required us to create an entirely new set of operations.

• Old operations: PSEnsure1, PSVerify1, PSCall1
• New operations: PSEnsure2, PSVerify2, PSCall2

In BuildMaster v2022, PSEnsure, PSVerify, and PSCall are aliases for 2, and the aliases are preferred. This means you should not explicitly use PSEnsure2, PSVerify2, PSCall2 in your OtterScript.

Custom Extensions Changes

BuildMaster 2022 targets Inedo.SDK-2.2, which means that you'll need to update the Inedo.SDK NuGet package reference in your project to Inedo-SDK 2.2.

Note that this version of the SDK targets .NET6.

See creating an extension documentation to learn more about how to do this.

Upgrade Process

You can only upgrade from BuildMaster 6.1 and later.

You can perform the upgrade from the Inedo Hub. As with all upgrades, you should make sure your installation is backed-up.

After the installation you have to update/install new versions of the extensions if needed.

If you are upgrading from BuildMaster 6.1, you will need to perform some additional steps after upgrading to BuildMaster 2022:

1. Remove old ( Legacy SDK) extensions as required
2. If you are using the SqlServer 1.0.0 extension, it will not load; delete it and download SqlServer 2.0.0
3. Upgrade/install extensions as needed

Rolling Back

You can roll back using the Inedo Hub.

Although there are changes to the database schema, they are all backward compatible, which means that you can safely reset your BuildMaster installation if an error occurs, and then upgrade later.