Integrate gitStream with Slack

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

Prerequisite Configurations

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

1. Create a Slack app with incoming webhooks enabled.
2. Provide your Slack webhook URL to gitStream as an organization environment variable.

Setup Incoming Webhooks in Slack

Follow this tutorial to configure your Slack instance to receive webhooks from gitStream.You’ll end up with a webhook URL like this:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Configure 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 SLACK_WEBHOOK_CHANNEL_NAME.

How to Send Slack Messages From gitStream

automations:
send_slack:
    if:
    - true
    run:
    - action: send-slack-message@v1
        args:
        message: "A message sent from GitStream!"
        webhook_url: "{{ env.SLACK_WEBHOOK }}"

Auto-Recognition For Meeting Team Goals

A good choice to reward developers for submitting great PRs would be to automate a Slack message that gives the developer recognition among their colleagues. To do this, you’ll need to create a Slack 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:
  slack_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-slack-message@v1
          args:
            webhook_url: "{{ env.SLACK_WEBHOOK }}"
            message: ":tada: 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 Slack automation actions at once, all with different webhooks and conditions. In an organization with different secrets for Slack webhooks to the #security-team channel, the #qa-team channel, and the #docs-team channel.

# -*- mode: yaml -*-

manifest:
  version: 1.0

automations:
  send_slack_security:
    # use your custom logic here to determine whether this needs a security review
    if:
      - true
    run:
      - action: send-slack-message@v1
        args:
          webhook_url: "{{ env.SLACK_WEBHOOK_SECURITY }}"
          message: "A PR requires a security review. See https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"
  send_slack_qa:
    # use your custom logic here to determine whether this needs a qa review
    if:
      - {{ not (files | match(regex=r/(test|spec)/) | some) }}
    run:
      - action: send-slack-message@v1
        args:
          webhook_url: "{{ env.SLACK_WEBHOOK_QA }}"
          message: "A PR was submitted without tests. See https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"
  send_slack_docs:
    # use your custom logic here to determine whether this needs a docs review
    if:
      - {{ files | match(regex=r/(docs)/) | some }}
    run:
      - action: send-slack-message@v1
        args:
          webhook_url: "{{ env.SLACK_WEBHOOK_DOCS }}"
          message: "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 Slack.

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.