@eliware/knit

GitHub webhook handler and SSH deployment automation service.

Runtime

• Node.js >=26; ESM.
• POST / receives signed GitHub webhooks.
• GET / serves the Knit project landing page.
• GET /health returns service status and version.
• Repository configuration is YAML mounted at KNIT_CONFIG_PATH (default ./repos).
• YAML files use <owner>__<repo>.yaml naming in Kubernetes ConfigMaps.
• Configuration is loaded once per process; GitOps content-hashed ConfigMaps trigger a pod rollout for changes.

Configuration

Modern configuration uses SSH targets:

repository: owner/repo
discordChannelId: "123456789012345678"
git:
  url: git@github.com:owner/repo.git
  ref: main
targets:
  - name: dev
    host: dev.example
    user: root
    workingDirectory: /opt/repo
    pre: []
    post: []
execution:
  mode: sequential
  stopOnError: true

discordChannelId is the Discord channel snowflake where Knit posts embeds. Repository configuration is intentionally plaintext YAML and contains no credentials. The bot token and SSH assets remain runtime secrets; SSH assets are mounted at /run/secrets/eliware/ssh/.

Kubernetes uses a content-hashed ConfigMap for repository configuration. Updating a config through GitOps changes the ConfigMap name and the Deployment reference, causing Kubernetes to restart Knit with the new configuration. Knit does not monitor mounted files for changes while running.

Targets execute commands over SSH with strict host verification. identity and knownHosts may be host-installed or paths relative to the configured path. Modern targets are SSH-only.

New configurations must use YAML and SSH targets. Local Compose requires only KNIT_CONFIG_PATH; systemd requires an equivalent mounted/provisioned config path.

Knit self-deployment and organization fallback

eliware/knit is configured as the fallback target for organization-level GitHub events. Its push deployment runs git pull, npm install, and npm test on dev.purinton.us:/opt/knit, then sends the result to Discord. Successful deployments do not restart the process; release a new image and let Argo CD roll it out for Knit code changes.

Environment

Variable	Purpose
PORT	Listen port; default 3456
GITHUB_WEBHOOK_SECRET	GitHub signature secret
LOG_LEVEL	Logger level
KNIT_CONFIG_PATH	Mounted configuration directory
DISCORD_TOKEN	Discord bot token, supplied from a runtime Secret
DISCORD_CLIENT_ID	Discord application/client ID

Development

npm install
npm test
npm run lint
npm start

Kubernetes releases use immutable container images and Argo CD GitOps. Knit can receive its own repository webhook and SSH-deploy /opt/knit; new Knit code is delivered by releasing an image, not by runtime self-updating.