Merge branch 'master' into bom

.github/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to GitHub Branch Source
+Community pull requests are encouraged and welcomed! Following are some guidelines for what to expect.
+
+## Getting started
+For information on contributing to Jenkins in general, check out the 
+[Beginner's Guide](https://wiki.jenkins-ci.org/display/JENKINS/Beginners+Guide+to+Contributing) to contributing to 
+Jenkins. Also, please make sure to read the [Jenkins Code of Conduct](https://jenkins.io/project/conduct/). The main 
+[jenkins.io website](https://jenkins.io/doc/developer) has lots of information about developing and extending Jenkins, 
+including several [how-to guides](https://jenkins.io/doc/developer/guides/) about plugin development.
+
+## Being careful
+
+GitHub Branch Source is one of the most widely used plugins in the Jenkins plugin catalog. 
+It is relied upon by hundreds of thousands of people worldwide. Because of this huge install 
+base, caution must be exercised when making changes. Code changes are reviewed 
+with a high level of scrutiny, out of necessity. This level of thoroughness should not be interpreted 
+as a personal attack. (And, of course, if someone feels it is a personal attack, that's why we have the 
+[Code of Conduct](https://jenkins.io/project/conduct/) in place).
+
+## How to submit your contribution
+
+Changes should come in the form of pull requests to the master branch of the main repository. Contributors 
+may do so from the origin repository, e.g. 
+`https://github.com/jenkinsci/github-branch-source-plugin`, or from their own fork, e.g. 
+`https://github.com/firstTimeContributor/github-branch-source-plugin`. 
+
+Changes should never be made directly to master. This holds true for all contributions, 
+no matter the person or the change. Pull requests allow for easy code review. 
+
+High-impact security patches may sometimes follow an accelerated process. The 
+[Jenkins Security team's process](https://jenkins.io/security/) describes how to report, and 
+work on, security vulnerabilities in Jenkins plugins.
+
+Any new functionality, API changes, or bug fixes must include adequate automated test coverage. 
+If you feel that your pull request does not need its own test coverage, state this in 
+the description, including the reason(s) why. 
+
+Please use human-readable commit messages. When your code is being reviewed, a commit message like 
+`Add unit test for whizBang.getSomethingAwesome` is far more useful than `testcase`.
+
+If your PR relies on open PRs in other plugins, please include references to them in your 
+PR. This makes it easy for reviewers to navigate between all of the relevant PRs.
+
+## Associating changes with existing Jira issues
+
+If your PR is in response to an existing issue (bug, improvement, etc) in 
+[the Jenkins JIRA](https://issues.jenkins-ci.org/secure/Dashboard.jspa), include the issue 
+key in the subject line, with `[` `]` square brackets surrounding it. For example,
+`[JENKINS-12345] Improve GitHub Branch Source with fluxCapacitor module`. This keeps the issue 
+easy to see in what can become a long list of PRs.
+
+## Creating a new Jira issue for your contribution
+
+When proposing new features or enhancements, potential contributors should file a Jira issue first, 
+describing their proposed changes and potential implementation details. Consensus can be reached in 
+the Jira issue before the PR is filed. This prevents surprising plugin maintainers, and prevents 
+contributors from having large amounts of work refused.
+
+Trivial changes might not warrant filing a Jira issue; although there is no harm in filing 
+one anyway. Larger changes, which have noticeable impact on your fellow users and developers, 
+should always have a Jira issue filed for them. This Jira issue serves as a centralized 
+location for discussion about the change. 
+
+To give a sense of what constitutes a trivial change versus a larger one, here are some examples. 
+This is not intended to be an all-inclusive list, but it should give an idea:
+
+| Trivial Changes, no Jira needed | Larger Changes, file a Jira   | 
+| --------------------------------|-------------------------------|
+| Additional test coverage        | Entirely new functionality    |
+| Spelling, Grammar, other typos  | API Changes                   |
+| Edits to inline help            | New or updated dependencies   |
+| Cleaning up of unused imports   | User Interface changes        |
+
+## Testing your changes
+
+Before submitting your pull request, it needs to have been tested. This may take the form of 
+the automated tests you've included in your pull request - _you did include tests, right?_  
+To run your tests locally, simply building the plugin via `mvn clean install` will run all 
+of its tests locally. 
+
+Additionally, manual testing is welcomed and encouraged. If you've done some particularly clever 
+testing of your changes, please describe that in the description of your pull request, so that 
+your reviewers know what's already been done.
+
+Once submitted, your change will be built, and the plugin's tests will get run, on 
+[ci.jenkins.io](https://ci.jenkins.io). GitHub will be notified of the results of this build, 
+so you don't need to follow up and look for yourself. Your changes will be tested with combinations 
+of Java 8 and 11, on Linux and Windows.
+
+## The code review process
+
+We promise to be thoughtful, professional, and reasonable, and the same is expected of all 
+contributors. [Jenkins has a Code of Conduct](https://jenkins.io/project/conduct/), and we 
+take that seriously. We want the Jenkins community to be an open and welcoming one, for all 
+contributors, no matter how seasoned.
+
+In order to have your PR merged or considered for merging, you must respond to all actionable 
+feedback.
+
+## Merging and releasing
+
+The process by which pull requests get merged to master is fairly simple, and is described 
+in the [guide for releasing a plugin](https://jenkins.io/doc/developer/publishing/releasing/).
+In short, once changes are merged to master, a release can be generated. Final decisions 
+on merging and releasing fall to the plugin's maintainer.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,24 @@
-* JENKINS issue(s):
-    * Issue link or n/a
-* Description:
-    * ...
-* Documentation changes:
-    * Link to related jenkins.io PR or explanation for why doc change not needed
-* Users/aliases to notify:
-    * ...
+# Description
+
+A brief summary describing the changes in this pull request. See 
+[JENKINS-XXXXX](https://issues.jenkins-ci.org/browse/JENKINS-XXXXX) for further information. 
+
+<!--
+In the lists below, fill in the empty checkboxes [ ] with checks by replacing the space with an x, like [x].
+-->
+# Submitter checklist
+- [ ] Link to JIRA ticket in description, if appropriate.
+- [ ] Change is code complete and matches issue description
+- [ ] Automated tests have been added to exercise the changes
+- [ ] Reviewer's manual test instructions provided in PR description. See Reviewer's first task below.
+
+# Reviewer checklist
+- [ ] Run the changes and verify that the change matches the issue description
+- [ ] Reviewed the code
+- [ ] Verified that the appropriate tests have been written or valid explanation given
+
+# Documentation changes
+- [ ] Link to jenkins.io PR, or an explanation for why no doc changes are needed
+
+# Users/aliases to notify
+

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+For version 2.6.0 and beyond, see the [GitHub releases](https://github.com/jenkinsci/github-branch-source-plugin/releases) list. 
+
 ## Version 2.5.8
 Release date: 2019-09-27
 
@@ -42,7 +44,7 @@ are in-flight (dependency on Jenkins Core v2.167)
 ## Version 2.5.3
 Release date: 2019-05-23
 
--   [JENKINS-57583](https://issues.jenkins-ci.org/browse/JENKINS-57583): Fixed compatibility with the "Ignore target brach" setting
+-   [JENKINS-57583](https://issues.jenkins-ci.org/browse/JENKINS-57583): Fixed compatibility with the "Ignore target branch" setting
 
 -   [JENKINS-57371](https://issues.jenkins-ci.org/browse/JENKINS-57371): Added graceful fallback to cloning for PRs when needed 
 

README.md

@@ -1,15 +1,25 @@
  # GitHub Branch Source Plugin
 
 [![Jenkins Plugin](https://img.shields.io/jenkins/plugin/v/github-branch-source)](https://plugins.jenkins.io/github-branch-source)
-[![Changelog](https://img.shields.io/github/v/tag/jenkinsci/github-branch-source-plugin?label=changelog)](https://github.com/jenkinsci/github-branch-source/blob/master/CHANGELOG.md)
+[![Changelog](https://img.shields.io/github/v/tag/jenkinsci/github-branch-source-plugin?label=changelog)](https://github.com/jenkinsci/github-branch-source-plugin/blob/master/CHANGELOG.md)
 [![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/github-branch-source?color=blue)](https://plugins.jenkins.io/github-branch-source)
-[![Contributors](https://img.shields.io/github/contributors/jenkinsci/github-branch-source-plugin.svg)](https://github.com/jenkinsci/github-branch-source/contributors)
+[![Contributors](https://img.shields.io/github/contributors/jenkinsci/github-branch-source-plugin.svg)](https://github.com/jenkinsci/github-branch-source-plugin/contributors)
 
 ## 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. Complete documentation is 
 [hosted by CloudBees](https://docs.cloudbees.com/docs/admin-resources/latest/plugins/github-branch-source).
 
+### Guides
+
+* [GitHub App authentication](docs/github-app.adoc)
+* [Extension points provided by this plugin](docs/implementation.adoc)
+
+## Extension plugins
+
+* [github-scm-trait-notification-context](https://github.com/jenkinsci/github-scm-trait-notification-context-plugin) -
+allows overriding the `continuous-integration/jenkins/<context>` commit status name.
+
 ## Version History
 
 See [the changelog](CHANGELOG.md).

docs/github-app.adoc

@@ -0,0 +1,140 @@
+= GitHub app authentication guide
+
+This guide is targeted to users who want to use a link:https://developer.github.com/v3/apps/[GitHub app]
+to authenticate to Jenkins.
+
+== Why?
+
+- the link:https://developer.github.com/apps/building-github-apps/understanding-rate-limits-for-github-apps/[rate limit]
+for a GitHub app scales with your organization size, whereas a user based token has a limit of 5000 regardless of
+how many repositories you have,
+- for organization's that have 2fa enforced - no need to manage 2fa tokens for a 'bot' user
+- to improve and tighten security: the Jenkins GitHub app requires a minimum, controlled set of privileges compared to a service user and its personal access token which has a much wider set of privileges
+
+== Getting started
+
+Before you get started make sure you have the required permissions:
+
+=== GitHub
+
+You'll need the permission to create a GitHub app, if you're creating it on a personal account then you can skip this section,
+otherwise:
+
+- organization owner
+
+or
+
+- permission to manage GitHub apps has been
+link:https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/adding-github-app-managers-in-your-organization[delegated to you].
+
+=== Jenkins
+
+You'll need the permission to create a new credential and update job configuration, the specific permissions are:
+
+- Credentials/Create
+- Job/Configure
+
+== Creating the GitHub app
+
+link:https://developer.github.com/apps/building-github-apps/creating-a-github-app/[Follow the GitHub guide for creating an app]
+
+The only fields you need to fill out (currently) are:
+
+- Github App name - i.e. `Jenkins - <team name>`
+- Homepage URL - your company domain or a github repository
+- Webhook URL - your jenkins instance, i.e. `https://<jenkins-host>/github-webhook/`
+
+Permissions this plugin uses:
+
+- Commit statuses - Read and Write
+- Contents: Read-only (to read the `Jenkinsfile` and the repository content during `git fetch`). You may need "Read & write" to update the repository such as tagging releases
+- Metadata: Read-only
+- Pull requests: Read-only
+- Webhooks (optional) - If you want the plugin to manage webhooks for you, Read and Write
+
+
+Click 'Create GitHub app'
+
+You now need to generate a private key authenticating to the GitHub app
+
+Click the 'generate a private key' option.
+
+After a couple of seconds the key will be downloaded to your downloads folder.
+
+Now you need to convert the key into a different format that Jenkins can use:
+
+[source,shell]
+----
+openssl pkcs8 -topk8 -inform PEM -outform PEM -in key-in-your-downloads-folder.pem -out converted-github-app.pem -nocrypt
+----
+
+== Install the GitHub app
+
+- From the install app section of newly created app, install the app to your organization.
+
+== Adding the Jenkins credential
+
+=== UI
+
+- From the Jenkins main page click 'Credentials'
+- Pick your credential store, normally `(global)`
+- Click 'Add credentials'
+
+Fill out the form:
+
+- Kind: GitHub app
+- ID: i.e. github-app-<team-name>
+- App ID: the github app ID, it can be found in the 'About' section of your GitHub app in the general tab.
+- API endpoint (optional, only required for GitHub enterprise this will only show up if a GitHub enterprise server is configured).
+- Key: click add, paste the contents of the converted private key
+- Passphrase: do not fill this field, it will be ignored
+- Click OK
+
+=== link:https://github.com/jenkinsci/configuration-as-code-plugin[Configuration as Code Plugin]
+
+[source,yaml]
+----
+credentials:
+  system:
+    domainCredentials:
+      - credentials:
+        - gitHubApp:
+            appID: "1111"
+            description: "GitHub app"
+            id: "github-app"
+            # apiUri: https://my-custom-github-enterprise.com/api/v3 # optional only required for GitHub enterprise
+            privateKey: "${GITHUB_APP_KEY}"
+----
+
+== Configuring the github organization folder
+
+See the link:https://docs.cloudbees.com/docs/admin-resources/latest/plugins/github-branch-source[main documentation]
+for how to create a GitHub folder.
+
+- Load the folders configuration page
+- Select the GitHub app credentials in the 'Credentials field drop down
+- If you are using GitHub enterprise make sure the API url is set to your server,
+(note you currently need to set the API url on both the credential and the job).
+
+After selecting the credential you should see:
+
+[quote]
+----
+GHApp verified, remaining rate limit: 5000
+----
+
+- Click save
+- Click 'Scan organization now'
+- Click 'Scan organisation log'
+
+Verify at the bottom of the scan log it says:
+
+[quote]
+----
+Finished: SUCCESS
+----
+
+=== Help?
+
+Raise an issue on link:https://issues.jenkins-ci.org/[Jenkins jira]
+setting the 'component' to be `github-brance-source-plugin`

docs/implementation.adoc

@@ -45,6 +45,6 @@ explicitly apply a `DefaultGitHubNotificationStrategy` to the source context in
 Duplicate (by equality) strategies are ignored when applied to the source context.
 
 ==== Implementations:
-https://github.com/steven-foster/github-scm-trait-notification-context[github-scm-trait-notification-context]
+https://github.com/jenkinsci/github-scm-trait-notification-context-plugin[github-scm-trait-notification-context]
 
 

pom.xml

@@ -21,13 +21,14 @@
     </licenses>
 
     <properties>
-        <revision>2.5.9</revision>
+        <revision>2.6.1</revision>
         <changelist>-SNAPSHOT</changelist>
         <hpi.compatibleSinceVersion>2.2.0</hpi.compatibleSinceVersion>
         <java.level>8</java.level>
         <jenkins.version>2.150.3</jenkins.version>
         <useBeta>true</useBeta>
         <jcasc.version>1.35</jcasc.version>
+        <jjwt.version>0.10.5</jjwt.version>
     </properties>
 
     <scm>