GitHub Board Slack notifications
The purpose of this project is to send notifications to a Slack channel for any changes that are performed in a GitHub board (Projects v2 / beta). This application uses AWS Lambda as backend which is provisioned with Terraform.
Features
Currently notifications are being sent for the following events:
- A Draft Issue is created on a board column that has a valid status.
No Statuscolumn is not being notified. - An existing Issue is added to a board column that has a valid status.
- A Draft Issue is converted to an Issue.
- An Issue or Draft Issue is moved to a different column that has a valid status.
- An Issue is removed from the board.
Setup
In order for this integration to work, a GitHub App must be created and installed in the organisation that contains the targeted projects and a Slack application is required to post on the specified channels.
The steps are the following:
- Fork this repository
- Create a Slack app by going to https://api.slack.com/apps and pressing the
Create New Appbutton. - Grab the Signing secret in the app page and save it as
PROD_SLACK_SIGNING_SECRETin theSecrets -> Actionssection of your GitHub repository. - Navigate to the
OAuth & Permissionson the left sidebar and scroll down to the Bot Token Scopes section. ClickAdd an OAuth Scope. Add thechat:writescope. Grab the generatedBot User OAuth Tokenand save it asPROD_SLACK_TOKENin the GitHub repository secrets. - Create a new Secret in the GitHub repo named
PROD_ORG_WEBHOOK_SECRETand set it to a random string of 16 or more characters. Save it for later. - Go to the Settings page of your organisations, then to
Developer settings->GitHub apps. The url should look something like https://github.com/organizations/your-organisation/settings/apps - Create a new GitHub App using the
New GitHub Appbutton - In the app creation page, after setting the name and application URL, you need to set the following permissions required by the app:
- Repository:
- Issues:read-only
- Pull requests:read-only
- Organisation:
- Projects:read-only
- Repository:
- In the
Permissions & eventspage accessible for the GitHub app edit page, in theSubscribe to eventssection, checkProjects v2 item - From the GitHub application edit page, grab the
App IDand save it in the repo secrets asPROD_ORG_APP_ID - In the GitHub application edit page, go to the
Private keyssection an click onGenerate a private key. The resulting PEM file will be downloaded automatically onto your computer. Open that file with a text editor and paste the key into a base64 encoder. Save the base64 converted string into the repo GitHub secrets asPROD_ORG_PRIVATE_KEY - Deploy the application to AWS after checking the infra README
- Grab the URL provided by the terraform output and add it to the GitHub Application edit page, in the Webhook section. Add the value that was saved as
PROD_ORG_WEBHOOK_SECRETto the webhook secret field, save changes. - Install the Slack Bot Application into your Slack workspace and add the Slack Bot to each channel that will receive notifications.
- Configure the Slack channel for each project that should be used for notifications according to the guide below.
Configuring the Slack channel for a project
The webhook will receive events from all projects inside the organisation where the GitHub App is installed. In order to configure the Slack channel(s) that get notified when changes are done on project boards, a custom field must be added inside the projects' settings.
The field must be named SlackChannel with the type Single select. The configured options will be the channels that will receive the notification.
The Slack bot should be added to those channels otherwise message sending will fail.
Dev/Prod separation
All the steps above need to be redone for a DEV app and the secrets prefixed with DEV_ instead of PROD_.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![optic-release-automation[bot] avatar](https://avatars.githubusercontent.com/u/1544687?v=4 "optic-release-automation[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent