Table of contents

Plugin management


GitHub Branch Source Plugin

Introduction

The GitHub Branch Source Plugin allows you to create a new project based on the repository structure from one or more GitHub users or organizations. You can either:

  • Import all or a subset of repositories as jobs into the workspace from a GitHub user or organization

  • Import a single repository’s branches as jobs from a GitHub user or organization

The GitHub Organization project scans the repository, importing the Pipeline jobs it identifies according to your criteria. To define a job, you create a Pipeline script in a Jenkinsfile in the root directory of the project or branch. You can have different Pipeline scripts defined in project branches, or add and remove `Jenkinsfile`s depending on your use cases. After a project is imported, Jenkins immediately runs a job. Removing a Pipeline script from a branch or from the entire project, removes the item from the view. You can restrict imports using a regular expression on the GitHub Organization configuration page. This plugin fits into the larger "Pipeline as Code" story; for more information, see the CloudBees Cookbook article.

The GitHub Branch Source Plugin creates each repository as a folder containing each branch with a Jenkinsfile in the top level directory as a different job. The Jenkinsfile contains a Pipeline script outlining the steps of the job. Scripts can be different for each branch.

GitHub pull requests

The GitHub Branch Source plugin allows the project to import externally originated pull requests containing a Pipeline script. The following features are included:

  • GitHub user or organization repository’s pull requests are treated as jobs

  • Pull request build result status reporting

Pull requests will be added to Jenkins as long as the pull request originates from a remote repository, contains a Pipeline script in a Jenkinsfile, and is mergable. Even when you make changes to your Jenkinsfile, the checked out code is at the revision as the script.

When the proper webhooks are configured, Jenkins will report the status of the pull request’s job to GitHub. The status is reported as follows:

  • Success - the job was successful

  • Failure - the job failed and the pull request is not ready to be merged

  • Error - something unexpected happened; example: the job was aborted in Jenkins

  • Pending - the job is waiting in the build queue

Creating a project

This plugin creates a new project type. To use this plugin, you must have GitHub credentials with the appropriate access level to your project (see the section on credentials below) installed in Jenkins. Set up your GitHub Organization as follows:

Go to Jenkins > New Item > GitHub Organization screenshot1

In the Repository Sources section, complete the section for "GitHub Organization". You can specify a username or an organization in the "Owner" field. Select or add new "Scan credentials". These credentials should allow you to at least see the contents of your targeted repository. Optionally, change the "Repository name pattern". screenshot2

Save, and wait for the "Folder Computation" to run. Job progress is displayed to the left hand side. screenshot3

You may need to refresh the page after it runs to see your repositories. screenshot4

A this point, you are finished with basic project configuration. You can now explore your imported repositories, configuring different settings on each of those folders if needed. You can also investigate the results of the jobs run as part of the Folder Computation. screenshot5

Credentials

There are two different types of credentials for the GitHub organization:

  • scan credentials: used to access the GitHub API

  • checkout credentials: used to clone the repository from GitHub

You can use different credentials for each as long as they have the appropriate permissions. There is an anonymous option for checkout. Regardless, you should create a GitHub access token to use to avoid storing your password in Jenkins and prevent any issues when using the GitHub API. When using a GitHub access token, you must use standard Username with password credentials, where the username is the same as your GitHub username and the password is your access token.

Exploring an imported repository

Each of your imported repositories is a folder containing a project for each branch with a Pipeline script defined in a Jenkinsfile in the root directory. You cannot modify the settings on these folders.

Build triggers & webhooks

You can change the build configuration to perform the folder computation at different times. The default setting will scan your GitHub repository for changes if it has not received any change notifications from GitHub within the past day. This scan will catch the repositories you’ve added or removed from the managed GitHub repository. You can always force the Folder Computation to run from the GitHub Organization page.

screenshot6

While the build triggers are often enough, you can set up webhooks to automatically trigger builds when changes are pushed to your GitHub repositories. To do this you must have a GitHub login with a token.

  1. Go to the main configuration settings page, Manage Jenkins > Configure System

  2. In the GitHub Plugin Configuration section, add a server with your credentials

  3. If you need a token, generate one with the Additional Actions > Convert login to password and token

You can also configure this manually through GitHub itself by registering the URL provided in the help section of the server config.

Controlling what is built

By default, Jenkins will build any branches it finds in the "origin" repository (the actual repository found in your organization). Also, any pull requests that have been filed from "forks" (clones in user accounts) will also be built; Jenkins will try to merge the pull request with the "base" (target) branch on every commit, to check for possible integration conflicts. Pull requests filed from the origin repository are skipped as these are already getting built as plain branches.

If you would like to customize this behavior, as of version 1.8 of the plugin you can click the Advanced button and then turn on and off certain kinds of branch projects:

build types

In particular, you can choose to build origin-repository pull requests in addition to, or instead of, building the plain branches; and you can choose to build pull requests without merging with the base branch, or in addition to building the merge product.