handles a merge queue with github actions and slack.

NOTE: smart-host has taken stewardship of the repository and transferred from lwhiteley/slack-merge-queue. The last version under the previous owner's account is lwhiteley/slack-merge-queue@v3. Please now use the version specified below in the documentation.

Create a slack api bot via https://api.slack.com/apps

then setup the following permissions

Base required scopes:

• chat:write.customize
• users:read.email
• incoming-webhook: should be enabled when the bot is added to a channel

Methods used and their scopes:

Please see each method's required scopes and add them to your slack bot token. If a new method is used with a new set of scopes, this will typically be a breaking change

Methods:

• users.info
• conversations.members
• conversations.list
• conversations.history
• conversations.replies
• chat.postMessage
• chat.update
• chat.delete

Once the bot is setup, install the bot to your desired channel.

NB:

• For private channels (or additional private channels), the bot (App) must be added to the channel

create a github secret with name SLACK_TOKEN and its value the Bot User OAuth Access Token.

Add the actions to your workflow. ensure the modes are used correctly as explained in the Modes section.

There are various modes to achieve the different actions to manage the queue. These are:

This mode is responsible for adding a pull request to the slack queue. You can do this by commenting on a pull request with the init_trigger (default: /merging). For this mode to work, ensure this piece of your workflow is merged to the main branch of your repository.

sample:

name: sample-add-to-q

on:
  issue_comment:
    types: [created, edited]
  pull_request_review:
    types: [submitted, edited]

jobs:
  add_to_queue:
    env:
      SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}
    runs-on: ubuntu-latest
    name: Add PR to queue
    steps:
      - name: Add PR to queue
        uses: smart-host/slack-merge-queue@v4
        id: add_to_q
        with:
          mode: 'INIT'
          channel: 'merge-queue'
          init_trigger: '/merging'
      # Use the output from the `add_to_q` step
      - name: Get the output
        run: echo "status => ${{ steps.add_to_q.outputs.status }}"

Additionally, you can set slack users to be notified by using a notify: tag in the comment on a new line. This is a comma seperated list of user references. The user reference can be the:

• slack member id
• slack member's full name
• slack display name
• slack username
• email username portion (eg. john.doe@smq.com)

Please note that these references are case sensitive

eg.

/merging
notify: U024BE7LH, Max Musterman, Mark, jim.j, john.doe

Tips:

• You can update the notify: list in slack by editing an existing INIT comment.
  • Only the watchers list can be updated by a comment change once a pull request is in the queue.
• If your slack username is the same as your github username then you will be automatically notified without specifying the notify list. This includes assignees and all other users associated with the pull request and comment made (except reviewers list)
  • github usernames will be lowercased to match slack requirements

This mode manually sets the status of a PR in the queue to CANCELLED without needing to close a pull request. This can be considered a temporary cancel. To trigger this mode a comment can be made on the pull request with the desired or default trigger phrase.

eg. trigger cancel and override delete_on_cancel option

/cancel-merge
delete_on_cancel: true

Actions taken:

• It will change the Queue Status from MERGING to CANCELLED.
• It will send a message to alert the next pull request in the queue when the current pull request is cancelled. Alert is only sent if the next PR is the next in line to be merged.
• if configured, will delete message thread after cancel complete

sample:

name: sample_cancel_in_queue

on:
  issue_comment:
    types: [created]
  pull_request_review:
    types: [submitted]

jobs:
  add_to_queue:
    env: # Or as an environment variable
      SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}
    runs-on: ubuntu-latest
    name: Cancel PR in queue
    steps:
      - name: Cancel PR in queue
        uses: smart-host/slack-merge-queue@v4
        id: cancel_pr
        with:
          mode: 'CANCEL'
          channel: 'merge-queue'
          cancel_trigger: '/cancel-merge'
          cancel_ready_message: 'Previous PR merge was temporarily cancelled. This PR is now up for merge!'
          # delete_on_cancel: 'true' # uncomment if you want to delete cancelled prs from queue
      # Use the output from the `cancel_pr` step
      - name: Get the output
        run: echo "status => ${{ steps.cancel_pr.outputs.status }}"
      - name: Get the next PR number
        run: echo "next pr => ${{ steps.cancel_pr.outputs.next_pr }}"

This mode updates the slack message of the current pull request.

Actions taken:

• It will change the Queue Status from MERGING to either CANCELLED or MERGED for current PR.
• It will send a message to alert the next Pull request in the queue when the current pull request is closed/merged.
• If a PR is merged ahead of one currently up for merge, The unmerged PR(s) will be marked as STALE. They can be added to the queue again by re-triggering the INIT mode.
• if configured, will delete message thread after cancel complete

sample:

name: sample_update_queue

on:
  pull_request:
    types: [closed]

jobs:
  update_q_on_close:
    env:
      SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}
    runs-on: ubuntu-latest
    name: Update Queue
    steps:
      - name: Update queue
        uses: smart-host/slack-merge-queue@v4
        id: update_q_on_close
        with:
          mode: 'MERGE'
          channel: 'merge-queue'
          merge_ready_message: 'Last PR closed. This PR is now up for merge!'
          # delete_on_cancel: 'true' # uncomment if you want to delete cancelled prs from queue
      # Use the output from the `update_q_on_close` step
      - name: Get the output status
        run: echo "status => ${{ steps.update_q_on_close.outputs.status }}"
      - name: Get the next PR number
        run: echo "next pr => ${{ steps.update_q_on_close.outputs.next_pr }}"

This mode alerts the current pull request in the queue by adding a message to its thread. Typically this can be used to alert the thread when the build/workflow is complete but can be used at any point in the build process based on your use case. If used to alert when the build is complete, ensure the proper dependencies are set to ensure the job is run last or close to last as a post build step.

simple example:

• pr-build-complete.yml

workflow completed example:

• pr-build-complete-wait.yml
• dummy-build.yml

name: sample_alert_current

on:
  workflow_run:
    # will trigger alert for each workflow listed
    workflows: ['mock-workflow']
    types:
      - completed

jobs:
  alert_current_pr:
    env:
      SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }}
    runs-on: ubuntu-latest
    name: Alert Current in Queue
    steps:
      - name: Alert queue
        uses: smart-host/slack-merge-queue@v4
        id: alert
        with:
          mode: 'ALERT'
          channel: 'merge-queue'
          # the following variables are only available in 'workflow_run' event
          alert_message: '`${{ github.event.workflow.name }}` is complete with status `${{ github.event.workflow_run.conclusion }}`!'
      # Use the output from the `alert` step
      - name: Get the output status
        run: echo "status => ${{ steps.alert.outputs.status }}"

• Invalid required inputs will fail the build
• Process errors will not fail the build
  • A status will be given along with an error log

The queue tag is sent by the INIT mode.

Pattern: [Search Prefix] :: [PR number] :: [Queue Status] :: [PR link]

eg.

Q-PR :: 3 :: MERGED :: chore: add package keyword

• Pull requests are welcome!

Apache 2.0