Chapter 8. Setting up a Custom Git Trigger
A Custom Git Trigger is a generic way for any git server to act as a build trigger. It relies solely on SSH keys and webhook endpoints; everything else is left to the user to implement.
8.1. Creating a Trigger
Creating a Custom Git Trigger is similar to the creation of any other trigger with a few subtle differences:
- It is not possible for Red Hat Quay to automatically detect the proper robot account to use with the trigger. This must be done manually in the creation process.
- There are extra steps after the creation of the trigger that must be done in order to use the trigger. These steps are detailed below.
8.2. Post trigger-creation setup
Once a trigger has been created, there are 2 additional steps required before the trigger can be used:
- Provide read access to the SSH public key generated when creating the trigger.
- Setup a webhook that POSTs to the Red Hat Quay endpoint to trigger a build.
The key and the URL are both available at all times by selecting View Credentials from the gear located in the trigger listing.
8.2.1. SSH public key access
Depending on the Git server setup, there are various ways to install the SSH public key that Red Hat Quay generates for a custom git trigger. For example, Git documentation describes a small server setup in which simply adding the key to $HOME/.ssh/authorize_keys would provide access for builders to clone the repository. For any git repository management software that isn’t officially supported, there is usually a location to input the key often labeled as Deploy Keys.
8.2.2. Webhook
In order to automatically trigger a build, one must POST a JSON payload to the webhook URL with the following format:
{
"commit": "1c002dd", // required
"ref": "refs/heads/master", // required
"default_branch": "master", // required
"commit_info": { // optional
"url": "gitsoftware.com/repository/commits/1234567", // required
"message": "initial commit", // required
"date": "timestamp", // required
"author": { // optional
"username": "user", // required
"avatar_url": "gravatar.com/user.png", // required
"url": "gitsoftware.com/users/user" // required
},
"committer": { // optional
"username": "user", // required
"avatar_url": "gravatar.com/user.png", // required
"url": "gitsoftware.com/users/user" // required
}
}
}
This request requires a Content-Type header containing application/json in order to be valid.
Once again, this can be accomplished in various ways depending on the server setup, but for most cases can be done via a post-receive git hook.
