Upgrade Notes for BuildMaster v5

KB#1117: Last Updated Nov 19, 2018

Upgrading from a v3 or v4? This document is for informational purposes only, and you should upgrade directly to v6; please see Upgrading from BuildMaster v3 and v4 first.

Upgrading from a 5.x? You should directly upgrade to the latest BuildMaster 5.8 prior to upgrading to v6.

This article is a rollup of all upgrade notes from BuildMaster 5.0 through 5.8, and discusses the changes which may impact your installation, configuration, and customizations of BuildMaster.

BuildMaster v5 was a transformative release intended to modernize the platform and software and introduced a lot of changes through nine different releases.

Change Summary

The following table summarizes all of the changes introduced throughout v5, and the details can be found below. In addition to these changes, two important things to note:

BuildMaster 5.0
BuildMaster 5.1
BuildMaster 5.2
BuildMaster 5.3
BuildMaster 5.4
BuildMaster 5.5
BuildMaster 5.6
BuildMaster 5.7
BuildMaster 5.8

Upgrade Process

Upgrading from a v3 or v4? This document is for informational purposes only, and you should upgrade directly to v6; please see Upgrading from BuildMaster v3 and v4 first.

Upgrading from a 5.x? You should directly upgrade to the latest BuildMaster 5.8 prior to upgrading to v6.

You can upgrade from any BuildMaster 5.x version to the latest BuildMaster 5.8 simply by downloading and running the installer.

Risk Mitigation

Although the risks vary depending on which 5.x version you're upgrading from, you should take the following precautions to prevent downtime:

  • Make sure that your BuildMaster database is backed up prior to upgrade
  • Make sure that your Encryption Key is backed up prior to upgrade
  • Make sure that the installation's \Extensions directory is backed up prior to upgrade

Rollback

Because there are database changes, a rollback will require uninstalling BuildMaster, and then restoring your BuildMaster instance.

.NET 4.5 Required

BuildMaster 5.0 introduced a requirement that .NET Framework 4.5 or later is installed on the BuildMaster server, and for all of the BuildMaster agents. This is a highly compatible, in-place update to .NET Framework 4, and is already included with Windows 8 and Windows Server 2012. For older machines, simply download .NET 4.5 from Microsoft and install the update.

User Experience Changes

BuildMaster 5.0 introduced a Web Interface Overhaul to Refocus on Release Automation. In addition to the color, font, and basic layout updates, the first thing you will notice is the continued shift towards application release automation; although we will support the "create a build and deploy it to production" workflow indefinitely, this workflow is becoming less popular as CI servers like TeamCity, Jenkins, TFS, etc. become the preferred build tool, and as universal package managers like ProGet become the preferred artifact store.

The most notable change will be in terminology; "builds" are now "release packages", "promotions" are now "deployments", and "workflows" are now "pipelines".

In retrospect, this wasn't a good idea. As of BuildMaster 6.1, we have mostly undone this change and will be focusing on BuildMaster as a CI/CD platform with the "create a build and deploy it to production" as a primary use case.

New Execution Engine / Legacy Plans

BuildMaster 5.0 added the Inedo Execution Engine (OtterScript) for deployment plans. To mitigate upgrade risk, this new execution engine is implemented side-by-side with the legacy execution engine, and. Although the new execution cannot run a legacy plan (nor can the legacy engine run a new OtterScript plan), you can convert legacy plans to OtterScript on a plan-by-plan basis, and then edit the corresponding pipeline to use the new plan.

See KB#1118: Legacy Plans in BuildMaster 5.0

Workflows Renamed to Pipelines

BuildMaster 5.0 renamed Workflows to Pipelines. While conceptually similar, the feature was completely reimplemented, and pipelines are quite a bit more versatile. There are a few notable changes:

  • Stages vs Environments - a workflow represented a sequence of environments, where as a pipeline is a sequence of stages; a stage can target zero or more environments
  • Targets - in addition to an environment, a target also specifies servers; this means you don't have to explicitly name the servers you want to use in your plans
  • Build Step Removed - there is no special build step anymore; you can just add a stage and add a build importer to that
  • Gates - these are the same as Pre-deployment checklist

Deprecated Features Removed

