Github Issues Sample

This watsonwork-github-issues sample application showcases a variety of capabilities and easy-to-use features with Watson Work Services. In particular it shows authentication with Watson Work Services, posting a message to a Work Services space and integration with a third party service.

This app will listen to newly created or closed Github issues for a particular repository and post the status back to Watson Work Services.

Quickstart with IBM Bluemix

Let's get started! The steps below will outline the process from getting the app running within Bluemix to enabling the app to post within a space based on the status of a github issue, and everything in between.

Before jumping in, try accessing the links below to make sure you have access to Workspace, the developer experience for Watson Work Services, and Bluemix.

• Watson Workspace
• Watson Work Services
• Bluemix

Deploy to Bluemix

First, let's get this app up and running on Bluemix. This will provide us with a publicly accessible endpoint that we can register with Watson Work Services to get events pushed to. To deploy to Bluemix, you can simply click the button below. This will create your own Bluemix DevOps toolchain in addition to deploying the app. As part of the toolchain, Bluemix will create a git-based repository for source control and a pipeline for building, testing and deployment.

Once you've clicked the button, you'll get prompted with the following screens:

1. Define your App name, Region, Organization and Space.

Most of the time you can keep the default values, but if you have multiple accounts/organizations/spaces in Bluemix, please make note of the values here to make sure the app is deployed where you'd like it to be.

Click the Deploy button at the bottom of the screen to continue to the next step.

2. Once deployment and configuration has begun, you will be sent to the DevOps toolchain dashboard for your app:

This will show you each of the "tools" that are provided in the tool chain.

• The Issues block will take you to your own git-based repository for this app. It will bring you to the issues section of this repository.
• The Git block will also take you to the git repository. This repository can be used like any git repository, included with the ability to automatically run the pipeline for any git push.
• The Eclipse Orion Web IDE will take you to Eclipse's web-based editor, with the project connected to the git repository referenced above.
• The Delivery Pipeline block will bring you to Bluemix's pipeline dashboard, which outlines each stage configured for the pipeline.

3. Click on the Delivery Pipeline block to see the current status of the deployment.

   When the deployment is done, the deploy stage will appear as below, with a green Stage Passed confirmation box.

   

   Note: It may take a minute or two to deploy.

4. After the app is done deploying, click on the box under Last Execution Result to navigate to the deployed app.

5. The Last Execution Result block will take you to the App dashboard for the newly deployed app.

This dashboard shows the status of the app, the URL to access the app and provides the ability to interact with the app ( set environment variables, view logs, etc).

Take note of the app name at the top. The app name is used to contruct the URL for the running app: https://<appname>.mybluemix.net.

For example, in the screenshot above, the URL would be: https://watsonwork-github-issues-20170805194040469.mybluemix.net

Now let's register this app in Watson Work Services!

Register app with Watson Work Services

An app must be registered with Watson Work Services in order to interact with the platform. The registration process provides the app with an id, secret and enables the app to request certain capabilities, such as listening to events in the system.

To register an app, navigate to the Watson Work Services developer experience: https://developer.watsonwork.ibm.com.

1. Once logged in, select the Your Apps link at the top right.

2. From here, you should see a button to Create new app, as well as a list of apps if you have already created some.

3. Click on Create new app.

Provide any App name and Description that you'd like for your app and then click Create. This name will show up in Watson Work Services as the display name for your app.

4. Once registered, you will be presented with the id and secret for the app.

Copy both the id and secret for later use.

5. After copying the id and secret, you will be sent to the App Dashboard for the newly registered Watson Work Services app.

This dashboard contains all of the information for your app, as well configuration options for listening to events, enabling your app to run as a user, and much more!

Listen to events in Watson Work Services

Now that your app is registered with Watson Work Services, we can enable it with a variety of different capabilities.

For now we're going to focus on Listen to Events to set our app up to retrieve messages from Watson Work Services.

1. Click on the Listen to Events tab on the side menu in your Apps Dashboard.

2. Click on Add an outbound webhook.

• Provide any Webhook Name that you would like. This name won't be displayed anywhere.

• For the Webhook URL, provide the following URL, based on the app name that was copied above from Bluemix.

  • Webhook URL: <appname>.mybluemix.net/webhooks/.

    • Example: watsonwork-github-issues-20170805194040469.mybluemix.net/webhooks/.

    Note the / at the end is required for this particular sample app. Also, the form includes the https://, so no need to include that in the input box.

• For the Events section, check the message-created option.

3. Once you click Save, a confirmation dialog will appear with your Webhook Secret. Copy this secret. We will need it for configuring our Bluemix app.

Note: Even though we have saved the webhook, the webhook is not enabled until we update our app to use the webhook secret. We will come back to the Listen to Events panel to enable it after updating these values in Bluemix.

4. Navigate back to you Bluemix app dashboard to input the ids and secrets. In your Bluemix app dashboard, navigate to Runtime on the side menu, and then the Environment variables tab.

5. Add the following environment variables:

• Name: APP_ID, Value: Id copied from app registration success dialog
• Name: APP_SECRET, Value: Secret copied from app registration success dialog
• Name: WEBHOOK_SECRET, Value: Secret copied from webhook registration

Click Save and the app will automatically restart.

6. Once the app has restarted. Navigate back to the Listen to Events page for your app in the Watson Work Services developer experience. Select the Enable button on your webhook.

The button should then turn to Disable if enablement of the webhook was a success.

Now your app is connected to Watson Work Services, and can both post messages and listen to message-created events! Let's try it out.

Try out your app in Workspace

After the app is registered and configured to listen to events, we can try it out by adding it to a space in Workspace.

1. Open Watson Workspace in a new tab.

2. Create a new space to add the app to. You can click on the Create a Space button or the + icon next to the Spaces title.

3. Click on the space name at the top to go to the Space Settings panel. From here you can click on the Apps link on the left to view apps to add.

4. Click on the app to add it to the space.

5. Now we can try to interact with the app. First let's send a message to see if the app can echo it back. The app is configured to listen for @py-echo <message>.

   Attempt to send in @py-echo This is a test. The app should respond.

   

   The app is able to listen for a message containing @py-echo and post a message back into the space!

   Let's set this up with Github now! Make note of your spaceId, which you can find in the URL of the space: https://workspace.ibm.com/space/598639bfe4b07d4cbf448742, with the id being 598639bfe4b07d4cbf448742.

Setup Github Webhook

Our app is now registered in Watson Work Services and running in Bluemix. The next step is to set up our app with a Github repository so that we can see the actual app functionality in motion!

1. Navigate to any Github repository where you have access to configure webhooks.
2. In your Github repo, head to the Settings page

3. Select the Hooks & services from the side menu.

4. Select Add Webhook.

For the Payload URL, put in your Bluemix URL that we've used above (https://<appname>.mybluemix.net), with the context root of /github/{spaceId}.

For example: https://watsonwork-github-issues-20170805194040469.mybluemix.net/github/598639bfe4b07d4cbf448742

Select application/json for the Content-Type.

5. The app is only configured to listen to events related to issues, so we can select the Let me select individual events option, and pick issues.

6. Save the webhook and create a new issue to see the event posted back to your Workspace space!

And a post back in Workspace!

If you close the issue, that will be reflected as well.

Now we have an app that integrates with Github and posts useful updates to our spaces!