Slack notification for GitHub pull requests

This tutorial shows how to create and test a workflow definition that subscribes to GitHub events to send Slack notification when there is a pull request.

• Prerequisites
• Step 1: Sign up to GitHub
• Step 2: Create a GitHub app
• Step 3: Setup GitHub app permissions
• Step 4: Install GitHub app
• Step 5: Retrieve client ID and client secret for GitHub app
• Step 6: Create GitHub OAuth 2.0 credentials
• Step 7: Sign up to Slack
• Step 8: Create a Slack app
• Step 9: Request scopes for Slack app
• Step 10: Installing and authorizing the Slack app
• Step 11: Create Slack OAuth 2.0 credentials
• Step 12: Create SimWorkflow workflow definition
  • Step 12.1: Plan the workflow definition
  • Step 12.2: Define the workflow definition
• Step 13: Define workflow definition variables
  • Step 13.1: GitHub webhook secret
  • Step 13.2: Slack channel ID
• Step 14: Define Webhook settings for the workflow definition
• Step 15: Create a GitHub repository webhook
• Summary

Prerequisites

To perform the steps in this tutorial, you must already have the following:

• An account with GitHub.
• An account with Slack to send Slack messages.
• A SimWorkflow account that you can log in to create workflow definitions.

Step 1: Sign up to GitHub

If you're a first-time user of GitHub, your first step is to sign up for a GitHub account.

Step 2: Create a GitHub app

1. Navigate to your GitHub account settings.

   • For a GitHub App owned by a personal account, click Settings.

   • For a GitHub App owned by an organization:

     1. Click Your organizations.

     2. To the right of the organization, click Settings.

2. In the left sidebar, click Developer settings.
3. In the left sidebar, click GitHub Apps.
4. Click New GitHub App button.
5. Enter SimWorkflow to the GitHub App name field.
6. Enter https://www.simworkflow.com/ to the Homepage URL field.
7. Enter https://www.simworkflow.com/credentials/callback to the Callback URL field.
8. Click Create GitHub App button.

Step 3: Setup GitHub app permissions

1. On the GitHub Apps page, click Edit button of SimWorkflow app.
2. In the left sidebar, click Permissions & events.
3. In Repository permissions section, select Access: Read-only for Pull requests permission.
4. Click Save changes button.

Step 4: Install GitHub app

1. On the GitHub Apps page, click Edit button of SimWorkflow app.
2. Click Install App.
3. Click Install next to the location where you want to install the GitHub App.
4. Select All repositories or Only select repositories.
   • For Only select repositories, select the repositories that you want the app to access under the Select repositories dropdown.
5. Click Install button.

Step 5: Retrieve client ID and client secret for GitHub app

1. On the GitHub Apps page, click Edit button of SimWorkflow app.
2. In the left sidebar, click General.
3. In the About section, copy the Client ID, we'll paste it later.
4. In Client secrets section, click Generate a new client secret button.
5. Copy the Client secret, we'll paste it later.

Step 6: Create GitHub OAuth 2.0 credentials

1. Log in to the SimWorkflow.
2. Navigate to Credentials.
3. Click Create credentials button.
4. Select OAuth 2.0 tab.
5. Select GitHub for the Provider field.
6. Enter GitHub to the Name field.
7. Paste the Client ID to the Client ID field.
8. Paste the Client secret to the Client secret field.
9. Enter repo to the Scopes field.
10. Click Create credentials button.

We'll use this credentials in the workflow definition when we integrate with GitHub for pull requests.

Step 7: Sign up to Slack

If you're a first-time user of Slack, your first step is to sign up for a Slack account.

Step 8: Create a Slack app

1. On the Your Apps page, select Create New App.

2. Select From scratch.

3. Enter SimWorkflow to the App Name field.

4. Select the Workspace where you'll be developing your app.

5. Select Create App.

Step 9: Request scopes for Slack app

1. Within OAuth & Permissions, scroll down to Scopes.

2. Under Bot Token Scopes, select Add an OAuth Scope.

3. To allow your app to post messages, add the chat:write scope.

Step 10: Installing and authorizing the Slack app

1. Return to the Basic Information section of the app management page.

2. Install your app by selecting the Install to Workspace button.

3. You'll now be sent through the Slack OAuth flow. Select Allow on the following screen.

4. After installation, navigate back to the OAuth & Permissions page.

5. Click Add New Redirect URL button under Redirect URLs.

6. Enter https://www.simworkflow.com/credentials/callback to the input field and click Add button.

7. Return to the Basic Information section of the app management page.

8. Under App Credentials, copy Client ID and Client Secret.

Step 11: Create Slack OAuth 2.0 credentials

1. Log in to the SimWorkflow.
2. Navigate to Credentials.
3. Click Create credentials button.
4. Select OAuth 2.0 tab.
5. Select Slack for the Provider dropdown.
6. Enter Slack chat write to the Name field.
7. Paste the Client ID to the Client ID field.
8. Paste the Client Secret to the Client secret field.
9. Enter chat:write to the Scopes field.
10. Click Create credentials button.

We'll use this credentials in the workflow definition when we integrate with Slack to send alerts.

Step 12: Create SimWorkflow workflow definition

Step 12.1: Plan the workflow definition

There are three key steps in the process:

