Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Make the manual webhook setup documentation much clearer — actually mention the webhook URL!

Wiki Markup
{jenkins-plugin-info:github}

Github Plugin

Excerpt

This plugin integrates Jenkins with Github projects.

The plugin currently has three major functionalities:

  • Create hyperlinks between your Jenkins projects and GitHub
  • Trigger a job when you push to the repository by groking HTTP POSTs from post-receive hook and optionally auto-managing the hook setup.
  • Report build status result back to github as Commit Status (documented on SO)
  • Base features for other plugins

Table of Contents

Hyperlinks between changes

...

When creating a job, specify that is connects to git. Under "Github project", put in: git@github.com:Person/Project.git Under "Source Code Management" select Git, and put in git@github.com:Person/Project.git

...

GitHub hook trigger for GITScm polling

This feature enables builds after post-receive hooks in your GitHub repositories. This trigger only kicks git-plugin internal polling algo for every incoming event against matched repo.

Note
titleOld name

Previously named as "Build when a change is pushed to GitHub"

To be able to use this feature:

...

In this mode, you'll be responsible for registering the hook URLs to GitHub. Click the (question) icon to (under Manage Jenkins > Configure System > GitHub) to see the URL in Jenkins that receives the post-commit POSTs . Just go to — but in general the URL is of the form $JENKINS_BASE_URL/github-webhook/ — for example: https://ci.example.com/jenkins/github-webhook/.

Once you have the URL, and have added it as a webhook to the relevant GitHub repositories, continue to Step 3.

Automatic Mode (Jenkins manages hooks for jobs by itself)

...

Each GitHub Server Config creates own GitHub client to interact with api. By default it uses cache (with 20MB limit) to speedup process of fetching data and reduce rate-limit consuming. You can change cache limit value in "Advanced" section of this config item. If you set 0, then this feature will be disabled for this (and only this) config.

Note

Additional info:

  • This plugin now serves only hooks from github as main feature. Then it starts using git-plugin to fetch sources.
  • It works both public and Enterprise GitHub
  • Plugin have some limitations

Possible Issues between Jenkins and GitHub

...

  • In windows, Jenkins will use the the SSH key of the user it is running as, which is located in the %USERPROFILE%\.ssh folder ( on XP, that would be C:\Documents and Settings\USERNAME\.ssh, and on 7 it would be C:\Users\USERNAME\.ssh). Therefore, you need to force Jenkins to run as the user that has the SSH key configured. To do that, right click on My Computer, and hit "Manage". Click on "Services". Go to Jenkins, right click, and select  "Properties". Under the "Log On" tab, choose the user Jenkins will run as, and put in the username and password (it requires one). Then restart the Jenkins service by right clicking on Jenkins (in the services window), and hit "Restart".
  • Jenkins does not support passphrases for SSH keys. Therefore, if you set one while running the initial Github configuration, rerun it and don't set one.

Change Log

Version 1.17.0 (Feb 22, 2016)
  • (plus) Handle ssh:// URLs that doesn't contain git@ (pull #110)
Version 1.17.0 (Jan 26, 2016)
  • (plus) Administrative monitor, that can tell about hooks registering problem (also with warning in job config) (JENKINS-24690)
