docs@
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.
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.
Authentication with GitHub is handled through Resource Credentials. In most cases, creating a resource credential using the GitHub type is sufficient, but you can also use Git for "generic" source control integration that doesn't rely on GitHub-specific concepts like "organizations" or GitHub releases. These credentials are effectively 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.
To connect to a self-managed instance of GitHub Enterprise, make sure the API URL of the resource credentials 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.
Resource credentials can be defined at the system-level or the application-level, and they can inherit from one another, such that configuring the "parent" resource credential will automatically give that configuration to its "child" credentials. This allows you to define some fields (such as name/password) at the system level, while defining repository-specific information at the application level.
Is this documentation incorrect or incomplete? Help us by contributing!
This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.