Upgrading to BuildMaster 2023

BuildMaster 2023 is a major update, and this article provides information about what will change, the impact to your instance, and how to mitigate risk during upgrade.

Planning for Your Upgrade

BuildMaster 2023 is a major upgrade, and many of the changes were additive features, platform updates (library upgrades, etc.), and UI changes.

Upgrading from BuildMaster 2022

No major features have been removed and there were no significant changes to the core components; we anticipate the upgrade will be relatively easy and no preparation will be required.

You can safely downgrade to BuildMaster 2022 without rolling back the database, but new data, such as Docker- and Cloud-related resources may not work in the older version.

Upgrading from BuildMaster 7.0 and BuildMaster 6.2

If you're currently using BuildMaster 6.2 or BuildMaster 7.0, we recommend directly upgrading to BuildMaster 2023. While it won't hurt to do incremental upgrades, there's almost never a benefit.

Please read the upgrade notes from each version to learn what changed and how to mitigate risks. To summarize:

In BuildMaster 2022,we reworked Git integration, made pipeline changes, and PowerShell operation changes. However, there were very few issues reported - and they've been resolved in the latest versions.

In BuildMaster 7.0, there was very little that changed from an upgrade standpoint. We mostly standardized libraries, adding Linux support, high-availability, etc.

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 2023 UPGRADE in the "How can we help" section, and include the Legacy Features Dashboard Report Logs in the text body of the ticket.

New Feature: First-Class Docker Integration

Although BuildMaster has long supported container-based development with the Docker extension, we made Docker a core part of BuildMaster 2023's functionality, in a similar manner to how Git is integrated.

This feature leverages existing components within BuildMaster, and provides specialized views to help you Containzerizing your Application and Deploy With Docker Run Config.

New: Run Build Scripts in Containers

Instead of configuring build servers to run your builds, you can use pre-built containers like microsoft-dotnet-sdk and maven that have the tools and components already installed, or customerize those containers as well.

When Image-based Services is enabled, script templates like Build .NET Project and Build Maven Project will display a "Docker" tab that lets you select the container to run your build script in.

Changes: Docker Resources/Credentials

In previous versions, you could create a "Docker Container Registry" resource and specify

• Credentials used to authenticate to the registry
• Optional registry prefix like proget.kramerica.local:443/mycontainers

And then, in Docker-based operations, you could specify a "short" repository name like myapp, which would then be combined into the full repository name of proget.kramerica.local:443/mycontainers/myapp. The operations would use docker login to authenticate using the specified credentials.

The Credentials were typically a Username/Password credential, as that's what docker login uses. An API token was also supported, but the operations would simply use api as the username, and then the API token as the password. This generally only with ProGet we believe.

In BuildMaster 2023, "Docker Container Registry" resources will be transparently converted to a "Generic Docker Repository" resource. The "prefix" and "short name" will continue to function, but is considered deprecated in BuildMaster 2023.

API Token credentials will still work, but they will "disappear" if you edit the if you edit the resource. You'll need to create a Username/Password, or switch to a different repository type.

You will also be able to add a "ProGet Container Repository", which will allow you to select a feed and then enter a repository name without worrying about credentials. Down the line, you'll be able to add other service-specific resources like "Azure Container Repository".

Changes: Docker Operations

All of the Docker-based operations were modified to support the Resource/Credential changes. In addition, Docker::Assemble-Image was deprecated in favor of simply maintaining your Dockerfile in BuildMaster.

New Feature: First-Class npm Integration

If your web application uses npm to build or enhance their front-end pages, there is now an option to enable building an npm project on the "npm Options" tab of script templates like Build .NET Project and Build Maven Project.

Once enabled, the script template will set an npm version (optional), install npm packages (npm install), and run the build script (npm run build). You'll be able to select an npm feed from a connected PRoGet instance, and publish those dependencies as a SCA Project Release in ProGet.

This feature is powered by the newly-created Node integration (extension), which is also included with BuildMaster.

New Feature: First-Class Azure App Services Integration

It's now much easier to deploy your applications to Azure App Services with a Built-in Azure Connection Wizard and Script Templates/Operations that simplify working with Slotted Deployments.

BuildMaster 2022.9 and later includes built-in operations for deploying your applications to an Azure Web App. For other Azure operations, please see our deployment using az.exe documentation.

Redesigned Feature: Issue Tracking Integration

BuildMaster's Issue Tracker Integration had a major overhaul in BuildMaster 2023. Functionally, it's works the same, and BuildMaster will still:

• Connect to issue trackers like Jira, Azure DevOps, GitHub, YouTrack, etc.
• Pull issues associated with active releases
• Quickly see release notes (and generate them)
• Block deployment if there are open issues
• Automatically update issue statues after deployment

However, BuildMaster 2023 makes it much easier to configure these connections and improves the UI quite a bit:

