# GitHub It is very easy to integrate **GitHub** activity to your Harmony instance. The integration is done through GitHub [webhooks](https://docs.github.com/en/webhooks/about-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](/harmony/configuration/dependencies/installations.md) page, the configuration should look like the following, unless you used different options during installation: ```json "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](https://ngrok.com/). 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](https://ngrok.com/download). 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](https://dashboard.ngrok.com/get-started/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 ``` 5. 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! {% hint style="info" %} 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. {% endhint %}

ngrok public URL

#### GitHub WebHooks Sign in to your GitHub account and configure the **Settings/Webhooks** either on a repository level or on an organization level. {% hint style="info" %} 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 {% endhint %} 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.

GitHub webhook

2. **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 3. 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. {% hint style="warning" %} 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. * [x] harm-10-support-github-integration * [x] feature/harm-10-support-github-integration * [x] support-github-integration-harm-10 * [x] harm-10 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 {% endhint %}

Suggested git command to create a branch

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.

Git summary details on card's view

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

Git activity

### 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... --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://chsakell.gitbook.io/harmony/integrations/github.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.