GitHub webhook handler and SSH deployment automation service with Discord notifications, delivery-aware presence, 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 target profiles. It reads each repository workflow at the event commit. It runs approved commands on verified SSH targets. It sends event and deployment results to Discord.
Use Node.js 26 or later. Provide a GitHub webhook secret and a valid target inventory. Provide a Discord bot and guild settings to enable Discord notices.
Install dependencies with npm ci. Set the runtime variables in the configuration guide. Create the target inventory. Add a version 1 workflow to each repository. Read the docs index for the end-user guides.
Run npm start to start Knit. Set the GitHub webhook URL to https://<host>/. Set the webhook content type to application/json. Use GET /health to check service status. Read the docs index for end-user guides. Read release notes for version changes. Read specifications for repository requirements.
Use Node.js 26 and npm. Run npm ci to install locked packages. Keep runtime secrets and target credentials outside Git.
Run npm test for full validation. Run npm run lint for lint checks. Run npm run audit for dependency checks. Run npm run format to format files. Run npm run format:check to check file format.
Check webhook delivery status, signature settings, target access, and SSH host keys. Follow the troubleshooting guide for fault steps.
Knit checks the webhook signature before event processing. It reads workflows at the signed commit. It checks target access and SSH host keys before remote commands.
Set GITHUB_WEBHOOK_SECRET as a runtime secret. Set GITHUB_READ_TOKEN for private GitHub repositories or higher API limits. Set DISCORD_TOKEN and DISCORD_CLIENT_ID together to enable Discord. 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 fields and examples.
Knit validates targets before it opens external connections. It gets .knit/deploy.yaml and package.json at the webhook commit. It runs deployment commands in order. A nonzero command result marks the deployment as failed. GHCR publication builds an image. GitOps controls image deployment. Read usage for start, health, and shutdown steps.
The /help command gives a short service summary. Knit requests only the Discord Guilds intent.
Knit handles repository push events. It sends special Discord notices for release, workflow_run, pull_request, issues, deployment, and deployment_status events. It sends a general notice for other repository events. It ignores events without a repository name.
For each event, Knit uses the repository name after the owner slash as the announcement channel name. Knit encodes punctuation as _xHEX_ so different names stay distinct. Knit does not add a hash or truncate a name. Names longer than 100 characters fail. Knit checks for a matching announcement channel. It creates one if no matching channel exists, including when another channel type has that name. Knit sets access from repository visibility, updates the topic from package metadata, and posts the notice. Long descriptions do not remove topic keywords.
Knit returns HTTP 200 after it queues a valid signed webhook. Knit does not wait for event processing to finish.
Enable the Guilds intent. Grant the bot the Administrator permission. The bot can access all channels. Do not add the bot to channel allowlists. Knit does not request message, member, presence, reaction, typing, or scheduled event intents.
For help, questions, or to chat with the author and community, visit:
