Skip to main content

​
Commands

​
athanor serve

Start the webhook server. 
athanor serve
Reads configuration from environment variables (or /etc/athanor/env via systemd).

​
athanor (default)

Launch the interactive TUI to run workflows locally. 
# Interactive — pick a workflow
athanor

# Run a specific workflow
athanor --workflow .github/workflows/ci.yml

# Custom workflow directory
athanor --workflow-dir ./my-workflows

​
Flags (Local Mode)

FlagDefaultDescription
--workflow-dir.github/workflowsDirectory to search for workflow files
--workflow(none)Path to a specific workflow file (skips the selection TUI)

​
Environment Variables (Server Mode)

​
Required

VariableDescription
WEBHOOK_SECRETGitHub webhook secret for signature validation
GITHUB_TOKENPersonal access token with repo:status scope

​
Server

VariableDefaultDescription
LISTEN_ADDR:8080Address to listen on
WORKSPACE_DIR/var/lib/athanor/workspacesWhere repos are cloned

​
MicroVM

Set KERNEL_PATH to enable VM mode. If unset, steps run directly on the host.
VariableDefaultDescription
KERNEL_PATH(none)Path to vmlinux kernel. Enables VM mode.
ROOTFS_PATH/var/lib/athanor/rootfs.ext4Base rootfs image
SSH_KEY_PATH/var/lib/athanor/vm-ssh-keySSH private key for VM access
VM_DISK_DIR/var/lib/athanor/vm-disksDirectory for per-VM rootfs copies
VM_CPUS2vCPUs per VM
VM_MEMORY_MB2048RAM per VM in MB
VM_MAX_PARALLEL0 (auto)Max concurrent VMs. 0 = auto-detect from host RAM.

​
GitHub App (Optional)

For Checks API support with full logs. See GitHub App Setup.
VariableDescription
GITHUB_APP_IDGitHub App ID
GITHUB_APP_INSTALLATION_IDInstallation ID
GITHUB_APP_PRIVATE_KEY_PATHPath to the .pem private key

​
HTTP Endpoints

MethodPathDescription
GET/Web dashboard
GET/healthHealth check (returns ok)
POST/webhookGitHub webhook receiver
GET/api/runsRecent runs as JSON
GET/api/eventsSSE stream of run updates

​
Make Targets

TargetDescription
make buildBuild binary to bin/athanor
make build-linuxCross-compile for Linux (arm64 + amd64)
make testRun all tests
make vetRun go vet ./...
make runBuild and launch the TUI
make run-workflow WORKFLOW=pathBuild and run a specific workflow
make cleanRemove build artifacts