Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/krauters/github-notifier
Rich GitHub pull request notifications posted to Slack.
https://github.com/krauters/github-notifier
chatops devops github-notifications github-notifier notifications pull-request-automation pull-requests slack slack-api
Last synced: 5 days ago
JSON representation
Rich GitHub pull request notifications posted to Slack.
- Host: GitHub
- URL: https://github.com/krauters/github-notifier
- Owner: krauters
- License: isc
- Created: 2024-06-19T02:41:33.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-09-25T16:17:08.000Z (about 1 month ago)
- Last Synced: 2024-10-04T21:36:23.504Z (about 1 month ago)
- Topics: chatops, devops, github-notifications, github-notifier, notifications, pull-request-automation, pull-requests, slack, slack-api
- Language: TypeScript
- Homepage: https://npmjs.com/package/@krauters/github-notifier
- Size: 1.52 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/marketplace/actions/github-notifier-by-krauters)
[](https://www.npmjs.org/package/@krauters/github-notifier)
[](https://packagephobia.now.sh/result?p=@krauters/github-notifier)
# GitHub Notifier
Post Open Pull Requests to Slack.
[Simple Usage Example](https://github.com/krauters/github-slack-notifier)
**GitHub Notifier** is a _TypeScript_ [GitHub Action](https://docs.github.com/en/actions) that posts open pull requests to Slack channels based on a [scheduled job](https://crontab.guru/) 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](https://app.slack.com/block-kit-builder/T025EE5RS#%7B%22blocks%22:%5B%5D%7D) 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.
1. [Generate a GitHub token](https://github.com/settings/tokens?type=beta) – 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**.
1. [Create a Slack App](https://api.slack.com/apps) either _from scratch_ or by using a pre-defined [manifest file](./manafest.json).
- 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.
1. On the **OAuth & Permissions** page, click `Install To Workspace`, then copy the `User OAuth Token`.
1. Save this token in your repository at `Settings` > `Secrets and variables` > `Actions` > `New repository secret`, naming it **SLACK_TOKEN_GH_NOTIFIER**.
1. Add the Slack app you just created to the relevant Slack channel(s) and note down the channel IDs for the workflow.
1. Set up a workflow similar to this:
```yaml
# .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](./action.yaml).
## Input Variables
See [action.yaml](./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](./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](https://stackoverflow.com/questions/66948900/customizing-slack-notification-for-github-pull-requests/78949579#78949579)
- [Reddit / Recommended slack app to post github pull requests notifications?](https://www.reddit.com/r/Slack/comments/1e3pdfr/comment/llhfu11/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button)
- [GitHub Discussions / Best way to send slack to developers notifications daily about new PRs, new issues or new comments?](https://github.com/orgs/community/discussions/70288)
