Post GitHub Events To A Microsoft Teams Channel Using C#.NET

Webhooks allow you to build or set up integrations that subscribe you to events on GitHub.com. We will use the webhook to get notified of events on our custom web API endpoint and will use the attributes from the payload received to POST to a team's channel using Microsoft Teams incoming webhook. Developers can proactively get notified on a team's channel they are collaborating on. For the purpose of this article, we will just focus on push events for a particular repository. You can extend it to events outside of a repository as well.

 

Let us get started!

 

Here are our main steps,

• Configure Microsoft Teams incoming webhook.
• Develop Web API endpoint for receiving events from GitHub.
• Configure GitHub repository webhook.

Configure Microsoft Teams incoming webhook

 

If you have not configured an incoming webhook for a Microsoft Teams Channel, please follow the instructions below. If you have an incoming webhook configured already, please have the URL to the webhook handy. This will be needed for our next step.

 

Right-click the channel of interest in Microsoft Teams and choose Connectors,

 

 

Select Configure option for Incoming Webhook,

 

 

Name your incoming webhook and upload an image of your choice. This image will be displayed as part of your webhook messaging. Choosing a GitHub image will be ideal.

 

That way developers can easily see the source of the notification as GitHub. This will also be very helpful if you have other webhooks in the channel for other notifications and if you want to differentiate GitHub from others just at a quick glance. 

 

 

After you gave it a good name and optionally uploaded an image of choice, click on Create.

 

Copy the URL for the incoming webhook and keep it handy. You will need this for our next step.

 

 

Develop Web API endpoint for receiving events from GitHub 

 

We will create a REST endpoint in C# to receive the push event from GitHub. After we create the API we will configure it in GitHub so that we receive the payload from GitHub for the push event. When GitHub notifies you, the payload in JSON string format has a lot of attributes as shown in the image below,

 

 

For the purpose of this article, we will only use a few objects and attributes in the JSON structure. We will use the following attributes,

• ref (root object)
• name (repository object)
• the message, timestamp, URL, committer (commits object)
• name, email, username (commits==>committer object)

These attributes are a good start and help developers get a basic view into the push event all without leaving the MS Teams channel. For this example, we will also deep-link to the commit using the URL attribute of the commits object, in case we need to find details. We will deserialize the payload to the basic attributes that are needed and then POST it to MS Teams channel as an adaptive card. Adaptive Cards are platform-agnostic snippets of UI, authored in JSON, that apps and services can openly exchange.

 

Please refer to Adaptive Cards if you are interested to learn more about it.

 

Let us get going with our WebAPI project. We will use Visual Studio and create an ASP.NET Core Web API project.

• Open Visual Studio and create an ASP.NET Core Web API project using C#,

 

Configure your new project.

 

Give it a good name and click Next.

 

 

We will pick .NET 5.0 for the Target Framework in the Additional information form. You can pick a framework of your choice. .NET 5.0 has some great features out of the box including Swagger support. Click Create after you made your selection,

 

 

After the solution gets loaded, let us create the necessary classes for our WebAPI. Let us create our controller class first. Right-click the Controllers folder and add a new controller,

 

 

Give it a good name and click Add,

 

 

Let us create the necessary classes for our GitHub and Teams objects. We will put both of them under the Models folder. Right-click the project and create a new folder Models,

 

 

Now right-click the Models folder and create a class for our GitHub which we will call GithubCommit,

 

 

Let us also create a new class for our Teams which we will call TeamsMessage,

 

 

With all the class files in place, let us get to some coding.

 

First, we will create the necessary attributes for our GitHub payload that we can deserialize. We are only interested in a subset of attributes coming in from the payload.

 

GithubCommit.cs

public class GithubCommit {
    [JsonProperty(PropertyName = "ref")]
    public string BranchReference {
        get;
        set;
    }
    public Repository Repository {
        get;
        set;
    }
    public Commits[] Commits {
        get;
        set;
    }
}
public class Commits {
    [JsonProperty(PropertyName = "message")]
    public string Message {
        get;
        set;
    }
    [JsonProperty(PropertyName = "timestamp")]
    public DateTime TimeStamp {
        get;
        set;
    }
    [JsonProperty(PropertyName = "url")]
    public string URL {
        get;
        set;
    }
    [JsonProperty(PropertyName = "committer")]
    public Committer Committer {
        get;
        set;
    }
}
public class Committer {
    [JsonProperty(PropertyName = "name")]
    public string Name {
        get;
        set;
    }
    [JsonProperty(PropertyName = "email")]
    public string Email {
        get;
        set;
    }
    [JsonProperty(PropertyName = "username")]
    public string Username {
        get;
        set;
    }
}
public class Repository {
    [JsonProperty(PropertyName = "name")]
    public string RepoName {
        get;
        set;
    }
}

Next, we will create the necessary class for our teams message. Please note that Teams support adaptive cards and some of the properties are centric around the branding of the card.

 

TeamsMessage.cs

public class TeamsMessage {
    [JsonProperty(PropertyName = "type")]
    public string Type {
        get;
        set;
    }
    [JsonProperty(PropertyName = "themeColor")]
    public string ThemeColor {
        get;
        set;
    }
    [JsonProperty(PropertyName = "summary")]
    public string Summary {
        get;
        set;
    }
    [JsonProperty(PropertyName = "sections")]
    public Sections[] Sections {
        get;
        set;
    }
}
public class Sections {
    [JsonProperty(PropertyName = "activityTitle")]
    public string ActivityTitle {
        get;
        set;
    }
    [JsonProperty(PropertyName = "activitySubtitle")]
    public string ActivitySubtitle {
        get;
        set;
    }
    [JsonProperty(PropertyName = "activityImage")]
    public string ActivityImage {
        get;
        set;
    }
    [JsonProperty(PropertyName = "markdown")]
    public bool Markdown {
        get;
        set;
    }
}

