Documentation Index
Fetch the complete documentation index at: https://athanor.alexisbouchez.com/llms.txt
Use this file to discover all available pages before exploring further.
By default, Athanor reports results via commit statuses (pass/fail). To get full log output visible directly on GitHub, with per-step details, expandable logs, and proper check run annotations, you need to create a GitHub App.
This is the standard way to integrate CI systems with GitHub. The Checks API is only available to GitHub Apps, not personal access tokens.
Why a GitHub App?
| Commit Statuses (PAT) | Checks API (GitHub App) |
|---|
| Pass/fail badge | Yes | Yes |
| Per-workflow status | No (single “athanor” check) | Yes (one check per workflow) |
| Log output on GitHub | No | Yes (full Markdown logs) |
| Per-step details | No | Yes |
| Token expiry | Manual rotation | Auto-refreshing (1-hour tokens) |
Step 1: Create the App
Go to github.com/settings/apps/new and fill in:
| Field | Value |
|---|
| GitHub App name | athanor-ci (or any name you want) |
| Homepage URL | http://your-server-ip:8080 |
| Webhook | Uncheck “Active” (Athanor has its own webhook handler) |
Permissions
Under Repository permissions, set:
| Permission | Access |
|---|
| Checks | Read & Write |
| Commit statuses | Read & Write |
| Contents | Read-only |
| Metadata | Read-only |
Step 2: Note the App ID
After creation, you’ll be on the app’s settings page. The App ID is displayed near the top, a number like 123456. Save this.
Step 3: Generate a Private Key
On the same settings page, scroll to Private keys and click Generate a private key.
A .pem file downloads to your machine. This is the private key Athanor uses to authenticate as the app. Keep it safe.
Step 4: Install the App
In the left sidebar of the app settings, click Install App.
Click Install next to your account. Select Only select repositories and choose your repository (e.g., athanor). Click Install.
After installation, note the Installation ID from the URL:
https://github.com/settings/installations/12345678
^^^^^^^^
Installation ID
Using the Setup Script
The repo includes a script that handles the rest:
./scripts/setup-github-app.sh <APP_ID> <path-to-private-key.pem>
- Upload the private key to the server
- Look up the installation ID automatically
- Update the server config
- Restart Athanor
Manual Configuration
If you prefer to do it manually, upload the private key:
scp your-app.private-key.pem root@your-server:/etc/athanor/github-app.pem
ssh root@your-server 'chmod 600 /etc/athanor/github-app.pem'
/etc/athanor/env:
GITHUB_APP_ID=123456
GITHUB_APP_INSTALLATION_ID=12345678
GITHUB_APP_PRIVATE_KEY_PATH=/etc/athanor/github-app.pem
systemctl restart athanor
Step 6: Verify
Check the logs to confirm the app is configured:
journalctl -u athanor -n 5 --no-pager
[athanor] GitHub App configured (app_id=123456, installation_id=12345678)
- Each workflow appears as a separate check run
- Click Details to see the full log output
- Logs are formatted as Markdown with per-job, per-step sections and code blocks
How It Works
Under the hood, Athanor uses standard GitHub App authentication:
- JWT generation. Athanor signs a short-lived JWT with the app’s RSA private key.
- Token exchange. The JWT is exchanged for an installation access token via
POST /app/installations/{id}/access_tokens.
- API calls. The installation token is used to create and update check runs via the Checks API.
- Token caching. Tokens are cached and refreshed automatically (they expire after 1 hour).
The PAT-based commit status is always set as a fallback, so even if the GitHub App fails, you still get pass/fail reporting.
Environment Variables Reference
| Variable | Required | Description |
|---|
GITHUB_APP_ID | Yes | The App ID from step 2 |
GITHUB_APP_INSTALLATION_ID | Yes | The Installation ID from step 4 |
GITHUB_APP_PRIVATE_KEY_PATH | Yes | Path to the .pem file on the server |
GITHUB_TOKEN, WEBHOOK_SECRET, etc.).