1. Workflow automatically starts when pull request events occurred on GitHub.
   • We will enable Webhook for the workflow definition to subscribe to GitHub events.
2. Fetch the pull request details if the pull request event action is created or reopened, otherwise completed the workflow.
   • We will use HTTP Task to call GitHub API to fetch pull request details.
3. Slack the pull request details to a Slack channel.
   • We will use HTTP Task to call Slack API to post Slack message.

Step 12.2: Define the workflow definition

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Create workflow definition button.

4. Select General tab of the workflow definition.

5. Enter Slack GitHub Pull Request to the Name field.

6. Click Start task and select Input Parameters tab.

7. Enter the following JSON object to the Input parameters field:

   {
     "body": "${jsonata:$eval(workflow.input.body)}"
   }
   

   The system will use jsonata to create a JSON Object from the "body" field of the workflow input and set it to "body" field.

8. Click HTTP Task to add a system task and name it Get pull request.

9. Connect the Start task to the Get pull request task.

10. Click on the route between Start task and Get pull request task.

11. Enter Created or reopened to the Name field.

12. Select Condition for Conditional routing field.

13. Enter the following JavaScript to the editor:

    ['created', 'reopened'].includes($.body.action)
    

    The system will continue with this route only when the "body.action" field of the task input parameters is created or reopened.

14. Click End task to add a terminal task and name it End.

15. Connect the Start task to the End task.

16. Select Always true for Conditional routing field.

    • The system will continue with this route to complete the workflow when the action of the pull request event is not created and reopened.

17. Click Get pull request task and select Input Parameters tab.

18. Enter the following JSON object to the Input parameters field:

    {
      "pull_request": "${Start.input.body.pull_request}"
    }
    

    The system will reference the "body.pull_request" field from the Start task input to the "pull_request" field.

19. Click Get pull request task and select Configuration tab.

20. Select GitHub (OAuth 2.0) for Credentials field.

21. Enter the following JSON object to the HTTP request field:

    {
      "url": "${pull_request.url}",
      "method": "GET",
      "headers": {
        "Accept": "application/vnd.github.text+json"
      }
    }
    

    The HTTP request configuration will call the GitHub API to retrieve the pull request details.

22. Click HTTP Task to add a system task and name it Slack.

23. Connect the Get pull request task to the Slack task.

24. Click Slack task and select Input Parameters tab.

25. Enter the following JSON object to the Input parameters field:

    {
      "body": {
        "text": "Pull request: *${['Get pull request'].output.body.title}* ${['Get pull request'].output.body.state} with ${['Get pull request'].output.body.changed_files} changes.\n\n${Start.input.body.pull_request.html_url}",
        "channel": "${['swf:variables'].slackChannelId}"
      }
    }
    

26. Click Slack task and select Configuration tab.

27. Select Slack chat write (OAuth 2.0) for Credentials field.

28. Enter the following JSON object to the HTTP request field:

    {
      "url": "https://slack.com/api/chat.postMessage",
      "body": "${body}",
      "method": "POST",
      "headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
      }
    }
    
    

    The HTTP request configuration will call the Slack API to post the alert message to the Slack channel.

29. Click Save button.

30. Toggle the Enable checkbox to enable the workflow definition.

Use this workflow definition

Step 13: Define workflow definition variables

1. Log in to the SimWorkflow.
2. Navigate to Workflow definitions.
3. Click Variables menu item from the three dots (more options) menu of the Slack GitHub Pull Request workflow definition.

Step 13.1: GitHub webhook secret

1. Enter githubWebhookSecret to the Variable key field.
2. Create the GitHub secret token and enter it to the Variable value field.
3. Click Save variable button.

Step 13.2: Slack channel ID

1. Enter slackChannelId to the Variable key field.
2. Locate the Slack channel ID and enter it to the Variable value field.
3. Click Save variable button.

Step 14: Define Webhook settings for the workflow definition

1. Log in to the SimWorkflow.

2. Navigate to Workflow definitions.

3. Click Webhook settings menu item from the three dots (more options) menu of the Slack GitHub Pull Request workflow definition.

4. Turn on Webhook on field.

5. Copy the Webhook endpoint URL, we'll paste it later.

6. Select a user for User to start the workflow as field.

7. Enter the following JavaScript to the Validate the payload field:

   'sha256=' + Swf.hmacSha256Hex($['swf:variables'].githubWebhookSecret, $.body) === $.headers['x-hub-signature-256']
   

   The system will use the workflow definition variable githubWebhookSecret to verify that a webhook delivery is from GitHub.

8. Click Save webhook settings button.

Step 15: Create a GitHub repository webhook

1. On GitHub.com, navigate to the main page of the repository.
2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
3. In the left sidebar, click Webhooks.
4. Click Add webhook button.
5. Paste the workflow definition Webhook endpoint to the Payload URL field.
6. Select application/json for the Content type field.
7. Paste GitHub secret token to the Secret field.
8. Select Let me select individual events. for the Which events would you like to trigger this webhook? field.
9. Ensure only the Pull requests checkbox is checked.
10. Click Add webhook button.

Summary

You've now successfully completed all the steps necessary to define a workflow definition to send a Slack message when there is a GitHub pull request. You've learned how to integrate with third party APIs using SimWorkflow HTTP tasks and Webhooks. As a result, you are able to have an automated process to send Slack messages when there are GitHub pull requests.