Documentation: GitHub App authentication for Workspaces is undocumented

[axon-agent]

🤖 Axon Agent @gjkim42

Problem

GitHub App authentication for Workspaces is fully implemented in Axon but is completely absent from all user-facing documentation. A new user following the README, reference docs, or `axon init` template would have no idea this authentication option exists.

What's implemented (but undocumented)

The `workspace.githubApp` config option is wired end-to-end:

• CLI config (`internal/cli/config.go`): `WorkspaceConfig.GitHubApp` struct with `appID`, `installationID`, `privateKeyPath` fields
• `axon run` (`internal/cli/run.go`): Creates a Kubernetes secret from GitHub App credentials when `githubApp` is set in config
• Controller (`internal/controller/task_controller.go`): Calls `resolveGitHubAppToken` to exchange App credentials for an installation token before each task run
• `internal/githubapp/token.go`: Full JWT generation and GitHub API token exchange implementation (supports PKCS1 and PKCS8 PEM keys)

What's missing from docs

1. README (Quick Start → credential details): No mention of GitHub App as a workspace auth option
2. `docs/reference.md` (Workspace section): Only documents `secretRef` (PAT), not `githubApp`
3. `axon init` config template: Only shows `token: ""` for workspace, no GitHub App example
4. `examples/` directory: No example using GitHub App authentication
5. `self-development/README.md`: Has a comment # or authenticate with githubApp but no actual example

Why It Matters

GitHub recommends GitHub Apps over Personal Access Tokens for production/organizational use:

• Fine-grained permissions at the installation level
• Higher rate limits
• No dependency on a specific user account (bots don't need PATs)
• Tokens expire automatically (more secure than long-lived PATs)

Teams deploying Axon in production environments are likely to prefer or be required to use GitHub Apps, but they currently have no documentation to guide them.

Suggested Fix

1. Add a githubApp section to docs/reference.md in the Workspace spec table
2. Add a commented-out GitHub App example to the `axon init` config template
3. Add a note in the README's "How to get your credentials" section
4. Optionally add an example or note in `examples/02-task-with-workspace/`

Example config snippet to document

```yaml

Alternative: GitHub App authentication (recommended for production/org use)

workspace:

repo: https://github.com/org/repo.git

ref: main

githubApp:

appID: "12345"

installationID: "67890"

privateKeyPath: ~/.config/my-app.private-key.pem

```

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs

Status: STILL VALID

Evidence:

• No merged PRs reference this issue (gh pr list --state merged --search "436" returned empty)
• No recent commits on main mention issue 436 or GitHub App documentation changes
• Verified the current codebase confirms all claims in the issue are accurate:
  • README.md (lines 113-119): Only shows token for workspace config, no mention of GitHub App auth
  • docs/reference.md (lines 45-51): Only documents secretRef.name (PAT-based), githubApp is absent
  • kelos init template (internal/cli/init.go lines 36-39): Only shows token, no githubApp example
  • examples/ directory: All 7 examples use PAT-based secretRef, none demonstrate GitHub App auth
  • self-development/README.md (lines 32, 114): Contains only bare comments # or authenticate with githubApp with no actual config shown
• The feature itself is fully implemented and tested:
  • internal/cli/config.go: GitHubAppConfig struct with AppID, InstallationID, PrivateKeyPath
  • internal/cli/run.go: ensureGitHubAppSecret() creates K8s secrets from GitHub App credentials
  • internal/controller/task_controller.go: resolveGitHubAppToken() exchanges App credentials for installation tokens
  • internal/githubapp/token.go: Full JWT generation and GitHub API token exchange (PKCS1/PKCS8)
  • cmd/kelos-token-refresher/main.go: Sidecar for periodic token refresh
  • Integration tests cover GitHub App scenarios in test/integration/
• The project was renamed from axon to kelos (issue [ANNOUNCE] Rename project: axon-core/axon → kelos-dev/kelos #456), but the documentation gap persists — the rename did not add GitHub App documentation

Duplicates found: None found. Other open docs issues (#365, #305, #242, #221, #205, #204, #202, #201, #195) cover different topics (troubleshooting, Quick Start ordering, model values, TaskSpawner docs, credential types). Issue #454 is about incorrect field names in example 05, not GitHub App auth.

Recommendation: KEEP OPEN — The documentation gap is real and well-scoped. GitHub App auth is a production-grade feature that is fully implemented but invisible to users. The suggested fixes in the issue are reasonable and actionable.