How does it work

Buildwatch uses Google Cloud Messaging (GCM) to notify the Phones about updates.

Google Cloud Messaging Basics

Cloud messaging is basically a free store & forward server in the internet for small messages. Android devices keep a longlived HTTPS connection to this service and can hence receive 'push' updates from GCM. Applications that want to use this service need an API token on the message - sending components and a service correlation id ('RegId'). Applications on Phones that want to receive messages need to register with their Google account and the RegId at the GCM Servers and receive a GCM Token. The phone registers this token at the message sender. The message sender uses the GCM token from the Phone, the API token and the RegId to address messages to the phones.


As you can see the setup process is quite tedious. We implemented BuildWatch in a way where each admin creates their own Google GCM account. Like this the (potentially) secret information about your builds is never shared with us but only with Google. We tried to make the device registration process as simple as possible by making your jenkins page show a QR code that you can scan with your phone that contains all configuration data. Upon getting a new GCM token, the device tries to contact your jenkins server to register the token there. Note that you need to be able to reach jenkins from your phone for that. That means either your build server is on the public internet, or you have to join you WIFI at work to use automatic setup. Of course you can always put it in manually as well.

Sending a message
Overview: Setup Jenkins

Setup your Jenkins Server

It is not actually hard to setup the whole thing. But there is a lot of different things you have to do. It is probably easiest, if you check the video where we show how to set it up below. For those of you who prefer text, please scroll down.

Create a GCM account

  1. Head over to the Google API console and select "Create new Project".
  2. Choose any name
  3. Configure the "Google Cloud Messaging for Android" Service for your new project and slide the Status Control to "On".
  4. On the left side click on API Access and create a new server key (don't bother with the Browser key that is pre generated, you need a different one).
  5. You don't have to whitelist any IP addresses, just press "Create"
  6. Note down the API key String that was just created (Make sure that you take the one that says 'Key for Server Apps')
  7. Click on "Overview" and note down the Project Number that you see on your Dashboard.
Now you have all the relevant information for the GCM setup. To make this easier for you, we have created a video where we show what to do.

Configure Jenkins

To use BuildWatch some jenkins configuration is necessary. You need to get the Google Cloud Messaging plugin and tell it your credentials for the GCM account. This is what you have to do:

  1. Install the GCM Notification Plugin via the Update Center.
  2. Click on Configure System and find the entries of the GCM plugin ("Google Cloud Messaging Notifications")
  3. In the Project Number field, input the project number you have just obtained from the Google API Console.
  4. In the Simple API access key field, input the simple api access token you just obtained from the Google API Console.
  5. Press 'save' and you are done.

Setup your Phone

Your device needs a GCM token from the Google Servers and connect it to your jenkins user. This is very easy:

  1. Go to your account page (click on your username and then find 'Configure').
  2. Find the GCM Token field and click on the 'Show QR Code' link.
  3. Open BuildWatch on your phone, select "Auto Setup".
  4. Scan the QR code with your phone and wait for the 'Successfully registered with jenkins' Toast.
And then your are done. Note: This only works if the phone and jenkins are in the same network (Internet or local wifi). If you need some tries there is a retry button in the BuildWatch options menu. If you can not be in the same network you can configure the phone manually in the "Server Settings" tab. Note that you will have to manually copy the GCM token from the device to jenkins.

Configure the Job

Not all build events are sent to Google Cloud Messaging. You have to explicitly enable users that should receive messages per job. This is what you do:

  1. Select the job from the main page and click the "Configure" link.
  2. Find the Post-Build Actions and select "Add post-build action".
  3. Choose "Notify Android Devices".
  4. Put all Users that you want to have notified via GCM to the list of users. Note that they will still need to have registered a valid GCM token to receive a message (check in the Users Config page, it should be printed there if the auto setup process above worked.)

After all this has happened you are done. Try to run a build and see if you get a message on your SmartWatch. If something doesn't work, double check if the token in jenkins matches the token shown on your device. If you don't see a token, make sure the BuildWatch can establish a TCP/IP connection to the host specified in the Jenkins URL configuration parameter on the main jenkins configuration page. Also make sure that your build server can connect to the GCM servers (android.googleapis.com) on port 443 (https). If nothing helps, look into the jenkins logfile.

FAQ and Hints

The 'show QR code' button is not on my jenkins configuration page. I only have the possibility to configure the token manually.

The button is only shown for logged in users on their own configuration page. Double check that you are logged in in Jenkins and that you are visiting your own configuration page. (Thanks Steve!)

The GCM setup somehow failed (Device has no Google Account configured, GCM Setup on Jenkins is wrong, Forgot to turn on wifi when buildserver is only accessible from the local network, ...). It is annoying to retry by QR code scanning

There is the possibility of retrying from the app, it is a little bit hidden as a 'Menu' item on the Configuration Page.