github-bot@node:~$ status github commits / discord webhooks / secure webhook verification simple commit logging through discord embeds
GitHub Bot is a lightweight Node.js webhook service that sends GitHub commits directly into Discord through configurable webhooks.
the bot is designed to be simple to setup and run, with an included launcher that automatically handles the initial configuration, dependency installation and GitHub webhook security.
commits can be separated between a main/public webhook and a hidden updates webhook, allowing selected commits to be shown publicly while normal development commits can still be logged privately.
incoming GitHub requests are authenticated using a shared webhook secret before any event is processed.
| commit logging | automatically sends GitHub commits into Discord as embeds |
| public updates | selected commits can be sent to the main/public Discord webhook |
| hidden updates | normal development commits can be logged separately through a private webhook |
| webhook security | incoming GitHub requests are verified using a shared secret signature |
| automatic setup | the launcher automatically creates the required configuration and environment files |
| secret generation | a secure GitHub webhook secret can be automatically generated during setup |
| dependencies | missing Node.js dependencies are automatically installed when the bot is launched |
| runtime |
|
| language |
|
| services |
|
clone or download the repository and launch the included .bat file.
the launcher will first check whether Node.js is installed.
if Node.js cannot be found, the Node.js website will automatically be opened and the launcher will ask you to install it before continuing.
on first launch the setup will ask for:
| main webhook | the Discord webhook used for public commit updates |
| hidden webhook | the Discord webhook used for normal/internal commit updates |
| port | the HTTP port used by the GitHub webhook endpoint |
these values are automatically saved into:
config.js
if config.js already exists, the configuration setup will be skipped.
the launcher also handles the GitHub webhook secret used to verify incoming requests.
if a .env file does not already exist, you will be prompted with:
GitHub Webhook Secret:
you can either enter your own secret or simply press Enter to have a secure secret automatically generated for you.
the launcher will then create:
.env
containing:
GITHUB_HOOK_SECRET=YOUR_SECRET
after creating the file, the launcher will display the secret that needs to be entered into GitHub.
the secret displayed by the launcher must be the exact same secret entered into the GitHub webhook settings.
the .env file contains private information and should never be committed to GitHub.
make sure your .gitignore contains:
.env
if the node_modules folder cannot be found, the launcher will automatically run:
npm install
once the dependencies have been installed, the bot will start automatically.
open the repository you want the bot to monitor and navigate to:
Settings > Webhooks > Add webhook
set the payload URL to:
http://IP_ADDRESS:PORT/recieve_github
replace IP_ADDRESS with the public IP address or domain of the machine running the bot.
replace PORT with the port configured during setup.
for example:
http://123.123.123.123:3000/recieve_github
or when using a domain and reverse proxy:
https://example.com/recieve_github
configure the GitHub webhook using the following settings:
| payload url | http://IP_ADDRESS:PORT/recieve_github |
| content type | application/json |
| secret | paste the exact secret generated or entered during the setup process |
| ssl verification | enabled when using HTTPS |
| events | select the events you want the bot to receive |
| active | enabled |
the secret entered into GitHub should contain only the secret itself.
for example, if the launcher creates:
GITHUB_HOOK_SECRET=98a1b14f75af236b83449ae9178731c651f5979e38c155238cb0b3794ebc8a27
you should enter this into GitHub:
98a1b14f75af236b83449ae9178731c651f5979e38c155238cb0b3794ebc8a27
not:
GITHUB_HOOK_SECRET=98a1b14f75af236b83449ae9178731c651f5979e38c155238cb0b3794ebc8a27
before processing an event, the bot verifies that the incoming request is valid.
| github hookshot | the request must identify itself as a GitHub Hookshot request |
| secret | the bot reads GITHUB_HOOK_SECRET from the environment |
| signature | the GitHub request signature must match the signature generated by the bot |
| comparison | signatures are compared using a timing-safe comparison |
requests that fail verification are rejected with:
403 Forbidden
this prevents unauthorised requests from pretending to be GitHub and triggering webhook events.
the bot separates commits between the main webhook and hidden updates webhook depending on the commit message.
| main webhook | commits using the required bracket format are displayed publicly |
| hidden webhook | commits without the bracket format are sent to the hidden updates webhook |
an example public update:
tweak(bot)
an example hidden/internal update:
Update server.js
this allows normal development commits to remain within the hidden updates channel while selected updates can be published through the main webhook.
the bot runs an HTTP endpoint which GitHub needs to access from the internet.
if you are hosting the bot from your own network, the configured port may need to be port forwarded through your router.
you can check whether a port is externally accessible using:
when exposing the bot publicly, using a domain with HTTPS and a reverse proxy is recommended over directly exposing the HTTP port.