BuildMaster 5.0. The Notifiers and Triggers that were replaced with Event Listeners in BuildMaster 4.4 have been removed; there had been warnings about these for several versions (especially in 4.9). The Global environment approvals were also removed; these too were deprecated in BuildMaster 4.4.

Roles Renamed to Tasks and Rebuilt

BuildMaster 5.0

As part of the UX overhaul, "Roles" have been renamed to "Tasks", and the names of the roles have been updated to sound more task-like. KB#1120 (Permission Updates in BuildMaster 5.0) provides more details on this change.

BuildMaster 5.5

The five built-in tasks (Administer, Coordinate Releases, Manage Application, View Application, and Deploy to Environment) have been rebuilt, which means any customizations made to those tasks will be lost. If you didn't heed the warning about modifying built-in tasks, then you may want to rename the tasks to anything else prior to upgrade. Custom tasks are not impacted.

In addition, the Environments_Manage attribute was renamed to Infrastructure_Manage, and the Environments_View attribute was removed altogether.

UTC for Deploy Artifact Action

BuildMaster 5.0 now uses UTC times to compare artifacts on destination servers. This may cause BuildMaster to deploy the full artifact on first deployment after upgrading as timestamps are no longer matched using local time.

New Agent Model / Legacy BuildMaster Agents

BuildMaster 5.1 added support for the Inedo Agent and renamed the previous agents to the Legacy BuildMaster Agent. See KB#1039: The Inedo Agent and Legacy BuildMaster Agents for more information.

New Feature: Resource Credentials

BuildMaster 5.1 added a new feature called resource credentials that is used for passwords and other secrets. See Resource Credential documentation for more information.

Resource Credentials for SSH-based Servers

BuildMaster 5.1 removed support for having SSH-based servers store the credentials and/or private key on the server itself. Instead a resource credential must be created, and then associate with the server. Existing SSH-based servers will still function, but when you edit a server, you will need to associate it with a resource credential.

New SSH Library

BuildMaster 5.1 changed the SSH library used to communicate with Linux-based servers. This should have no functional impact, and although the new library (libssh2) is very popular and actively maintained in comparison to the old library (SSH.NET), the library change introduces some risk for deployment to Linux-based servers.

Encryption Key

BuildMaster 5.1. To encrypt resource credentials, an encryption key is used; this will be created during upgrade, and added to the web and service configuration files. This encryption key must be added to your back up plan, or you will not be able to decrypt resource credentials on a resto

New Feature: Server Roles (replacing Server Groups)

BuildMaster 5.2 introduced the Server Roles feature as a replacement for Server Groups, and Server Groups will be hidden unless you have Legacy Plans

In Legacy Plans, the Server Groups feature enabled actions or action groups to target of multiple servers. Because Operations in OtterScript plans cannot target a server group (though, you can iterate over servers to provide exactly the same functionality), they offer no value for non-legacy users and are hidden from the UI if there are no legacy plans.

Servers may still be grouped together using Server Roles, which is a new feature in this release. Roles may be the target of a pipeline stage, and may be iterated just like server groups.

New Feature: API Keys (replacing ApiKey)

BuildMaster 5.2 introduced the API Keys feature. If you configured an ApiKey for BuildMaster in All Settings, that will be automatically converted to an API Key with Native API access.

New Features: Infrastructure Configuration Import/Export & Synchronization

BuildMaster 5.2 introduced the Configuration Import/Export and Infrastructure Synchronization features.

New Features: Release Templates

BuildMaster 5.3 introduced the Release Templates feature in conjunction with deprecating the existing variables that are used on releases and release packages.

New Feature: Configuration Variables / Legacy Variables

BuildMaster 5.3 introduced a new variables feature called Configuration Variables. All existing configuration or release template variables that you've created will now be "legacy variables" in the UI; Release Templates and Configuration Variables were implemented side-by-side to replace them.

See KB#1128: Legacy Configuration and Release Variables for more information

New Feature: Agentless Windows Servers

BuildMaster 5.4 introduced a new agentless means for communication with Windows servers via PowerShell remoting channels.

Changes to the Internal Artifact Disk Store Structure

Although accessing artifact files directly in the artifact disk store (i.e. ArtifactsBasePath) is unsupported, many users wrote external scripts and tools that rely on doing exactly this.

In previous versions of BuildMaster, artifacts were stored using the following structure:

