GitHub Notifier

Post Open Pull Requests to Slack.

Simple Usage Example

GitHub Notifier is a TypeScript GitHub Action that posts open pull requests to Slack channels based on a scheduled job to remind team members to review pull requests.

Overview

This GitHub Action will query the GitHub (or GitHub Enterprise) org for all repositories (based on token permissions) and then, for each repository it will check for open pull requests. Then, it will attempt to match any related GitHub users to Slack users before building Slack blocks and posting a message (or multiple messages in the case of many PRs) to the designated Slack channels.

Quick start

1. (Optional) Start by creating a repository called github-notifier.

   1. Whatever repo you use to host this workflow needs to be able to use GitHub Runners.

2. Generate a GitHub token – You’ll need a fine-grained GitHub token that allows access to either all your repositories or just the ones you want notifications about.

   Here are the specific permissions the token needs:

   • Repository Administration: read – This lets the token list repositories within the organization.
   • Repository Pull Requests: read – Required to fetch details about pull requests.
   • Repository Contents: read – Allows the token to check the status of repository branch protections.
   • Organization Members: read – Required to retrieve GitHub email addresses for matching them with Slack users.

   Make sure the token is created by an organization owner, as it must belong to the organization where the relevant repositories and pull requests live.

   1. Save the token in your repository by going to Settings > Secrets and variables > Actions > New repository secret, and name it GH_TOKEN_GH_NOTIFIER.

3. Create a Slack App either from scratch or by using a pre-defined manifest file.

   • To create from scratch: Start a new app called GitHub Notifier and add it to your Slack workspace.
   • To use the manifest: On the Slack App creation page, select "From an app manifest" and upload your manifest.json file to quickly set up the app.

   1. On the OAuth & Permissions page, assign the following scopes to the bot,

      • chat:write – So the bot can post messages in Slack channels.
      • users:read – To look up Slack users for matching with GitHub accounts.
      • users:read.email – Allows the bot to retrieve Slack user emails for matching with GitHub accounts.
      • chat:write.customize – This enables the bot to modify its display name and avatar when posting.

   2. On the OAuth & Permissions page, click Install To Workspace, then copy the User OAuth Token.

   3. Save this token in your repository at Settings > Secrets and variables > Actions > New repository secret, naming it SLACK_TOKEN_GH_NOTIFIER.

   4. Add the Slack app you just created to the relevant Slack channel(s) and note down the channel IDs for the workflow.

4. Set up a workflow similar to this:

   # .github/workflows/github-notifier.yaml
   
   name: GitHub Notifier
   
   on:
     schedule:
     - cron: 0 15,17,19,21,23 * * 1-5
     workflow_dispatch:
   
   jobs:
     github-notifier:
       runs-on: ubuntu-latest
       steps:
       - uses: krauters/github-notifier@main
         with:
           github-token: ${{ secrets.GH_TOKEN_GH_NOTIFIER }}
           channels: C07L8EWB389
           slack-token: ${{ secrets.SLACK_TOKEN_GH_NOTIFIER }}

   For more details about available inputs, you can check out the action definition file, action.yaml.

Input Variables

See action.yaml for more detailed information.

| Name | Description | Required | Default | |-----------------------|---------------------------------------------------------------------------------------------|----------|----------| | github-token | Fine-grained GitHub token with necessary scopes for administration, PR details, and members.| Yes | | | slack-token | Permissions to post to Slack and perform user lookups. | Yes | | | channels | Comma-separated list of Slack channel IDs to post to. | Yes | | | with-archived | Include PRs from archived repositories. | No | false | | with-public | Include PRs from public repositories. | No | true | | with-drafts | Include draft PRs. | No | false | | No | false | | with-user-mentions | Allow Slack user mentions. | No | true | | repository-filter | Comma-separated list of repositories to scan. | No | | | base-url | Base GitHub API URL (e.g., https://api.github.com). | No | |

Troubleshooting

Error: An API error occurred: channel_not_found

This error means the Slack app probably wasn’t added to the channel you’re trying to post in.

Husky

Husky helps manage Git hooks easily, automating things like running tests or linting before a commit is made. This ensures your code is in good shape.

Pre-commit hooks run scripts before a commit is finalized to catch issues or enforce standards. With Husky, setting up these hooks across your team becomes easy, keeping your codebase clean and consistent.

Our Custom Pre-Commit Hook

This project uses a custom pre-commit hook to run npm run bundle. This ensures that our bundled assets are always up to date before any commit (which is especially important for TypeScript GitHub Actions). Husky automates this, so no commits will go through without a fresh bundle, keeping everything streamlined.

Contributing

The goal of this project is to continually evolve and improve its core features, making it more efficient and easier to use. Development happens openly here on GitHub, and we’re thankful to the community for contributing bug fixes, enhancements, and fresh ideas. Whether you're fixing a small bug or suggesting a major improvement, your input is invaluable.

License

This project is licensed under the ISC License. Please see the LICENSE file for more details.

🥂 Thanks Contributors

Thanks for spending time on this project.

References to this project

• Stack Overflow / Customizing slack notification for Github pull requests

• Reddit / Recommended slack app to post github pull requests notifications?

• GitHub Discussions / Best way to send slack to developers notifications daily about new PRs, new issues or new comments?