Version 1.16.0 (Jan 14, 2016)
  • (plus) Show the "GitHub" link for Workflow projects (pull #105)
Version 1.15.0 (Jan 7, 2016)
  • (plus) Allow Commit Notifications to be used as Workflow Build Steps (pull #102)
Version 1.14.2 (Dec 21, 2015)
  • (error) Fix NPE after deserialization of old configs for status steps (JENKINS-32132)
Version 1.14.1 (Dec 15, 2015)
  • (plus) Configurable build context and message in status builder and notifier (JENKINS-27154)
  • (plus) Let GitHub Project property be applied to any Job (even workflow)
  • (error) Ignore files when clean root cache dir (in 1.14.0 it throws IOException in such case)
  • (info) Useful method GitHubRepositoryName#create to create it from GitHubProjectProperty
Version 1.14.0 (Oct 7, 2015)
  • (plus) Workflow support (JENKINS-27136)
  • (error) Handle pings from organization webhooks (JENKINS-30626)
  • (info) Using okHttp as client to make requests to GH instead of built-in URLConnection
  • (plus) Add cache to all requests to GitHub. It limited to 20MB for each GitHub server by default. Set 0 to disable this feature in "Advanced" section of GitHub Server configuration.
  • (info) Now plugin requires java 1.7
Version 1.13.3 (Sep 2, 2015)
  • (error) Restore old credential class to save backward-compatibility with plugins uses GH credentials (JENKINS-30223)
Version 1.13.2 (Aug 31, 2015)
  • (error) Ignore malformed Jenkins URL if override hook url
Version 1.13.1 (Aug 31, 2015)
  • (info) Clarify error log message when plugin not configured (JENKINS-30207)
Version 1.13.0 (Aug 24, 2015)
  • (plus) Credentials usage instead of plain token in global configuration. It requires plain-credentials-plugin to create "Secret text" credentials with token to use.
  • (info) Change UI in global configuration
  • (info) Move all global configuration from descriptor to separate class.
Version 1.12.1 (Aug 10, 2015)
  • Fix NPE in stop method of GHPushTrigger on 1.621 jenkins
  • Fix dummy "Unknown content type null" in logs
Version 1.12.0 (Jul 22, 2015)
  • Migrate to webhooks (fixes ability to use multiple jenkins instance with one repository)
  • Provide extension points for subscribing/listening hooks
Version 1.11.3 (Apr 13, 2015)
  • Bumped up to newer GitHub API library to deal with incompatible API changes in that library.
Version 1.11.2 (Feb 25, 2015)
  • (info) Added "re-register" button in global page for re-registering hooks (JENKINS-25127)
Version 1.11.1 (Mar 26, 2015)
Version 1.11 (Feb 25, 2015)
  • (info) Refer builds in commit status context (JENKINS-23995)
  • (info) Upgrade github-api-plugin dependency to 1.59
Version 1.10 (Nov 17, 2014)
  • (plus) Build step to set Github commit status as "pending"
  • (error) Prevent NPE in GitHubCommitNotifier if Git checkout fails (JENKINS-23641)
  • (error) Fixed NoClassDefFoundError when Multiple SCMs Plugin is not present
  • (info) Make the build status configurable if GitHubCommitNotifier fails (JENKINS-25312)
  • (info) Improved error checks in the global configuration page.
  • (info) Resolve variables in GitHub repository URL
Version 1.9.1 (Jul 16, 2014)
  • Fixed "Github Webhook event of type null is not supported" (JENKINS-23661)
Version 1.9 (Jul 1, 2014)
  • Webhook auto management now works with GitHub Enterprise (JENKINS-18710)
  • GitHub Web Hook does not work unless "Prevent Cross Site Request Forgery exploits" is disabled (JENKINS-20140)
Version 1.8
Version 1.7 (Jul 7, 2013)
  • Add the name of the user who pushed to Github into the log (pull #17).
  • Recognize GitHub repository URLs that doesn't end with ".git"
  • Got rid of API token and added OAuth token for interacting with GitHub.
  • Webhook support is no longer a pre-requisite for commit status notification (JENKINS-18165)
Version 1.4 (Jun 13, 2012)
  • Removed GitHub V2 API dependency
Version 1.3 (May 31, 2012)
  • Improved to use the new Jenkins hook type available in GitHub
  • Change GitHubPushCause to extend from SCMTriggerCause (pull #15).
Version 1.2 (Mar 13, 2012)
  • Refactored to enable GitHub SQS plugin (pull #13).
Version 1.1 (Feb 11, 2012)
  • URL normalisation corrupts urls where the project name legitimately ends in 'tree/' (pull #10).
  • Global configuration not saved since Jenkins 1.445 (JENKINS-12487).
  • Also trigger jobs with GitHub repositories configured via MultipleSCMs plugin (pull #12).
  • Match git http:// urls which don't container a username@host since these are valid.
Version 1.0 (Jan 11, 2012)
  • the post-receive hook handling was not poking read-protected projects.
Version 0.9 (Jan 4, 2012)
  • Fixed a bug in handling organization's private repository pull #4
  • Updated to use a newer version of the github-api library.
Version 0.7 (Aug 27, 2011)
  • Supported ssh-based access to GitHub. pull #4
  • Fixed a bug in GitHub repository pattern matching that didn't allow "." in the name pull #3
Version 0.6 (Jul 21, 2011)
  • Added JGit explicitly to improve interaction with the Git plugin
Version 0.5 (Jun 10, 2011)
  • Added support for post-receive trigger
Version 0.4 (Feb 14, 2011)
  • Remove unused code

...

Pipeline examples

Setting commit status

This code will set commit status for custom repo with configured context and message (you can also define same way backref)

Code Block
void setBuildStatus(String message, String state) {
  step([
      $class: "GitHubCommitStatusSetter",
      reposSource: [$class: "ManuallyEnteredRepositorySource", url: "https://github.com/my-org/my-repo"],
      contextSource: [$class: "ManuallyEnteredCommitContextSource", context: "ci/jenkins/build-status"],
      errorHandlers: [[$class: "ChangingBuildStatusErrorHandler", result: "UNSTABLE"]],
      statusResultSource: [ $class: "ConditionalStatusResultSource", results: [[$class: "AnyBuildResult", message: message, state: state]] ]
  ]);
}

setBuildStatus("Build complete", "SUCCESS");

More complex examle (can be used with multiply scm sources in pipeline)

Code Block
def getRepoURL() {
  sh "git config --get remote.origin.url > .git/remote-url"
  return readFile(".git/remote-url").trim()
}

def getCommitSha() {
  sh "git rev-parse HEAD > .git/current-commit"
  return readFile(".git/current-commit").trim()
}

def updateGithubCommitStatus(build) {
  // workaround https://issues.jenkins-ci.org/browse/JENKINS-38674
  repoUrl = getRepoURL()
  commitSha = getCommitSha()

  step([
    $class: 'GitHubCommitStatusSetter',
    reposSource: [$class: "ManuallyEnteredRepositorySource", url: repoUrl],
    commitShaSource: [$class: "ManuallyEnteredShaSource", sha: commitSha],
    errorHandlers: [[$class: 'ShallowAnyErrorHandler']],
    statusResultSource: [
      $class: 'ConditionalStatusResultSource',
      results: [
        [$class: 'BetterThanOrEqualBuildResult', result: 'SUCCESS', state: 'SUCCESS', message: build.description],
        [$class: 'BetterThanOrEqualBuildResult', result: 'FAILURE', state: 'FAILURE', message: build.description],
        [$class: 'AnyBuildResult', state: 'FAILURE', message: 'Loophole']
      ]
    ]
  ])
}

Change Log

GitHub Releases

Open Issues

Jira Issues
columnstype,key,summary,status,updated,created
anonymoustrue
urlhttps://issues.jenkins-ci.org/sr/jira.issueviews:searchrequest-xml/temp/SearchRequest.xml?jqlQuery=component+%3D+github-plugin+AND+status+in+%28Open%2C+%22In+Progress%22%2C+Reopened%29+ORDER+BY+updated+DESC&tempMax=1000