Skip to content
This repository was archived by the owner on Sep 25, 2020. It is now read-only.

Commit 51dc96b

Browse files
KostyaShaKostyaSha
authored
Merge pull request jenkinsci#224 from timja/docs-migration
Documentation migration
2 parents 7833dca + 603365b commit 51dc96b

8 files changed

Lines changed: 246 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 243 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,254 @@
1-
Jenkins Github Plugin
2-
=====================
1+
# Github Plugin
32

43
[![codecov](https://codecov.io/gh/jenkinsci/github-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/jenkinsci/github-plugin)
54
[![License](https://img.shields.io/github/license/jenkinsci/github-plugin.svg)](LICENSE)
6-
[![wiki](https://img.shields.io/badge/GitHub%20Plugin-WIKI-blue.svg?style=flat)](http://wiki.jenkins-ci.org/display/JENKINS/Github+Plugin)
75

6+
This plugin integrates Jenkins with [Github](http://github.com/)
7+
projects.The plugin currently has three major functionalities:
88

9-
Development
10-
===========
9+
- Create hyperlinks between your Jenkins projects and GitHub
10+
- Trigger a job when you push to the repository by groking HTTP POSTs
11+
from post-receive hook and optionally auto-managing the hook setup.
12+
- Report build status result back to github as [Commit
13+
Status](https://github.com/blog/1227-commit-status-api) ([documented
14+
on
15+
SO](https://stackoverflow.com/questions/14274293/show-current-state-of-jenkins-build-on-github-repo/26910986#26910986))
16+
- Base features for other plugins
17+
18+
## Hyperlinks between changes
19+
20+
The Github plugin decorates Jenkins "Changes" pages to create links to
21+
your Github commit and issue pages. It adds a sidebar link that links
22+
back to the Github project page.
23+
24+
![](/docs/images/changes.png)
25+
![](/docs/images/changes-2.png)
26+
27+
When creating a job, specify that is connects to git. Under "Github
28+
project", put in: [email protected]:*Person*/*Project*.git Under "Source
29+
Code Management" select Git, and put in
30+
[email protected]:*Person*/*Project*.git
31+
32+
## GitHub hook trigger for GITScm polling
33+
34+
This feature enables builds after [post-receive hooks in your GitHub
35+
repositories](https://help.github.com/post-receive-hooks/). This trigger
36+
only kicks git-plugin internal polling algo for every incoming event
37+
against matched repo.
38+
39+
Old name
40+
41+
Previously named as "Build when a change is pushed to GitHub"
42+
43+
To be able to use this feature:
44+
45+
### Manual Mode
46+
47+
In this mode, you'll be responsible for registering the hook URLs to
48+
GitHub. Click the
49+
![(question)](/docs/images/help_16.svg)
50+
icon (under Manage Jenkins \> Configure System \> GitHub) to see the URL
51+
in Jenkins that receives the post-commit POSTs — but in general the URL
52+
is of the form `$JENKINS_BASE_URL/github-webhook/` — for example:
53+
`https://ci.example.com/jenkins/github-webhook/`.
54+
55+
Once you have the URL, and have added it as a webhook to the relevant
56+
GitHub repositories, continue to **Step 3**.
57+
58+
### Automatic Mode (Jenkins manages hooks for jobs by itself)
59+
60+
In this mode, Jenkins will automatically add/remove hook URLs to GitHub
61+
based on the project configuration in the background. You'll specify
62+
GitHub OAuth token so that Jenkins can login as you to do this.
63+
64+
**Step 1.** Go to the global configuration and add GitHub Server Config.
65+
66+
![](/docs/images/ghserver-config.png)
67+
68+
**Step 2.1.** Create your personal access token in GitHub.
69+
70+
Plugin can help you to do it with all required scopes. Go to
71+
**Advanced** -\> **Manage Additional GitHub Actions** -\> **Convert
72+
Login and Password to token**
73+
74+
![](/docs/images/manage-token.png)
75+
76+
Two-Factor Authentication
77+
78+
Auto-creating token doesn't work with [GitHub
79+
2FA](https://help.github.com/articles/about-two-factor-authentication/)
80+
81+
You can create **"Secret text"** credentials with token in corresponding
82+
domain with login and password directly, or from username and password
83+
credentials.
84+
85+
**Step 2.2.** Select previously created "Secret Text" credentials with
86+
GitHub OAuth token.
87+
88+
Required scopes for token
89+
90+
To be able manage hooks your token should have **admin:org\_hook**
91+
scope.
92+
93+
GitHub Enterprise
94+
95+
You can also redefine GitHub url by clicking on **Custom GitHub API
96+
URL** checkbox.
97+
Note that credentials are filtered by entered GH url with help of domain
98+
requirements. So you can create credentials in different domains and see
99+
only credentials that matched by predefined domains.
100+
101+
![](/docs/images/secret-text.png)
102+
103+
**Step 3.** Once that configuration is done, go to the project config of
104+
each job you want triggered automatically and simply check "Build when a
105+
change is pushed to GitHub" under "Build Triggers". With this, every new
106+
push to the repository automatically triggers a new build.
107+
108+
Note that there's only one URL and it receives all post-receive POSTs
109+
for all your repositories. The server side of this URL is smart enough
110+
to figure out which projects need to be triggered, based on the
111+
submission.
112+
113+
#### Security Implications
114+
115+
This plugin requires that you have an HTTP URL reachable from GitHub,
116+
which means it's reachable from the whole internet. So it is implemented
117+
carefully with the possible malicious fake post-receive POSTS in mind.
118+
To cope with this, upon receiving a POST, Jenkins will talk to GitHub to
119+
ensure the push was actually made.
120+
121+
#### Jenkins inside a firewall
122+
123+
In case your Jenkins run inside the firewall and not directly reachable
124+
from the internet, this plugin lets you specify an arbitrary endpoint
125+
URL as an override in the automatic mode. The plugin will assume that
126+
you've set up reverse proxy or some other means so that the POST from
127+
GitHub will be routed to the Jenkins.
128+
129+
#### Trouble-shooting hooks
130+
131+
If you set this up but build aren't triggered, check the following
132+
things:
133+
134+
- Click the "admin" button on the GitHub repository in question and
135+
make sure post-receive hooks are there.
136+
- If it's not there, make sure you have proper credential set in
137+
the Jenkins system config page.
138+
- Also, [enable
139+
logging](https://wiki.jenkins.io/display/JENKINS/Logging) for the
140+
class names
141+
- `com.cloudbees.jenkins.GitHubPushTrigger`
142+
- `org.jenkinsci.plugins.github.webhook.WebhookManager`
143+
- `com.cloudbees.jenkins.GitHubWebHook`
144+
and you'll see the log of Jenkins trying to install a
145+
post-receive hook.
146+
- Click "Test hook" button from the GitHub UI and see if Jenkins
147+
receive a payload.
148+
149+
#### Using cache to GitHub requests
150+
151+
Each **GitHub Server Config** creates own GitHub client to interact with
152+
api. By default it uses cache (with **20MB** limit) to speedup process
153+
of fetching data and reduce rate-limit consuming. You can change cache
154+
limit value in "Advanced" section of this config item. If you set 0,
155+
then this feature will be disabled for this (and only this) config.
156+
157+
Additional info:
158+
159+
- This plugin now serves only hooks from github as main feature. Then
160+
it starts using git-plugin to fetch sources.
161+
- It works both public and Enterprise GitHub
162+
- Plugin have some
163+
[limitations](https://stackoverflow.com/questions/16323749/jenkins-github-plugin-inverse-branches)
164+
165+
## Possible Issues between Jenkins and GitHub
166+
167+
### Windows:
168+
169+
- In windows, Jenkins will use the the SSH key of the user it is
170+
running as, which is located in the %USERPROFILE%\\.ssh folder ( on
171+
XP, that would be C:\\Documents and Settings\\USERNAME\\.ssh, and on
172+
7 it would be C:\\Users\\USERNAME\\.ssh). Therefore, you need to
173+
force Jenkins to run as the user that has the SSH key configured. To
174+
do that, right click on My Computer, and hit "Manage". Click on
175+
"Services". Go to Jenkins, right click, and select  "Properties".
176+
Under the "Log On" tab, choose the user Jenkins will run as, and put
177+
in the username and password (it requires one). Then restart the
178+
Jenkins service by right clicking on Jenkins (in the services
179+
window), and hit "Restart".
180+
- Jenkins does not support passphrases for SSH keys. Therefore, if you
181+
set one while running the initial Github configuration, rerun it and
182+
don't set one.
183+
184+
## Pipeline examples
185+
186+
#### Setting commit status
187+
188+
This code will set commit status for custom repo with configured context
189+
and message (you can also define same way backref)
190+
191+
```groovy
192+
void setBuildStatus(String message, String state) {
193+
step([
194+
$class: "GitHubCommitStatusSetter",
195+
reposSource: [$class: "ManuallyEnteredRepositorySource", url: "https://github.com/my-org/my-repo"],
196+
contextSource: [$class: "ManuallyEnteredCommitContextSource", context: "ci/jenkins/build-status"],
197+
errorHandlers: [[$class: "ChangingBuildStatusErrorHandler", result: "UNSTABLE"]],
198+
statusResultSource: [ $class: "ConditionalStatusResultSource", results: [[$class: "AnyBuildResult", message: message, state: state]] ]
199+
]);
200+
}
201+
202+
setBuildStatus("Build complete", "SUCCESS");
203+
```
204+
205+
More complex examle (can be used with multiply scm sources in pipeline)
206+
207+
```groovy
208+
def getRepoURL() {
209+
sh "git config --get remote.origin.url > .git/remote-url"
210+
return readFile(".git/remote-url").trim()
211+
}
212+
213+
def getCommitSha() {
214+
sh "git rev-parse HEAD > .git/current-commit"
215+
return readFile(".git/current-commit").trim()
216+
}
217+
218+
def updateGithubCommitStatus(build) {
219+
// workaround https://issues.jenkins-ci.org/browse/JENKINS-38674
220+
repoUrl = getRepoURL()
221+
commitSha = getCommitSha()
222+
223+
step([
224+
$class: 'GitHubCommitStatusSetter',
225+
reposSource: [$class: "ManuallyEnteredRepositorySource", url: repoUrl],
226+
commitShaSource: [$class: "ManuallyEnteredShaSource", sha: commitSha],
227+
errorHandlers: [[$class: 'ShallowAnyErrorHandler']],
228+
statusResultSource: [
229+
$class: 'ConditionalStatusResultSource',
230+
results: [
231+
[$class: 'BetterThanOrEqualBuildResult', result: 'SUCCESS', state: 'SUCCESS', message: build.description],
232+
[$class: 'BetterThanOrEqualBuildResult', result: 'FAILURE', state: 'FAILURE', message: build.description],
233+
[$class: 'AnyBuildResult', state: 'FAILURE', message: 'Loophole']
234+
]
235+
]
236+
])
237+
}
238+
```
239+
240+
## Change Log
241+
242+
[GitHub Releases](https://github.com/jenkinsci/github-plugin/releases)
243+
244+
## Development
11245

12246
Start the local Jenkins instance:
13247

14248
mvn hpi:run
15249

16250

17-
Jenkins Plugin Maven goals
18-
--------------------------
251+
## Jenkins Plugin Maven goals
19252

20253
hpi:create Creates a skeleton of a new plugin.
21254

@@ -28,8 +261,7 @@ Jenkins Plugin Maven goals
28261
hpi:upload Posts the hpi file to java.net. Used during the release.
29262

30263

31-
How to install
32-
--------------
264+
## How to install
33265

34266
Run
35267

@@ -42,10 +274,9 @@ To install:
42274

43275
1. copy the resulting ./target/rdoc.hpi file to the $JENKINS_HOME/plugins directory. Don't forget to restart Jenkins afterwards.
44276

45-
2. or use the plugin management console (http://example.com:8080/pluginManager/advanced) to upload the hpi file. You have to restart Jenkins in order to find the plugin in the installed plugins list.
277+
2. or use the plugin management console (https://example.com:8080/pluginManager/advanced) to upload the hpi file. You have to restart Jenkins in order to find the plugin in the installed plugins list.
46278

47279

48-
Plugin releases
49-
---------------
280+
## Plugin releases
50281

51282
mvn release:prepare release:perform -Dusername=juretta -Dpassword=******

‎docs/images/changes-2.png‎

23 KB
Loading

‎docs/images/changes.png‎

29.7 KB
Loading

‎docs/images/ghserver-config.png‎

5.91 KB
Loading

‎docs/images/help_16.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/images/manage-token.png‎

2.83 KB
Loading

‎docs/images/secret-text.png‎

5.02 KB
Loading

‎pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
<packaging>hpi</packaging>
1616

1717
<name>GitHub plugin</name>
18-
<url>http://wiki.jenkins-ci.org/display/JENKINS/Github+Plugin</url>
18+
<url>https://github.com/jenkinsci/github</url>
1919
<licenses>
2020
<license>
2121
<name>MIT License</name>
22-
<url>http://www.opensource.org/licenses/mit-license.php</url>
22+
<url>https://www.opensource.org/licenses/mit-license.php</url>
2323
<distribution>repo</distribution>
2424
</license>
2525
</licenses>

0 commit comments

Comments
 (0)