GitHub webhook handler and SSH deployment automation tool with Discord notifications, message status, and metadata-aware validation workflows.
- Features
- Requirements
- Setup
- Usage
- Development
- Testing
- Troubleshooting
- Security
- Configuration
- Operations
- Commands
- Events
- Intents and permissions
- Support
- Links
- License
Knit validates GitHub signatures and trusted targets. It runs repository commands through SSH and sends event results to Discord.
Use Node.js 26 or later and npm 12 or later. Provide a GitHub webhook secret and a target inventory. Configure Discord to enable notices.
Run npm ci to install packages. Set runtime values and create the target inventory as shown in the configuration guide. Read the docs index for user guides.
Run npm start to start Knit. Configure the GitHub webhook as described in the usage guide. Read release notes for version changes.
Read AGENTS.md and the specifications index before you change files. Keep documentation and records in this repository.
Run npm test for full validation. It runs the repository checks through eliware-test.
Read the troubleshooting guide to check startup, webhook, target, SSH, and Discord faults.
Keep secrets, credentials, private data, and runtime state out of Git. Knit verifies webhook signatures and SSH host keys before it runs commands.
Set GITHUB_WEBHOOK_SECRET at runtime. Set GITHUB_READ_TOKEN to read private repository contents. Set both DISCORD_TOKEN and DISCORD_CLIENT_ID to enable Discord notices.
Set KNIT_CONFIG_PATH or KNIT_TARGETS_PATH to select the target inventory. Set PORT to change the default port, 3456.
Read the configuration guide for all settings and examples.
Knit validates targets before it connects. For a branch push, it reads .knit/deploy.yaml at the webhook commit and runs the configured commands. It returns HTTP 200 after it verifies and queues a valid request.
The GHCR image runs Knit. The publish workflow runs on version tags and does not set a target platform. GHCR package settings define image visibility and pull access. The publish job uses GITHUB_TOKEN with packages: write. This permission does not set pull access.
GitOps deploys the published image by immutable version tag and recorded SHA-256 digest. Image publication does not deploy Knit.
Read the usage guide for startup, webhook behavior, health checks, and shutdown.
The /help command replies with a localized summary of Knit. Knit handles signed GitHub events and deployment notices.
The clientReady event logs that the Discord client started. The interactionCreate event routes chat input commands and ignores other interaction types.
For GitHub push events, Knit runs configured branch deployments and sends a result notice. Matching tag pushes send a notice without running commands. Knit also sends specialized notices for release, workflow, pull request, issue, and deployment events when GitHub sends them.
Knit uses only the Guilds intent. Grant the bot the Administrator permission so it can access all channels. Do not add the bot to channel allowlists.
For help, questions, or to chat with the author and community, visit:
