GitHub

Integrate GitHub activity to your Harmony projects

It is very easy to integrate GitHub activity to your Harmony instance. The integration is done through GitHub webhooks requests which send a POST request with all the required information to the GitHubController controller existing in the Harmony.Integrations.SourceControl application.

Integrating GitHub with your instance will allow you to see GIT activity such as branches, commits or pull requests, directly to your work items.

Integration Configuration

There are two steps required to configure the GitHub integration. The first one is to configure the Harmony.Integrations.SourceControl application & the next one is to setup the webhook URL on your GitHub account.

Harmony.Integrations.SourceControl

This application is responsible to accept webhook requests coming from GitHub. It also exposes HTTP endpoints to the client via the gateway. Open its appsettings.json file and configure all the required connection strings for MongoDB, RabbitMQ & optionally ElasticSearch. For local development and assuming you have installed MonboDB & RabbitMQ as explained in the Installations page, the configuration should look like the following, unless you used different options during installation:

  "MongoDB": {
    "ConnectionURI": "mongodb://localhost:27017"
  },
  "BrokerConfiguration": {
    "Host": "localhost",
    "Port": 5672,
    "Username": "",
    "Password": "",
    "VirtualHost": ""
  },
  "ElasticConfiguration": {
    "Uri": "http://localhost:9200"
  }

By default, Harmony.Integrations.SourceControl application runs on port 7113 as you can find in the Properties/launchSettings.json file. When running locally, you need to create a public URL that forwards the GitHub requests to your local instance and for this you can use ngrok. It can generate a publicly accessible URL that forwards the requests to your local source control application.

  1. Create a free account & download the ngrok agent from here.

  2. Extract the agent in a folder of your preference, e.g. C:/tools/ngrok

  3. As soon as you create an account, ngrok creates an authtoken for you which you can find in the your-authtoken page.

  4. Open a terminal and navigate to the folder where you extracted ngrok agent and run the following command to configure ngrok auth-token:

.\ngrok.exe config add-authtoken <your-auth-token-here>

  1. The last step is to create the tunnel to your application running at port 7113. Run the following command:

.\ngrok.exe http https://localhost:7113

This will create a public URL that you are going to use it as a webhook to GitHub!

Add the Harmony.Integrations.SourceControl application to your startup projects in case you run Harmony using Visual Studio.

The application should be up and running when GitHub sends Webhook requests or client asks for a card's Git activity.

GitHub WebHooks

Sign in to your GitHub account and configure the Settings/Webhooks either on a repository level or on an organization level.

If you have an organization with many repositories then it's more convenient to configure the webhooks on organization level because you only required to do it in one place. Otherwise you need to configure the webhooks in all of your repositories that are related to your harmony instance.

Organizations are free to create by the way but aren't required to configure the integration with harmony

  1. In the webhooks page of either your organization or in one of your repositories, fill the Payload URL with the ngrok URL generated in the previous step and set the Content type to application/json. Notice the you have to add an extra /github at the end of the URL in order to send the requests to the correct GitHub controller existing in the app.

  1. Which events would you like to trigger this webhook? Select the Let me select individual events option and check the following events:

  • Branch or tag creation

  • Branch or tag deletion

  • Pull requests

  • Pushes

  1. Activate the Webhook and save it.

Card Git Activity

When you open a board's card, you will find git activity information on the right sidebar. If there isn't any branch created for this item, then a suggested git command will help you to create one.

Branch names should contain the serial key of each item so that harmony can match all the git activity. The serial key consists of the board's KEY configured when you created and the item's number. You can find this information either directly from the board or by opening any card. Valid branch names examples: Assuming you have a card item with serial key equal to HARM-10 and title Support GitHub integration, here are a few suggested branch names that will work as expected.

You don't have to use the card's title in your branch's name, the critical part that creates the bonding is the serial key, which in the previous case is the harm-10.

  • Harmony controller will try to figure out the serial key by running the ([a-zA-Z]{3,5})-(\d+) regex on your branch name.

  • Avoid adding other numbers in your branch name

After creating a branch and as soon as it's being pushed to GitHub, the activity will be saved and displayed on the card's page. New commits or pull requests related to that branch will also get synced upon Webhook request.

Clicking the VIEW DETAILS button will show you even more detailed information for the git activity related to this issue.

Notes

Harmony.Integrations.SourceControl is exposed to the client via the Gateway. In a local dockerized environment you should run ngrok to expose the gateway's endpoint rather than the actual Harmony.Integrations.SourceControl. Assuming the gateway runs on port 7108, then the ngrok command should change to:

.\ngrok.exe http https://localhost:7108

Next the Webhook URL on GitHub will have the generated ngrok URL plus the /sourcecontrol/github segment. Notice the extra /sourcecontrol part added here. This is required because now the application is exposed through the Gateway app.

Pending a YouTube video tutorial to show all these in action...

Last updated