GitHub Branch Source plugin

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


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.


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.

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.