This documentation relates to QuickBuild 13.0.x
Select here if you are using a different version

Working with GitHub

Version 6 by Steve Luo
on Feb 11, 2023 03:08.

compared with
Current by Steve Luo
on Feb 11, 2023 03:09.

These lines were removed. This word was removed.
These lines were added. This word was added.

View page history

There are 1 changes. View first change.

 QuickBuild integrates with GitHub via the GitHub repository. This repository has all features of a normal [Git repository|Working with Git], but add the ability to build against pull requests, and update pull request status based on build result.
 h2. Build against pull requests
 To build against GitHub pull requests, define a GitHub repository like below:
 In repository definition, you may select to build against open, closed, or specified pull requests, and choose to build head, merge, or both of selected build requests like below:
 Here _head_ branch of pull request points to tip commit of the pull request, while _merge_ points to merged commit of head commit and tip commit of target branch of the pull request. After defining the Git repository, you should add a checkout step to check it out into the workspace, and add necessary build steps to build against checked out contents.
 Upon triggering of configuration using such repository, QuickBuild will first find all matched pull requests at GitHub side and then fire separate build request(s) for each pull request to check changes against that pull request, and build that pull request if necessary. So if there are many matched pull requests, many build requests will be fired. So it is best practice to enable [concurrent build|Build Concurrency and Deadlock] to speed up verification of multiple pull requests.
 As demonstrated below, each finished build will display associated pull request as branch information and changes of the build will be calculated against previous build with the same pull request branch.
 Upon manual triggering of such configuration, all matched pull requests will be built even if they've not being updated, just like what QuickBuild behaves when trigger configurations using normal repositories. However if you schedule the configuration and set build condition to _If changes found in referenced repositories_ (or something similar), QuickBuild will only build against new/updated pull requests.
 h2. Update pull request status at GitHub side based on build status
 When build against *head branch* of GitHub pull requests, QuickBuild will update pull request status automatically to reflect build status when build is started/finished, as demonstrated below:
 {note}To make this working, make sure head branch of relevant pull requests are getting built as pull request status reflects head commit status.{note}
 h2. GitHub Webhook Integration
 QuickBuild can trigger builds via GitHub webhooks since 9.0.
 h3. Config GitHub
 To enable the webhook, first you need go to GitHub repository webhook settings page to configure the QuickBuild side related information:
 If you want to use some custom parameters, you can add them to your webhook url like below:
 Then, later you can use _target_ parameter in your trigger condition.
 h3. Config QuickBuild
 h4. Add anonymous group
 As the webhook is triggered without authentication, anonymous group should be added and it should have the permission to use RESTful API.
 h4. Add webhook settings
 QuickBuild only allow push event to trigger the builds, other events will be ignored. To add integration at QuickBuild side, please go to configuration settings page and then choose Webhook -> GitHub from right side menu:
 Then, you can add the settings:
 * *Trigger User* the QuickBuild user to trigger the build who should at least have permission *RUN_BUILD* for that configuration.
 * *Webhook Secret* the secret should be the same as what you defined in GitHub
 * *Trigger Condition* the trigger condition in Groovy scripts, when the result is true, build will be triggered, otherwise, the build will not be triggered. You can use variable _delivery_ to access the data from GitHub like _delivery.ref_, _delivery.pusher.name_. See more details on [GitHub Events and Payloads page|]. You can also use the parameter specified in webhook URL as aforementioned.
 * *Trigger Build Variables* define the variables to trigger the builds so you can use those variables in the steps later.
 h3. GitHub Organization Webhook
 If you want to use GitHub organization webhook, you don't need specify the configuration id at the webhook URL:
 and then you need specify the repo and configuration mappings at QuickBuild side. Go to Administration page, and choose Plugin Management, then search for GitHub Webhook plugin:
 and then click the "Gear" icon to config the plugin, specify the repo and configuration id mappings here:
  You also need to add [GitHub Webhook|#WorkingwithGitHub-ConfigQuickBuild] settings at QuickBuild side and decide whether or not to trigger builds according to the GitHub webhook payload like [aforementioned].
  You also need to add [GitHub Webhook|#WorkingwithGitHub-ConfigQuickBuild] settings at QuickBuild side and decide whether or not to trigger builds according to the GitHub webhook payload like [aforementioned|].