\«application-id»
  \«release-number»
    \«package-number»
      \«deployable-id»
        \«artifact-name».zip

As of BuildMaster 5.4, newly-created artifacts will be stored in the following manner:

\A«application-id»
  \R«release-id»
    \B«package-id»
      \«artifact-name».zip

If you rely on these internal paths, you're going toh ave a problem with newly-created artifacts. Obviously, you should fix the external tool to not use these... but in the mean time, there are two options you can use:

  • Use Legacy Storage Path - both the Create Artifact Operation and Create Artifact Legacy Action have a new property called Use Legacy Storage Path that defaults to false. When set to true, the artifact will be stored using the earlier convention
  • Create Legacy Artifact Storage Symlinks - if you're in a particular bind because you didn't realize that something down the pipeline relied on this (such as a production deployment), the easiest quick fix may be to use the tool built-in to the service executable (bmservice.exe) that will create symbolic links for all existing "new path" artifacts at the old, expected location. Just run bmservice.exe, select the option, and that should fix the immediate problem. Afterwards, change your plans to use use the Use Legacy Storage Path property or (ideally) fix your external tool

New Feature: Variables Management API

BuildMaster 5.4 added the Variables Management API which lets you update configuration variables with a simplified API endpoint.

New Features: Pipeline Variables and Variables as JSON

BuildMaster 5.5 introduced variables to pipelines and pipeline stages, as well as the ability to bulk edit configuration variables as JSON documents.

New Feature: Release Management API

BuildMaster 5.5 added the Release and Package Deployment API offers a simple mechanism for creating releases, creating release packages, and deploying release packages.

New Feature: Issue Sources

BuildMaster 5.6 added the Issue Sources Feature to replace the Issue Tracking Providers, which are now considered a legacy feature.

Source Control Operations & Providers as a Legacy Feature

BuildMaster 5.6 deprecated the "provider model" in favor of using Resource Credentials and Global Variables for configuration, as well as tool-specific Operations. So instead of "Get-Latest using SVN" it would be "SVN-Checkout". As such, both Issue Tracking Providers and Source Control Providers are considered legacy features.

New Features: Calendars, Deployment windows, and Release target dates

Buildmaster 5.7 introduced several related features: Calendars, Deployment Windows, and Release Target dates.

Configuration file deployment changes

BuildMaster 5.7 introduced changes to configuration file deployment, with the biggest change in behavior being the removal of %-syntax variable support when deployment occurs in an OtterScript plan. The behavior was previously undefined, e.g. sometimes it performed the replacement, whereas other times it did not. See the full Configuration File Assets documentation for more information and specification.

Edition Name Changes

BuildMaster 5.7. Going forward, what was formerly named "BuildMaster Enterprise" is now "BuildMaster Standard". The only change in the software is to mention "Standard" on the license key pages in place of "Enterprise". No functionality changes as a result.

New Feature: Text Templating

BuildMaster 5.8 allows you to use the Apply-Template operation to perform advanced text replacement. Templating is part of the SDK, so it can also be used by custom extensions.

This feature can be used in combination with Configuration Variables as the simplest mechanism to deploy configuration files.

New Feature: Updated LDAP and Active Directory

BuildMaster 5.8 added a new and improved LDAP and Active Directory integration, which makes maintaining user and group permissions easier than before. Complex, multi-domain active directory structures are now easily catered to, as our new integration allows permissions to be defined in a third-party LDAP directory, or an active directory domain forest. If you choose to use an active directory domain, you can also enable Windows Integrated Authentication, removing the web-based login prompt.

The optional new "LDAP and Active Directory" user directory is served from the InedoCore extension (v5.8.0+) and bundled with the installer. Current user directory settings will not be modified and require additional configuration within BuildMaster in order to use it. Refer to the LDAP and Active Directory documentation for configuration options and if necessary, troubleshooting steps.

New Feature: Plan Versioning

BuildMaster 5.8 added Plan Versioning, where a history of edits is maintained within BuildMaster; allowing approved team members to view the version history, or even preform a rollback to a previous version. You can also simply view the differences between two versions from the Plan Version Listing page. The differences between the two selected plans will be highlighted for quick identification of the changes that have been made.

SDK Changes

