GitHub
Integrate GitHub activity to your Harmony projects
Last updated
Integrate GitHub activity to your Harmony projects
Last updated
It is very easy to integrate GitHub activity to your Harmony instance. The integration is done through GitHub 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.
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.
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:
Extract the agent in a folder of your preference, e.g. C:/tools/ngrok
Open a terminal and navigate to the folder where you extracted ngrok agent and run the following command to configure ngrok auth-token:
The last step is to create the tunnel to your application running at port 7113. Run the following command:
This will create a public URL that you are going to use it as a webhook to GitHub!
Sign in to your GitHub account and configure the Settings/Webhooks either on a repository level or on an organization level.
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.
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
Activate the Webhook and save it.
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.
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:
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...
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 . It can generate a publicly accessible URL that forwards the requests to your local source control application.
Create a free account & download the ngrok agent from .
As soon as you create an account, ngrok creates an authtoken for you which you can find in the page.
