BuildMaster Documentation

Raft Repositories

  • Last Modified: 2020-04-23

Rafts are an advanced feature. If you are just getting started with BuildMaster, you should revisit this topic once you've familiarized yourself with the other components.

Most of BuildMaster's configuration assets (scripts, pipelines, release templates, etc.) are stored as text files, and BuildMaster uses a "raft repository" store these assets.

A raft is sort of an abstracted file system, and there are different types of rafts; this means you can choose whether to store this configuration within the BuildMaster database, an external Git repository, or even in a readonly zip file.

You can also configure multiple rafts, which allows you to have some configuration stored within the BuildMaster database, and have other configuration (such as common scripts or text files) shared with other instances of BuildMaster or Otter using a zip file or Git repository.

The Default Raft

When you install BuildMaster, a raft named "Default" is automatically created. This is a Database raft and is backed up when you do a regular Back-up of BuildMaster.

For most users, this initial configuration is totally sufficient; some may wish to replace this "Default" raft with another raft, such as a Git-based Raft.

If you only have a single raft configured, and that raft is named "Default", then the ability select rafts will not be exposed on application, plan, pipeline, release template, and other pages.

Creating and Managing Rafts

You can create, manage, browse the contents of, and download a raft as a zip file by going to Admin > Raft Repositories.

Because rafts can be modified external to BuildMaster, it's possible to create "corrupted" configuration, such as pipelines with invalid JSON. These will not be editable on the regular configuration pages (such as the pipeline editor), but if you browse to the files on the Raft Repositories page, you can edit the raw contents of the configuration as needed.

Exporting & Reusing Raft Configuration

One of the main benefits of downloading your raft as a zip file is that you can use it in a different instance of BuildMaster or Otter by using a zip file-based raft.

You could even use BuildMaster to automate this between instances; see our CI/CD for Infrastructure & Configuration Management Guide

Rafts and Applications

An Application may be associated with a raft. When a raft is specified, the application's configuration (pipelines, release templates, etc.) will be persisted within that raft. If no raft is specified, then the "Default" raft (if one is named that) is used.

Application assets are stored in subfolders on a raft. Assets are stored in the folder structure of /projects/{application}/{asset type}/{asset}. This folder path structure exists for rafts configured at the server-level and the application-level.

Referencing a Raft Asset in Otter Script

An asset can be referenced at the global or the application level. To reference a global asset in the default raft, simply use global::itemName or Default::itemName. Using global:: is the same as using Default::. If a global asset is stored in a raft other than the default raft, speciyg the raft name instead of global or default (e.g., raftName::itemName).

An application can also reference an asset from another application. To do this, use the syntax appName::itemName. To avoid naming ambiguity, applications cannot be named Global, Default, or the same as a raft name. Application naming always takes precedence in referencing raft assets, so applications named Global, Default, or the same as a raft name will cause unexpected references.

Raft Repository Types

Rafts rely on an Extensible Raft Provider to retrieve and store raft data. There are three built-in raft types:

  • Database - this is the default raft provider, and persists all information in BuildMaster's database; the contents are versioned, and it's the simplest to use and back-up as part of the BuildMaster database
  • Disk - the raft is persisted as a simple file structure on disk; there isn't much of a usecase for this type, so we don't really recommend using it for anything other than quick testing purposes
  • Zip file - the raft is persisted in a zip file, and is read-only; this is an ideal way to manage configuration that is tested across environments; see our CI/CD for Infrastructure & Configuration Management Guide
  • Git - this raft is synchronized with a branch of a remote Git repository. See Git-Based Rafts to learn how to use this type of raft

Tutorial: Move Your "Default" Raft to GitHub

Although rafts are an advanced feature, they are an integral part of how BuildMaster works. The good news is, even if you don't need to use multiple rafts, you can simply replace the built-in raft ("Default") with a Git-based raft, and all your configuration assets will be versioned.

  1. To do this, start by creating a repository on GitHub. You can name your repository virtually anything. For example, we'll name ours "initech-raft"

  2. Then, in BuildMaster, go to Administration > Raft Repositories and click the "download" link next to the raft named "Default".

  3. Copy the contents of the ZIP file directly to GitHub. Of course, you can always push them from the git client.

  4. Go back to BuildMaster, and delete the existing "Default" raft. Note that you can rename it to DefaultOld if you prefer not to delete.

  5. Create a Git raft named "Default" by clicking Create Raft > Git

  6. Name your raft "Default", and enter the Remote repository URL (click on Clone or download in your GitHub repository to find it) and your GitHub credentials. Then, enter master for "Branch" and Click Save

  7. To ensure that synchronization and storage were successful, click "browse"

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.

Generated from commit 46e90aca on master