diff options
author | Stan Hu <stanhu@gmail.com> | 2015-03-16 18:09:31 +0300 |
---|---|---|
committer | Stan Hu <stanhu@gmail.com> | 2015-03-16 19:33:18 +0300 |
commit | 055457360c6316e9a10dfc8ee18ef8c87655d8ad (patch) | |
tree | 15c67289a235f6ec34ea53b753957307af33ca84 /doc/project_services | |
parent | bacb05c554dfa8781c53c1db7a4f9a706e33fd50 (diff) |
Add HipChat integration documentation as this was a source of confusion
Diffstat (limited to 'doc/project_services')
-rw-r--r-- | doc/project_services/hipchat.md | 54 | ||||
-rw-r--r-- | doc/project_services/project_services.md | 2 |
2 files changed, 55 insertions, 1 deletions
diff --git a/doc/project_services/hipchat.md b/doc/project_services/hipchat.md new file mode 100644 index 00000000000..021a93a288f --- /dev/null +++ b/doc/project_services/hipchat.md @@ -0,0 +1,54 @@ +# Atlassian HipChat + +GitLab provides a way to send HipChat notifications upon a number of events, +such as when a user pushes code, creates a branch or tag, adds a comment, and +creates a merge request. + +## Setup + +GitLab requires the use of a HipChat v2 API token to work. v1 tokens are +not supported at this time. Note the differences between v1 and v2 tokens: + +HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 +token is allowed to send messages to *any* room. + +HipChat v2 API has tokens that are can be created using the Integrations tab +in the Group or Room admin page. By design, these are lightweight tokens that +allow GitLab to send messages only to *one* room. + +### Complete these steps in HipChat: + +1. Go to: https://admin.hipchat.com/admin +1. Click on "Group Admin" -> "Integrations". +1. Find "Build Your Own!" and click "Create". +1. Select the desired room, name the integration "GitLab", and click "Create". +1. In the "Send messages to this room by posting this URL" column, you should +see a URL in the format: + +``` + https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> +``` + +HipChat is now ready to accept messages from GitLab. Next, set up the HipChat +service in GitLab. + +### Complete these steps in GitLab: + +1. Navigate to the project you want to configure for notifications. +1. Select "Settings" in the top navigation. +1. Select "Services" in the left navigation. +1. Click "HipChat". +1. Select the "Active" checkbox. +1. Insert the `token` field from the URL into the `Token` field on the Web page. +1. Insert the `room` field from the URL into the `Room` field on the Web page. +1. Save or optionally click "Test Settings". + +## Troubleshooting + +If you do not see notifications, make sure you are using a HipChat v2 API +token, not a v1 token. + +Note that the v2 token is tied to a specific room. If you want to be able to +specify arbitrary rooms, you can create an API token for a specific user in +HipChat under "Account settings" and "API access". Use the `XXX` value under +`auth_token=XXX`. diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 86eda341d6c..8510fcf0319 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -12,7 +12,7 @@ __Project integrations with external services for continuous integration and mor - Flowdock - Gemnasium - GitLab CI -- HipChat +- [HipChat](hipchat.md) An Atlassian product for private group chat and instant message. - [Irker](irker.md) An IRC gateway to receive messages on repository updates. - Pivotal Tracker - Pushover |