bitrise-io/bitrise-webhooks

Name: bitrise-webhooks

Owner: Bitrise

Description: Bitrise Webhooks processor

Created: 2016-02-03 15:24:26.0

Updated: 2018-03-16 11:52:58.0

Pushed: 2018-01-17 09:39:50.0

Homepage: null

Size: 611

Language: Go

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

bitrise-webhooks

Bitrise Webhooks processor.

Transforms various webhooks (GitHub, Bitbucket, Slack, …) to bitrise.io's Build Trigger API format, and calls it to start a build.

Feel free to add your own webhook transform provider to this project! For more information check the How to add support for a new Provider section.

Build Status

CI Skip

If the (commit) message includes [skip ci] or [ci skip] no build will be triggered.

Supported webhooks / providers

Service independent:

GitHub - setup & usage:

All you have to do is register your bitrise-webhooks URL for a GitHub repository.

  1. Open your repository on GitHub.com
  2. Go to Settings of the repository
  3. Select Webhooks
  4. Click on Add webhook
  5. Specify the bitrise-webhooks URL (.../h/github/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the Payload URL field
  6. Select the events you want to trigger a webhook for
  7. Right now bitrise-webhooks supports the Push and Pull Request events, every other webhook (triggered by another event) will be ignored.
  8. Click Add webhook

That's all! The next time you push code, push a new tag or create/update a pull request a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Bitbucket (V2) Webhooks - setup & usage:

All you have to do is register your bitrise-webhooks URL for a Bitbucket repository.

  1. Open your repository on Bitbucket.org
  2. Go to Settings of the repository
  3. Select Webhooks
  4. Click on Add webhook
  5. Specify the bitrise-webhooks URL (.../h/bitbucket-v2/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the URL field
  6. In the Triggers section select Choose from a full list of triggers and the following properties:
  7. Repository > Push
  8. Pull Request > Created
  9. Pull Request > Updated
  10. Click Save

That's all! The next time you push code, push a new tag or create/update a pull request a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Bitbucket Server Webhooks - setup & usage:

All you have to do is register your bitrise-webhooks URL for a Bitbucket Server repository.

  1. Open your repository on your self hosted Bitbucket Server instance
  2. Go to Settings of the repository
  3. Select Webhooks
  4. Click on Create webhook
  5. Specify the bitrise-webhooks URL (.../h/bitbucket-server/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the URL field
  6. In the Events section select the following properties:
  7. Repository > Push
  8. Pull Request > Opened
  9. Click Save

That's all! The next time you push code, push a new tag or create a pull request a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise). Please note that Bitbucket Server doesn't send any notifications when new commits are pushed to an existing PR, so no builds will be triggered by these events.

GitLab - setup & usage:

All you have to do is register your bitrise-webhooks URL for a GitLab project.

  1. Open your project on GitLab.com
  2. Go to Settings of the project
  3. Select Web Hooks
  4. Specify the bitrise-webhooks URL (.../h/gitlab/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the URL field
  5. In the Trigger section select:
  6. Push events
  7. Tag push events
  8. Merge Request events
  9. Click Add Web Hook

That's all! The next time you push code, push a new tag or create/update a merge request a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Gogs - setup & usage:

All you have to do is register your bitrise-webhooks URL as a Webhook in your Gogs repository.

  1. Open your project on your repository's hosting URL.
  2. Go to Settings of the project
  3. Select Webhooks, Add Webhook, then Gogs.
  4. Specify the bitrise-webhooks URL (.../h/gogs/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the Payload URL field.
  5. Set the Content Type to application/json.
  6. A Secret is not required at this time.
  7. Set the trigger to be fired on Just the push event
  8. Save the Webhook.

That's all! The next time you push code a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Visual Studio Online / Visual Studio Team Services - setup & usage:

All you have to do is register your bitrise-webhooks URL for a visualstudio.com project as a Service Hooks integration.

You can find an official guide on visualstudio.com 's documentations site.

A short step-by-step guide:

  1. Open your project on visualstudio.com
  2. Go to the Admin/Control panel of the project
  3. Select Service Hooks
  4. Create a service integration
  5. In the Service list select the Web Hooks option
  6. Select the Code pushed event as the Trigger
  7. In the Filters section select the Repository you want to integrate
  8. You can leave the other filters on default
  9. Click Next
  10. On the Action setup form specify the bitrise-webhooks URL (.../h/visualstudio/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the URL field
  11. You can leave every other option on default
  12. Click Finish

That's all! The next time you push code or push a new tag a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Deveo - setup & usage:

All you have to do is register your bitrise-webhooks URL for a Deveo repository.

  1. Open your repository on app.deveo.com
  2. Go to Hooks of the project
  3. Add new hook to the repository
  4. Select the hook type as webhook
  5. Specify the bitrise-webhooks URL (.../h/deveo/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the Url field
  6. Type json in the Content type field
  7. Click Save hook

That's all! The next time you push code or push a new tag a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Assembla - setup & usage:

Follow these steps to add your bitrise-webhooks URL to your Assembla space.

  1. Open your space on assembla.com or your organisation's assembla domain
  2. Go to the Webhooks section of the space
  3. Select Create New Webhook
  4. Set Title to BitRise Webhook
  5. Specify the bitrise-webhooks URL (.../h/assembla/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) in the External url field
  6. Select application/json in the Content type field
  7. Paste the following code to Content:
    sembla": {"space": "%{space}", "action": "%{action}", "object": "%{object}"}, "message": {"title": "%{title}", "body": "%{body}", "author": "%{author}"}, "git": {"repository_suffix": "%{repository_suffix}", "repository_url": "%{repository_url}", "branch": "%{branch}", "commit_id": "%{commit_id}"}}
  8. Select Code commits and/or Git Push in the Post updates about: section
  9. Click Add

That's all! The next time you push code a build will be triggered (if you have Trigger mapping defined for the event(s) on Bitrise).

Slack - setup & usage:

You can register the bitrise-webhooks URL (.../h/slack/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN) as either an Outgoing Webhook or as a slash command for your Slack team.

Once the URL is registered check the usage section below for all the accepted and required parameters you can define in the message, and for a couple of examples.

Usage - the message format

Your message have to be in the format: key:value|key:value|..., where the supported keys are:

At least one of these two parameters are required:

Other, optional parameters:

NOTE: at least either branch or workflow have to be specified, and of course you can specify both if you want to. You're free to specify any number of optional parameters.

You can also send environment variables that will be available in your workflow with the format: env[KEY1]:value1|ENV[KEY2]:value2

An example with all parameters included: workflow: primary|b: master|tag: v1.0|commit:eee55509f16e7715bdb43308bb55e8736da4e21e|m: start my build!|ENV[DEVICE_NAME]:iPhone 6S|ENV[DEVICE_UDID]:82667b4079914d4aabed9c216620da5dedab630a

Passthrough - setup & usage:

Simply register or use the .../h/passthrough/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN url. Every request received on the passthrough endpoint will trigger a build, no filtering is done or supported!.

The only limit is that neither the Headers nor the Body can be larger than 10kb.

The headers will be passed to the build in JSON serialized form, as the value of BITRISE_WEBHOOK_PASSTHROUGH_HEADERS. Note: headers are key value maps where the value is an array or strings, not just a single string value! Example:


"Content-Type": [
    "application/json"
],
"Some-Custom-Header-List": [
    "first-value",
    "second-value"
]

The body will be passed to the build as-it-is (in string/text form), as the value of BITRISE_WEBHOOK_PASSTHROUGH_BODY.

Demo: run the server locally (e.g. with bitrise run start) and call the .../h/passthrough/... endpoint with curl:

 -X POST --data 'just a text body' -H 'Example-Header: example header value' 'http://localhost:4000/h/passthrough/BITRISE-APP-SLUG/BITRISE-APP-API-TOKEN'

by default the server will print what and where it would send (debug mode), so you should see this in the server's log:

/09/10 16:30:18 ===> Triggering Build: (url:https://app.bitrise.io/app/BITRISE-APP-SLUG/build/start.json)
/09/10 16:30:18 ====> JSON body: {"build_params":{"branch":"master","environments":[{"mapped_to":"BITRISE_WEBHOOK_PASSTHROUGH_HEADERS","value":"{\"Accept\":[\"*/*\"],\"Accept-Encoding\":[\"gzip\"],\"Content-Length\":[\"16\"],\"Content-Type\":[\"application/x-www-form-urlencoded\"],\"Example-Header\":[\"example header value\"],\"User-Agent\":[\"curl/7.54.0\"],\"X-Forwarded-For\":[\"::1\"]}","is_expand":false},{"mapped_to":"BITRISE_WEBHOOK_PASSTHROUGH_BODY","value":"just a text body","is_expand":false}]},"triggered_by":"webhook"}
How to compile & run the server

Start the server:

Alternatively, with bitrise CLI:

Development mode:

By default the server will be started in Development Mode. This means that it won't send requests, it'll only print the request in the logs.

You can pass the -send-request-to flag, or set the SEND_REQUEST_TO environment variable to enable sending the requests to the specified URL (every request will be posted to the exact URL you specify).

You can switch the server into Production mode by defining the environment variable: RACK_ENV=production. In production mode the server will send requests to bitrise.io, unless you specify a send-request-to parameter.

How to use it / test it
Development
Testing a (new) webhook format

You can use http://requestb.in to debug/check a service's webhook format.

If you have a Heroku account you can quickly create & start your own RequestBin server for free, just follow the guide on RequestBin's GitHub page.

Create a RequestBin, and register the provided URL as the Webhook URL on the service you want to test. Once the service triggers a webhook you'll see the webhook data on RequestBin.

You can pass the -send-request-to option (or SEND_REQUEST_TO env var) to this server to send all the request to the specified URL (e.g. to RequestBin), instead of sending it to bitrise.io.

Deploy to Heroku

Alternatively you can use this Heroku deploy button, if you prefer the web UI over the heroku CLI: Deploy

Done. Your Bitrise Webhooks server is now running on Heroku.

You can open it with heroku open - opening the root URL of the server should present a JSON data, including the server's version, the current time, the server's environment_mode and a welcome message.

How to add support for a new Provider

Implement your webhook provider support code into ./service/hook/theprovider. Unit tests are required if you want your code to be merged into the main bitrise-wekhooks repository!

Once the implementation is ready add it to the selectProvider function, to the supportedProviders list, in the service/hook/endpoint.go file.

For an example you should check the service/hook/github (single webhook triggers only one build) or the service/hook/bitbucketv2 (a single webhook might trigger multiple builds) provider implementation.

Guide

Done! You can now test your provider on a server (check the Deployment section), and you can create a Pull Request, to have it merged with the official bitrise.io webhook processor.

Optional: define response Transform functions

Once you have a working Provider you can optionally define response transformers too. With this you can define the exact response JSON data, and the HTTP status code, both for success and for error responses.

If you don't define a response Transformer the default response provider will be used (service/hook/default_reponse_provider.go).

To define your own Response Provider/Transform functions you just have to implement the functions of ResponseTransformer (service/hook/common/common.go).

If your Provider implements these functions it'll be used for generating the response. You have to implement every function defined in the interface, or your Provider won't be considered as an implementation of the interface and the default response provider will be used instead.

Response

Response is always in JSON format.

If provider declares the response transformers it'll be used, and the provider is responsible for generating the response JSON.

If it doesn't provide the response transformer functions then the default response provider will be used.

The default response provider generates the following responses:

TODO
Contributors
This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.