Behind the scenes, the integration uses a new model as well: an "Issue Tracker Project" (Secure Resource) is used in conjunction with an "Issue Tracker Service" (Secure Credential). The Issue Tracker Project resource is what's used to pull issues and update statuses.

Issue Sources Are Deprecated

BuildMaster 2022 and earlier used a different integration model: an "Issue Source" (now deprecated) pulled issues by connecting to an "Issue Tracker Service" (Secure Resource) using an "Issue Tracker Account" (Secure Credential). Issue Sources are not project-specific, and you could technically configure an Issue Source to configure to different projects using variables.

Unfortunately, this model is incompatible with the previous model, and there was no easy way to migrate connections. While Issue Sources will still work in BuildMaster 2023, but they are considered a legacy feature and will be removed in BuildMaster 2025. We recommend deleting your configured issue sources, and re-adding the issue tracker connections instead.

OtterScript Updates

To help simplify your OtterScript scripts, we added a handful of control statements:

• break can be used in side of an iteration (loop) statement, and will exit the iteration
• continue can be used inside of an iteration (loop), and will skip to the next item
• return will exit the current script or module
• else if, which will make long if/else statements easier to work with.

We also made some minor UI changes to the low-code Script Editor that makes it easier to work in visual mode.

New "Set" Statement Behavior

The set statement (i.e. set $myvar = myval;) has a slightly new behavior; it will simply default to using the global scope when creating a new variable instead of the current "kind of local, kind of global" behavior.

For example, consider the following script.

# This script works in BuildMaster 2023 but fails in BuildMaster 2022
{
  set $myvar = myval;
}
Log-Information "myvar" is $myvar;

In BuildMaster 2022 and earlier, this would fail with an error like $myvar is not declared. But if you used set global $myvar = newval then it would work and log the result. In BuildMaster 2023, the script will not error, and will simply work as if you wrote set global.

# This script works in BuildMaster 2022 and BuildMaster 2023
{
  set global $myvar = myval;
}
Log-Information "myvar" is $myvar;

The above example works, but this is not a good general purpose solution, because set global only considers the global scope for assignment, so the below example could yield confusing behavior:

{
  set $myvar = myval;
  
  {
    set global $myvar = my new val;
  }

  Log-Information "myvar" is $myvar;
}

The output of the above example would be myvar is myval, because set global will only assign or create variables in the global scope.

If you want BuildMaster 2023 to create a variable in the local scope, then you can use the local scope as follows:

# This script fails in BuildMaster 2022 and 2023
{
  set local $myvar2  = myval;
}
Log-Information "myvar2" is $myval;

Note that set local will always create a variable in the local scope, even if one already exists in a higher enclosing scope.

What made BuildMaster 2022's default set behavior a bit confusing is that:

• Variables already initialized in a higher scope would be set
• Uninitialized variables would be set in the current scope

We've made default set more intuitive in BuildMaster 2023. The new behavior is:

• Variables initialized in a higher scope will still be set
• Uninitialized variables will be created in the global scope

By defaulting set to create new variables in the global scope, this will behave as more users expect.

Other Features & Notable Changes

• OtterScript Visual Editor Improvements; we improved the look/styling of the visual editor and added tag-based searching for statements
• "Templates" Secure Resource deleted; if you had a secure resource named "Templates" that was configured to point to our BuildMasterTemplates feed, it will be removed
• Application Template Version Change; if you're using the deprecated application templates feature, the template version number has been updated to 2.0.0, which means you'll need to recreate them
• Application Slug Support; you can now specify a short, url-friendly name for your application (a "slug"), which will be used in URLS that link to your application

Upgrade Process

You should generally perform the upgrade using the same method you used to install.

• On Windows, the most common installation method is using the internet-connected Inedo Hub; see HOWTO: Upgrade or Downgrade with the Inedo Hub for more details on how to upgrade.
• On Linux, the most common installation method is using our Docker container; see Upgrading Docker Containers for more details.

However, there are other installation options available, including offline installation, cluster installation, and even manual installation. If you want to change installation methods, the easiest way is to simply uninstall (by following the process in reverse) and install using the new method.

If you're upgrading from ProGet 6.2 or earlier, it's possible BuildMaster was installed with the legacy installer, The Inedo Hub should be able to upgrade these installations, but you may need to uninstall and then reinstall using the Inedo Hub.

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

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

While you can upgrade from BuidMaster 6.1 and later to BuildMaster 2023 (i.e. there is no need to install intermediate versions), you can only rollback to BuildMaster 2022 without restoring your database.

Rolling Back

However, if you need to rollback to BuildMaster 2022, you can do so without restoring the database by simply using the Inedo Hub. While there are database schema changes, they are all backwards-compatible with BuildMaster 2022, which means you can safely rollback your ProGet installation if there's a showstopper bug, and then upgrade later.