Integrate gitStream with Microsoft Teams

This page demonstrates uses cases for how to connect gitStream to Microsoft Teams to post messages via webhooks.

Prerequisite Configurations

To use gitStream with MS Teams, you first need to do two things:

1. Create an incoming webhook in Teams.
2. Provide your Teams webhook URL to gitStream as an organization environment variable.

Set Up Incoming Webhooks in Teams

Microsoft Teams can accept incoming webhooks to send fully-featured messages to channels and individuals. Here’s the complete tutorial from Microsoft.

Here is an overview of the process:

Step 1: Add the Incoming Webhook connector inside MS Teams.

Step 2: Give it a name and an image so your teammates can identify it easily and click create.

Once created, copy the webhook URL, you'll need this in the next step.

Configure gitStream Environment Variable

gitStream can access GitHub orgnization secrets as environment variables, and you'll need to do this to provide gitStream with access to your Slack webhook URL.

1. Create an organization secret in GitHub and ensure it isn't being overridden by a repo-level secret of the same name.
2. Pass the organization secret to gitStream as an environment variable in your gitstream.yml workflow file. We recommend using an easy to understand term like MS_TEAMS_WEBHOOK_CHANNEL_NAME.

How to Send Microsoft Teams Messages From gitStream

automations:
send_teams_message:
    if:
    - true
    run:
    - action: send-http-request@v1
        args:
        method: "POST"
                    headers: '{"Content-type": "application/json"}'
        url: "{{ env.MS_TEAMS_WEBHOOK }}"
                    body: '{"text": "Hello, world!"}'

Auto-Recognition For Meeting Team Goals

A good choice to reward developers for submitting great PRs would be to automate an MS Teams message that gives the developer recognition among their colleagues. To do this, you’ll need to create a MS Teams webhook that sends to a channel full of reviewers, managers, and anybody else who should see the recognition.

# -*- mode: yaml -*-

manifest:
  version: 1.0

automations:
  teams_auto_recognition:
    if:
      - {{ files | match(regex=r/(test|spec)/) | some }} # this pr has at least 1 test
      - {{ files | length <= 5 }} # this pr has 5 or less files
      - {{ branch.name | includes(regex=r/[A-Z]{2,}-\d+.*/) }} # this branch has the Jira ticket prefix
      - {{ branch.diff.size <= 150 }} # this branch has 150 lines of code or less changed
    run:
      - action: send-http-request@v1
        args:
          method: "POST"
          headers: '{"Content-type": "application/json"}'
          url: "{{ env.MS_TEAMS_WEBHOOK }}"
          body: '{"text": "Congrats to {{ pr.author }} for the amazing new PR, {{ pr.title }}! Check it out at https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"}'

Message Specific Teams Based on PR content

You can also use the Slack integration to automatically keep in touch with code owners and others who should be connected to the PR. You could check for certain conditions that require a more personal review from an experienced maintainer, like:

• Will the PR take too long to review?
• Did SonarCloud find vulnerabilities?
• Is this the author’s first commit or are they new to the codebase?
• Is this an automated PR that for some reason didn’t pass the automatic approval tests?

On the other hand, some PRs might not have anything wrong, but still need to be assigned to a certain team based on expertise. In that case, you could set up several Teams automation actions at once, all with different webhooks and conditions. In an organization with different secrets for Teams webhooks to the #security-team channel, the #qa-team channel, and the #docs-team channel.

# -*- mode: yaml -*-

manifest:
  version: 1.0

automations:
  send_teams_security:
    if:
      # use your custom logic here to determine whether this needs a security review
      - true
    run:
      - action: send-http-request@v1
        args:
          method: "POST"
          headers: '{"Content-type": "application/json"}'
          url: "{{ env.MS_TEAMS_WEBHOOK_SECURITY }}"
          body: '{"text": "A PR requires a security review. See https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"}'
  send_teams_qa:
    if:
      # use your custom logic here to determine whether this needs a qa review
      - {{ not (files | match(regex=r/(test|spec)/) | some) }}
    run:
      - action: send-http-request@v1
        args:
          method: "POST"
          headers: '{"Content-type": "application/json"}'
          url: "{{ env.MS_TEAMS_WEBHOOK_QA }}"
          body: '{"text": "A PR was submitted without tests. See https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"}'
  send_teams_docs:
    if:
      # use your custom logic here to determine whether this needs a docs review
      - {{ files | match(regex=r/(docs)/) | some }}
    run:
      - action: send-http-request@v1
        args:
          method: "POST"
          headers: '{"Content-type": "application/json"}'
          url: "{{ env.MS_TEAMS_WEBHOOK_DOCS }}"
          body: '{"text": "A PR has modified the docs. See https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"}'

Using this template and custom logic specific to your company, you can build a complete repo management system that gets the right people actively involved by pinging them where they are in Teams.

Additional Resources

gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.

Learn More about how gitStream Works.

More Automations can be found on the Automation Library and Integrations pages.