BuildMaster Documentation

Cloning and Patching an Inedo Extension

There are dozens of BuildMaster Extensions available designed to help you integrate with third party tools. Sometimes, the integration doesn’t work exactly the way you’d like it to, or there’s an additional parameter or option that you’d like added to the extension. This is accomplished through cloning and pataching an extension.

Fork the Extension Code on GitHub

The source code to all of our extensions are hosted on GitHub. You can browse the repositories at http://github.com/inedo, or find the repository link on the extension’s overview page. For this tutorial, we'll pick the Amazon Web Services extension.

First, navigate to the repository (in this case, https://github.com/Inedo/bmx-amazon), and then click the Fork button in the top right. You may be prompted to create a GitHub account, which you’ll need to do if you don’t have one already.

This will create a personal copy (a “Fork”) of the repository, which you can then access and modify as needed. From here, you’ll need to use a Git client (GitHub for Windows, git, etc.) to access the code and modify on your local workstation. How to use a Git client is out of the scope of this tutorial, but there are plenty of resources available online for that.

Adding GitHub as a Source Control Provider

The GitHub Extension is the easiest way to access GitHub (if you don't already have the GitHub extension installed you will need to install it first).

  1. Go to the Admin menu (hover on the gear icon in top right)
  2. Click Source Control Providers
  3. Click Create New Source Control Provider
  4. Click GitHub icon

When the connection is successful, you can click Save Provider.

Building the Extension in BuildMaster

Once you’ve forked the repository, you can use the “Create your own extension” function to create an application that builds and deploys the extension to BuildMaster. To do this,

  1. Go to the Admin menu (hove on the gear icon in top right)
  2. Click BuildMaster Extensions
  3. Click Create Auto-Deploying Extension Application at the bottom

This will bring up the Custom Extension Application form which will prompt you to set a name, provider, and path.

Click the "Create" button, and BuildMaster will create a new application, with pre-populated build plans and pipeline meant for custom and modified extensions.

Click on "Releases" > "Create Release" > "Create Release" > "Create Package" to start a build of the custom extension.

After a successful build the extension can be deployed which will install the customized extension to your BuildMaster instance, and trigger a restart in BuildMaster. See the Creating an Auto-Deploying Custom Extension Application tutorial to learn more about how this application works.

Modifying the Extension on Your Workstation

After creating an application that can build and deploy the extension it can be modified as needed.

All of the extensions are built using Visual Studio 2012 Professional, though you should be able to use any edition of Visual Studio 2010, 2012, 2013, or later. So long as the NuGet Visual Studio Extension is installed, you should be able to just open the solution file and build it. For complicated modifications, you may want to install BuildMaster on your workstation and create a post-build step in the project file that zips the output and copies it to your BuildMaster extensions folder.

Note that Visual Studio is only needed if you want to compile the code; assuming it’s  relatively simple change, you could just use a text editor to modify the codefiles and hope that it compiles inside of BuildMaster.

Build, Deploy, and Test the Extension in BuildMaster

The application should take care of building, packaging, deploying, and restarting BuildMaster. Sometimes the last part (restarting) doesn’t quite work; if not, you may have to just manually restart it. For complicated changes, you may want to take a look at Debugging BuildMaster Extensions.

Submitting Pull Requests

After you’ve verified your code changes work, feel free to submit the code changes to Inedo as a pull request on GitHub. To do this, navigate to the “Pull Requests” section on your fork of the repository.

Then click on the "New pull request" button.

Depending on the number of commits you’ve made to your repository, the new pull request page will have you select which commits you’d like to send.

After selecting the commits, add a comment and submit it to Inedo.  We’ll respond to it as soon as we can!

A Note on Release Numbers

From BuildMaster’s perspective, this extension will be indistinguishable from Inedo’s official extension. This isn’t a problem, although we recommend keeping your version numbers lower than Inedo’s official extension.

This way, you will be alerted that a newer version is available, and can check to see if the new version to see if your change has been included.