Let us make sure that our Teams webhook is a configurable entry in our configuration file (appsettings.json). Please replace the Repository key value with the name of the GitHub repository, TeamsURL with the URL of the webhook that you configured in the first step.

 

You can also put a pretty picture that goes along with the card for our team's message. Please replace the GithubImage value with a URL to a nice image that will be displayed in our team's message card.

 

Here is a quick snapshot of our appsettings.json file. 

 

appsettings.json

 

 

Now with both of our classes required for deserializing the payload coming from GitHub and serializing the object for our team's card message, let us move onto our API endpoint logic. Let us take advantage of dependency injection and inject the configuration object into the constructor so that we can call our configurable entries in appsettings.json,

 

NotifyController.cs

public class NotifyController: ControllerBase {
        private readonly IConfiguration _config;
        public NotifyController(IConfiguration config) {
            _config = config;
        }

Now for our main POST endpoint.

 

NotifyController.cs

// POST api/<NotifyController>
[HttpPost]
public async Task < IActionResult > Post() {
    using(StreamReader reader = new(Request.Body, Encoding.UTF8)) {
        var resultsData = await reader.ReadToEndAsync();
        GithubCommit githubCommitObject = null;
        try {
            githubCommitObject = JsonConvert.DeserializeObject < GithubCommit > (resultsData);
            var gitRepoName = githubCommitObject.Repository.RepoName;
            var repoName = _config["GithubEvents:Repository"].ToString().Trim().ToLower();
            if (repoName.ToLower() == repoName.ToLower()) {
                await PostToTeamsChannel(_config["GithubEvents:TeamsURL"].ToString().Trim(), repoName, githubCommitObject.BranchReference, githubCommitObject.Commits[0].Committer.Name, githubCommitObject.Commits[0].Message, githubCommitObject.Commits[0].URL, _config["GithubEvents:GithubImage"].ToString().Trim());
            }
        } catch (Exception ex) {
            //Eating the exception. Instead notify/log.
            string exception = ex.Message;
        }
    }
    return Ok();
}

The logic is simple enough. We read the payload from the body received from the GitHub event, deserialize it as a GithubCommit object and check if the repository name matches the repository that is of interest and if it matches, post it to our team's channel.

 

Let us explore PostToTeamsChannel method next.

 

NotifyController.cs

private static async Task < String > PostToTeamsChannel(string teamsURL, string repoName, string branchReference, string author, string commitMessage, string commitURL, string teamsPostImage) {
    string success = "false";
    if (teamsURL.Trim().Length > 0) {
        using
        var client = new HttpClient();
        TeamsMessage teamsMessage = new() {
            Type = "MessageCard",
                ThemeColor = "0076D7",
                Summary = commitMessage
        };
        Sections sections = new() {
            ActivityTitle = commitMessage,
                ActivitySubtitle = string.Format("Author: {1}, On {3} branch: {2} [Commit]({0}) ", commitURL, author, branchReference, repoName),
                ActivityImage = teamsPostImage,
                Markdown = true
        };
        teamsMessage.Sections = new Sections[] {
            sections
        };
        var teamsPayload = JsonConvert.SerializeObject(teamsMessage);
        var response = await client.PostAsync(teamsURL, new StringContent(teamsPayload, Encoding.UTF8, "application/json"));
        var contents = await response.Content.ReadAsStringAsync();
        if (response.IsSuccessStatusCode) {
            success = "true";
        }
    }
    return success;
   }
}

The method is also simple enough. It formats the attributes necessary for our card in a JSON adaptive card format. If necessary, you can template these cards to make them more generic. But for the purpose of this article, we will keep it simple. Please note, one of the attributes in the card is a deep link into GitHub commit URL.

 

Now we will have to host our POST endpoint in a publicly accessible way so that GitHub can send events to our endpoint. Please proceed with hosting the WebAPI endpoint. Hosting a web app is outside the scope of this article. Please have the endpoint URL handy which we will need to configure in GitHub repository settings. 

 

Not let us proceed with our final step of configuring the webhook in GitHub. 

 

Configure GitHub repository webhook

 

Log in to your GitHub account and select the repository that you are interested in getting notified on and then click on Settings,

 

 

Click Webhooks in the left navigation pane.

 

 

Specify our API endpoint URL for Payload URL, change the Content-type to application/JSON and click Add webhook. You can leave the rest of the fields with default settings.

 

Note

You can set a secret code if you prefer, this will make sure that you have the security in place to validate that the event is coming from GitHub. You need to have the logic to read the additional security attributes inside our POST call if you need to make it more secure. For this example, we will keep this simple and will leave the Secret field empty.

 

 

That is it! The next time you complete a push to the repository, GitHub will notify us on our POST endpoint with a payload and our logic will in turn process the payload and post some of the attributes from the payload as an adaptive card to the team's channel.

 

We have completed the basic necessary steps and coding for pro-actively notifying a GitHub event in a Microsoft Teams channel using C#.

 

Here is a sample message card that got posted to one of my Microsoft Teams Channel.

 

Happy coding and happy collaborating!!!