BuildMaster 5.0 and BuildMaster 5.1 shipped with a new SDK with breaking changes. This means extensions 5.0 extensions will not work with any version except 5.0, however 5.1 will work with later versions.

BuildMaster 5.2 through BuildMaster 5.7 shipped with a new SDK, but all additive changes.

Although the SDK is mostly the same (even from v4), the notable changes are as follows.

  • Operations are the v5-equivalent of Actions. However, you do not need to develop a Operation to use these in OtterScript plans, thanks to the special Execute-LegacyAction operation.
  • StoredProcs to DB - the utility class that provided access to the database API is now called DB. This new class is much more performant, supports transactions, has better type saftey, and supports asynchronous queries. In nearly all cases, simply renaming StoredProcs to DB will be sufficient.
  • 5.1+ Agent service interfaces were moved into the Inedo.Agents namespace in the Inedo.Agents.Client assembly
  • 5.1+ IRemoteZip has been uninclused, its two methods folded into IFileOperationsExecuter
  • 5.2+ The VariableFunctionPropertiesAttribute was obsoleted in the BuildMaster 5.2 SDK. If you have a custom variable function, and wish to compile against this SDK, use the LegacyAliasAttribute instead of the LegacyAlias property, and a TagAttribute instead of the Category property. The Scope property was ignored since v5.
  • 5.5+ The SDK changes are additive, to support additional dynamic list variables features. If you have a custom editor that inherits from PromotionRequirementEditorBase, that will no longer be displayed in the UI. It needs to be refactored to either use PromotionRequirementEditor or the appropriate editor attributes.

See the Writing a Simple Operation Using the BuildMaster SDK tutorial and the BuildMaster SDK Reference for more details.

Extensions Changes

The following extensions are supported in BuildMaster v5. Extensions with an asterisk (*) have actions that have not yet been converted to operations, though they will still function fine in an OtterScript plan using the Execute-LegacyAction operation.

Supported in v5: Amazon*, Azure*, Git, GitHub, Jenkins*, Jira, Java*, Mercurial, MSTest, MySQL, NuGet, Oracle, Perforce, PostgreSQL, Sourcegear, SqlServer, Subversion, TeamCity*, TFS*, Trac, Windows, WindowsSDK, YouTrack

Note that the JUnit extension was merged with the Java extension.

Un-migrated Community Extensions

Several of the extensions that were built by and for the community have not been upgraded to the new SDK, and thus will not work in v5. Although it's trivial to recompile/republish them, many of these extensions are not up to our usability/quality standards, or do not support newer versions of the tool they're integrating with. As such, we would prefer to work with a user familiar with that tool to bring it up-to-date.

Not Currently Supported in v5: AccuRev, Artifactory, Axosoft, BugTrackerNet, Bugzilla, CollabNet, CVS, DB2, FogBugz, FTP, LeanKit, MBUnit, PHPUnit, Plastic, Rake, Rational, Seapine, Skytap, VB6, WiX

If you are using any of these extensions, just let us know and we will recompile and publish them to work for v5.

BuildMaster 5.0: All Extensions Must be Upgraded

Because the breaking SDK changes from v4, you will need to upgrade all of your extensions after you upgrade BuildMaster. This is quite easy from the Admin > Extensions page.

BuildMaster 5.1: All Extensions Must be Upgraded

Because the breaking SDK changes from 5.0, you will need to upgrade all of your extensions after you upgrade BuildMaster. This is quite easy from the Admin > Extensions page.

BuildMaster 5.3: Core functionality moved to BuildMasterCore Extension

Most of the operations and variable functions have been migrated to built-in extensions; if "nothing works" after upgrade, then most likely the extensions could not load due to permissions errors. But, once the extensions are loaded, there will be no functional difference at all.

BuildMaster 5.6: GitLegacy and GitHubLegacy Extensions

This largest upgrade impact will be for users with the Git and GitHub extensions. Users with these extensions must download the GitLegacy and GitHubLegacy extensions to maintain existing functionality. This may occur post-upgrade via the Extensions Overview page within BuildMaster, or visiting the Inedo Den and downloading directly at http://inedo.com/den

BuildMaster 5.7: New Extension Loader

The extensions loader has changed since v5.6 for parity with Otter's romp extension loader. There should be no observable functional changes as extension load paths and temporary paths are the same.