BuildMaster Documentation

Integrating GitHub with BuildMaster

  • Last Modified: 2020-02-26

GitHub is a hosting platform primarily for open-source projects, but also has support for issue tracking, release management, and collaboration. GitHub has three types of accounts, Personal, Organization, and Enterprise, each offering a different level of security. While GitHub does have its own version of a CI/CD platform in GitHub Actions, it is still in beta, and it also requires an organization's projects to be migrated to the GitHub platform in order to use it.

BuildMaster is designed to work alongside GitHub to provide a self-managed CI/CD solution. BuildMaster's GitHub integration supports the following functionality:

See it live! See an example of GitHub integration by creating a new application using the GitHub CI/CD template.

Installing the GitHub Extension

Simply navigate to the Admin > Extensions page in your instance of BuildMaster and click on the GitHub extension to install it.

If your instance doesn't have Internet access, you can manually install the GitHub extension after downloading the GitHub Extension Package.

Connecting to and Authenticating GitHub

The easiest way to connect to a GitHub repository is with a GitHub Project secure resource and a GitHub Account secure credential. You could also use the more general-purpose Git operations, although those aren't generally recommended because they don't model GitHub-specific concepts like "organizations" or GitHub releases.

  • A GitHub Account is just a username and password, so we recommend creating a specific account with the minimum amount of privileges required to interact with GitHub. Typically, this is just Read permission, but if there are requirements to add releases or tag source code, at least the Write permission will be required.
  • A GitHub Project is the API URL, organization, and project names, and optionally can use a GitHub Account for authentication

To connect to a self-managed instance of GitHub Enterprise, make sure the API URL of the resource is configured to the hostname for your installation instead of GitHub's public API URL.

SSH connections are not supported using the built-in GitHub integration in BuildMaster, so make sure to use the HTTPS endpoint when supplying the repository URL to the resource credentials or any operations. If your organization requires SSH to connect, you must install and configure the Git CLI manually and then instruct BuildMaster to use the Git CLI instead.

Both Secure Resources and Secure Credentials can be defined at the system-level (global/shared) or the application-level. Generally, it's easiest to create one Secure Resource per application, and share a Secure Credential across multiple applications.

More on this topic:

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 ffb6a807 on master