Documentation

Everything you need to know about installing, configuring, and using Athena CI/CD.

Quick Start

Athena works out of the box with zero configuration:

Install Athena from the GitHub Marketplace
Select the repositories you want Athena to analyze
Open a pull request — Athena will create Check Runs with its analysis

That's it. No YAML to write, no dashboard to visit, no commands to run.

How It Works

When a pull request is opened or updated, Athena runs a 6-phase pipeline:

Phase 1 — Orchestrator

Receives the webhook from GitHub, verifies the HMAC signature, creates a durable processing record in the database, and coordinates the remaining phases.

Phase 2 — Change Intelligence (CIS)

Classifies every changed file by category (source, test, config, docs, infra, migration, etc.) and determines the intent of the PR. Supported intents:

DOCS_ONLY — Only documentation files changed
TEST_ONLY — Only test files changed
FRONTEND_ONLY / BACKEND_ONLY — Single-domain changes
DATABASE_CHANGE — Migrations or schema changes
SECURITY_SENSITIVE_CHANGE — Auth, crypto, or permission changes
SHARED_MODULE_CHANGE — Core/shared code that affects multiple domains
INFRA_CHANGE / CI_WORKFLOW_CHANGE / DEPENDENCY_CHANGE
MIXED_CHANGE — Multiple categories affected

Phase 3 — CI Planning (CPRS)

Generates an execution plan based on the CIS report. Each of 14 possible CI jobs is classified as:

Required — Must run based on the changes
Optional — Recommended but not critical
Deferred — Can wait for a later stage
Skipped — Not affected by this PR

Phase 4 — CI Execution (CIES)

Dispatches the planned jobs via workflow_dispatch to your GitHub Actions workflow, or operates in dry-run mode showing exactly what would run.

Phase 5 — Validation & Feedback (VFS)

Analyzes CI execution results, detects failure patterns, computes per-module health scores, and identifies flaky test signals.

Phase 6 — Learning & Evolution (LES)

Converts validation feedback into autonomous routing adjustments. If a module keeps failing, Athena increases the validation floor for future PRs touching that module.

GitHub Checks

Athena creates multiple Check Runs on each PR, one per phase:

Check Name	Phase	Shows
Athena CI/CD Orchestrator	1	Pipeline status and pre-analysis summary
Athena Change Intelligence	2	Intent, confidence, impact level, affected domains
Athena CI/CD Execution Plan	3	Required/optional/skipped jobs with rationale
Athena CI/CD Execution	4	Dispatch status, workflow inputs, job list
Athena Validation & Feedback	5	CI outcomes, failure patterns, module health
Athena Learning & Evolution	6	Recommendations and autonomous adjustments

Configuration

Athena works with zero configuration, but you can customize behavior with environment variables on your hosting platform:

Variable	Default	Description
`ENABLE_WORKFLOW_DISPATCH`	`false`	Actually trigger GitHub Actions (vs dry-run)
`ENABLE_MANUAL_COMMANDS`	`false`	Enable `/athena` commands in PR comments
`ENABLE_INTRO_COMMENTS`	`false`	Post a welcome comment on new PRs
`ENABLE_LEARNING_CHECKS`	`true`	Create Phase 6 Check Run with learning output

Dynamic CI Workflow

To enable real CI execution, add the Athena dynamic workflow to your repository:

Copy athena-dynamic-ci.yml to .github/workflows/ in your repo
Replace the echo placeholders with your real CI commands
Set ENABLE_WORKFLOW_DISPATCH=true

Athena dispatches this workflow with a JSON list of jobs to run. Each job uses an if: contains(...) guard so only the relevant jobs execute.

Permissions Required

Athena requires these GitHub App permissions:

Checks: Write — to create and update Check Runs
Contents: Read — to read file lists and config files
Pull Requests: Write — to post comments (when enabled)
Metadata: Read — to access repository information
Actions: Write — to dispatch workflows (when enabled)
Statuses: Write — to set commit statuses

Data & Privacy

Athena processes webhook metadata (file names, SHAs, PR titles) to make routing decisions. It does not read or store your source code. See our Privacy Policy for full details.