Skip to content
This repository was archived by the owner on Jun 9, 2021. It is now read-only.

Commit f6e6fe6

Browse files
tomasbjerretomasbjerre
committed
Adding HipChat documentation #187
* The HipChat docs were privided by [Rychard](https://github.com/Rychard). * Moving Jenkins docs to its own file. * Moving issue reporting guidelines to ISSUE_TEMPLATE.
1 parent 51f4c60 commit f6e6fe6

File tree

5 files changed

+139
-76
lines changed

5 files changed

+139
-76
lines changed

‎ISSUE_TEMPLATE‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
If things don't work as you expect, perhaps you should file an issue. But first, try troubleshooting it and provide as much info as possible. Here are some things that may help if added to an issue.
2+
3+
* Plugin version used.
4+
* Bitbucket Server version used.
5+
* Stack traces in Bitbucket Server log file.
6+
* Any browser console log messages, you can find it in Developer Tools in Chome by pressing F12.
7+
* Screenshot of plugin configuration in your issue.
8+
* Your configuration.
9+
You can get it with something like this:
10+
11+
`curl -u admin:admin 'http://localhost:7990/bitbucket/rest/prnfb-admin/1.0/settings' -H 'Accept: application/json, text/javascript, */*; q=0.01'`
12+
13+
`curl -u admin:admin 'http://localhost:7990/bitbucket/rest/prnfb-admin/1.0/settings/notifications' -H 'Accept: application/json, text/javascript, */*; q=0.01'`.
14+
15+
`curl -u admin:admin 'http://localhost:7990/bitbucket/rest/prnfb-admin/1.0/settings/buttons' -H 'Accept: application/json, text/javascript, */*; q=0.01'`.
16+
* If the system you are trying to notify does not seem to get notified you may check that the triggered URL looks as expected. You can do that by invoking https://requestb.in/ and inspect its results.

‎README.md‎

Lines changed: 4 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -217,84 +217,12 @@ It will respond with something like this.
217217

218218
You may use Chrome and Developer Tools (press F12) to view rest calls while editing in GUI to find more examples.
219219

220-
### Jenkins
221-
Parameterized Jenkins jobs can be triggered remotely by invoking a URL. How you trigger your Jennkins installation may vary depending on how it is configured. Here is, probably, the most complicated scenario where there is CSRF protection and authentication requirements.
220+
## Integration guides
222221

223-
The job that you want to trigger must have:
224-
* *This build is parameterized* checkbox checked.
225-
* *Trigger builds remotely* checkbox checked.
226-
* You may, or may not, use a token here.
222+
Here are some guides on how to use the plugin with different systems. Feel free to add guides through pull requests to this repo!
227223

228-
I like to add an *Execute shell* build step and then just do `echo param: $paramName` to test that my parameter shows up in the build job log.
229-
230-
First, you may try to trigger Jenkins with [Curl](https://github.com/curl/curl) from command line and then, when you know how it should be done, configure the plugin.
231-
232-
If your Jenkins is CSRF protected, you need to get a crumb. It can be done like this.
233-
```
234-
curl -s 'http://JENKINS_HOSTNAME/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'
235-
```
236-
237-
The response should be something like `Jenkins-Crumb:f122c77298b349b0116140265418ec7f`.
238-
239-
Now you can trigger a build like this (just remove `?token=YOUR_TOKEN` if you are not using a token).
240-
241-
```
242-
curl -u USERNAME:PASSWORD -X POST --data "paramName=paramValue" -H "Jenkins-Crumb:f122c77298b349b0116140265418ec7f" http://JENKINS_HOSTNAME/job/JENKINS_JOB/buildWithParameters?token=YOUR_TOKEN
243-
```
244-
245-
Now that job should have been triggered and you should be able to verify that Jenkins is setup correclty. You may want to SSH to the Bitbucket Server machine and do this, to also verify that firewalls are open.
246-
247-
Now to configure the plugin!
248-
249-
If you need ***authentication***, add your username and password in *Basic authentication*.
250-
251-
If you are using a ***CSRF*** protection in Jenkins, you can use the **Injection URL** feature.
252-
* Set **Injection URL** field to `http://JENKINS_HOSTNAME/crumbIssuer/api/xml?xpath=//crumb/text()`.
253-
* You may get an error like *primitive XPath result sets forbidden; implement jenkins.security.SecureRequester*. If so, you can set Injection URL to `http://JENKINS/crumbIssuer/api/xml?xpath=//crumb` in combination with regular expression `<crumb>([^<]*)</crumb>`.
254-
* A third option is to checkout [this](https://wiki.jenkins-ci.org/display/JENKINS/Secure+Requester+Whitelist+Plugin) Jenkins plugin.
255-
* In the headers section, set header **Jenkins-Crumb** with value **${INJECTION_URL_VALUE}**. The `Jenkins-Crumb` header name was previously just `.crumb`, use whatever the `curl` command responded with above.
256-
257-
You may trigger the build with `GET` or `POST`.
258-
259-
In ***URL*** add `http://JENKINS_HOSTNAME/job/JENKINS_JOB/buildWithParameters?token=YOUR_TOKEN&paramName=paramValue`.
260-
261-
Thats it! There are some common mistakes.
262-
* If using ${EVERYTHING_URL}, like `...?token=token&${EVERYTHING_URL}` then in your jenkins job you have to have parameters for each parameter, like `PULL_REQUEST_URL`.
263-
* Even when using `POST`, you should add the parameters to the `URL`.
264-
265-
#### Jenkins build step
266-
To perform the merge and verify that the pull request builds in its target branch, I do something like this.
267-
268-
```
269-
git clone $TO_REPO
270-
cd *
271-
git reset --hard $TO_HASH
272-
git status
273-
git remote add from $FROM_REPO
274-
git fetch --all
275-
git merge $FROM_HASH
276-
git --no-pager log --max-count=10 --graph --abbrev-commit
277-
278-
#compile command here ...
279-
```
280-
281-
## Reporting issues
282-
If things don't work as you expect, perhaps you should file an issue. But first, try troubleshooting it and provide as much info as possible. Here are some things that may help if added to an issue.
283-
284-
* Plugin version used.
285-
* Bitbucket Server version used.
286-
* Stack traces in Bitbucket Server log file.
287-
* Any browser console log messages, you can find it in Developer Tools in Chome by pressing F12.
288-
* Screenshot of plugin configuration in your issue.
289-
* Your configuration.
290-
You can get it with something like this:
291-
292-
`curl -u admin:admin 'http://localhost:7990/bitbucket/rest/prnfb-admin/1.0/settings' -H 'Accept: application/json, text/javascript, */*; q=0.01'`
293-
294-
`curl -u admin:admin 'http://localhost:7990/bitbucket/rest/prnfb-admin/1.0/settings/notifications' -H 'Accept: application/json, text/javascript, */*; q=0.01'`.
295-
296-
`curl -u admin:admin 'http://localhost:7990/bitbucket/rest/prnfb-admin/1.0/settings/buttons' -H 'Accept: application/json, text/javascript, */*; q=0.01'`.
297-
* If the system you are trying to notify does not seem to get notified you may check that the triggered URL looks as expected. You can do that by invoking https://requestb.in/ and inspect its results.
224+
* [Jenkins](https://github.com/tomasbjerre/pull-request-notifier-for-bitbucket/blob/master/README_jenkins.md)
225+
* [HipChat](https://github.com/tomasbjerre/pull-request-notifier-for-bitbucket/blob/master/README_hipchat.md)
298226

299227
## Developer instructions
300228
There are some scripts to help working with the plugin.

‎README_hipchat.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Send Pull Request Notifications to HipChat Room
2+
3+
1. Provision an API Token for HipChat
4+
- Login to the Hipchat website
5+
- Click the `Edit Profile` button in the top-right
6+
- Click `API Access` in the navigation menu on the left
7+
- Enter some descriptive text for the `Label`, select `Send Notification` from the `Scopes` combo box, and click the `Create` button
8+
- Copy the token from the grid; this is needed to authenticate the request
9+
> **Note:** This value allows API requests to be authenticated as your HipChat user for the selected actions. For that reason, this token should be kept private! It is recommended to create individual tokens for every application that uses the HipChat API, to minimize risk if the token is compromised.
10+
11+
1. Get the `API ID` for the HipChat room that will receive notifications
12+
- Login to the Hipchat website
13+
- Click on `Rooms` in the navigation bar below the welcome banner
14+
- Under the `Active` tab, click the name of the room that will receive notifications
15+
- Copy the `API ID` from the grid, this will be included in the notification request
16+
17+
1. Configure Bitbucket to send notifications to a HipChat room
18+
- In Bitbucket, go to the repository that will trigger HipChat notifications
19+
- Click `Settings` (a gear icon, if the sidebar is not expanded)
20+
- Click `Pull request notifications` under the `ADD-ONS` heading in the navigation menu on the left.
21+
- Scroll down to `Notifications`.
22+
- Configure triggers as desired
23+
- Configure the URL and Headers sections to communicate with HipChat:
24+
- **URL**: `https://api.hipchat.com/v2/room/{roomId}/notification`
25+
> Use the `API ID` of the room in place of `{roomId}` in the url above.
26+
27+
- **Post content**:
28+
```json
29+
{
30+
"from": "Bitbucket Pull Request",
31+
"color": "green",
32+
"message_format": "text",
33+
"message": "${PULL_REQUEST_DESCRIPTION}",
34+
"card": {
35+
"id": "${PULL_REQUEST_FROM_HASH}",
36+
"style": "link",
37+
"description": {
38+
"value": "${PULL_REQUEST_DESCRIPTION}",
39+
"format": "text"
40+
},
41+
"format": "compact",
42+
"notify": false,
43+
"url": "${PULL_REQUEST_URL}",
44+
"title": "[${PULL_REQUEST_FROM_REPO_NAME}] ${PULL_REQUEST_TITLE} (#${PULL_REQUEST_ID})"
45+
}
46+
}
47+
```
48+
- **Headers**:
49+
50+
| Name | Value |
51+
| :-------------- | :------------------ |
52+
| `Content-Type` | `application/json` |
53+
| `Authorization` | `Bearer {apiToken}` |
54+
> Use the `API Token` in place of `{apiToken}` in the above value.
55+
56+
1. Trigger your notification by performing one of the actions you configured earlier
57+
![](https://raw.githubusercontent.com/tomasbjerre/pull-request-notifier-for-bitbucket/master/sandbox/hipchat.png)
58+
59+
For further customization of the HipChat notification, refer to the [official documentation](https://www.hipchat.com/docs/apiv2/method/send_room_notification).

‎README_jenkins.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Jenkins
2+
Parameterized Jenkins jobs can be triggered remotely by invoking a URL. How you trigger your Jennkins installation may vary depending on how it is configured. Here is, probably, the most complicated scenario where there is CSRF protection and authentication requirements.
3+
4+
The job that you want to trigger must have:
5+
* *This build is parameterized* checkbox checked.
6+
* *Trigger builds remotely* checkbox checked.
7+
* You may, or may not, use a token here.
8+
9+
I like to add an *Execute shell* build step and then just do `echo param: $paramName` to test that my parameter shows up in the build job log.
10+
11+
First, you may try to trigger Jenkins with [Curl](https://github.com/curl/curl) from command line and then, when you know how it should be done, configure the plugin.
12+
13+
If your Jenkins is CSRF protected, you need to get a crumb. It can be done like this.
14+
```
15+
curl -s 'http://JENKINS_HOSTNAME/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'
16+
```
17+
18+
The response should be something like `Jenkins-Crumb:f122c77298b349b0116140265418ec7f`.
19+
20+
Now you can trigger a build like this (just remove `?token=YOUR_TOKEN` if you are not using a token).
21+
22+
```
23+
curl -u USERNAME:PASSWORD -X POST --data "paramName=paramValue" -H "Jenkins-Crumb:f122c77298b349b0116140265418ec7f" http://JENKINS_HOSTNAME/job/JENKINS_JOB/buildWithParameters?token=YOUR_TOKEN
24+
```
25+
26+
Now that job should have been triggered and you should be able to verify that Jenkins is setup correclty. You may want to SSH to the Bitbucket Server machine and do this, to also verify that firewalls are open.
27+
28+
Now to configure the plugin!
29+
30+
If you need ***authentication***, add your username and password in *Basic authentication*.
31+
32+
If you are using a ***CSRF*** protection in Jenkins, you can use the **Injection URL** feature.
33+
* Set **Injection URL** field to `http://JENKINS_HOSTNAME/crumbIssuer/api/xml?xpath=//crumb/text()`.
34+
* You may get an error like *primitive XPath result sets forbidden; implement jenkins.security.SecureRequester*. If so, you can set Injection URL to `http://JENKINS/crumbIssuer/api/xml?xpath=//crumb` in combination with regular expression `<crumb>([^<]*)</crumb>`.
35+
* A third option is to checkout [this](https://wiki.jenkins-ci.org/display/JENKINS/Secure+Requester+Whitelist+Plugin) Jenkins plugin.
36+
* In the headers section, set header **Jenkins-Crumb** with value **${INJECTION_URL_VALUE}**. The `Jenkins-Crumb` header name was previously just `.crumb`, use whatever the `curl` command responded with above.
37+
38+
You may trigger the build with `GET` or `POST`.
39+
40+
In ***URL*** add `http://JENKINS_HOSTNAME/job/JENKINS_JOB/buildWithParameters?token=YOUR_TOKEN&paramName=paramValue`.
41+
42+
Thats it! There are some common mistakes.
43+
* If using ${EVERYTHING_URL}, like `...?token=token&${EVERYTHING_URL}` then in your jenkins job you have to have parameters for each parameter, like `PULL_REQUEST_URL`.
44+
* Even when using `POST`, you should add the parameters to the `URL`.
45+
46+
#### Jenkins build step
47+
To perform the merge and verify that the pull request builds in its target branch, I do something like this.
48+
49+
```
50+
git clone $TO_REPO
51+
cd *
52+
git reset --hard $TO_HASH
53+
git status
54+
git remote add from $FROM_REPO
55+
git fetch --all
56+
git merge $FROM_HASH
57+
git --no-pager log --max-count=10 --graph --abbrev-commit
58+
59+
#compile command here ...
60+
```

‎sandbox/hipchat.png‎

14.4 KB
Loading

0 commit comments

Comments
 (0)