Source control

GitHub integration

Ahena checks the GitHub repository your app is built and deployed from: visibility, default-branch protection, deployment environments, Actions variables, secret names, webhooks and Pages. It creates environments, sets variables, adds required checks and reviews through its own ruleset, and creates a webhook, each after you approve. Secret values never go through Ahena. GitHub isn't called by your app at runtime, so there's no generated code.

BetaFull GitHub docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at GitHub.

Repository visibility, default branch, whether it's archived, and whether GitHub Actions is enabled.
Environments with their protection rules and deployment branch policy.
Actions variables (repository and environment, with values) and secret names with their last update. Never secret values: GitHub doesn't return them.
Default-branch protection from rulesets at every level and classic branch protection: required status checks and approving reviews.
Webhooks (URL, events, active; never the webhook secret) and GitHub Pages status.

What Ahena configures

You declare what you want in ahena.config.ts; ahena plan shows each change with its classification before anything is applied.

Change	Classification	Notes
Create a GitHub environment	CONFIRMATION_REQUIRED	Only when it doesn't exist; protection rules are left for you to set in GitHub.
Set an Actions variable (repository or environment, production included)	CONFIRMATION_REQUIRED	The diff shows old and new values; variables not in `ahena.config.ts` are left alone.
Create or extend the ruleset `Ahena: default branch`	CONFIRMATION_REQUIRED	Adds required status checks and approving reviews; keeps every existing rule and never lowers anything.
Create the webhook	CONFIRMATION_REQUIRED	Idempotent by URL; a new signing secret is stored encrypted as `GITHUB_WEBHOOK_SECRET`.
Set an Actions secret	MANUAL	Doctor prints the `gh secret set` command; Ahena doesn't send secret values to GitHub.

Refused outright:

Changing repository visibility, or deleting, archiving, renaming or transferring the repository.
Deleting environments, variables, rulesets or webhooks.
Removing or lowering required checks or reviews, disabling a ruleset, or editing protection Ahena didn't create.
Changing environment protection rules or existing webhooks, and webhooks that skip TLS verification.
Actions variables whose names look like secrets.

Generated code: Nothing: GitHub isn't called by your app at runtime.

How Ahena verifies

After every write, Ahena reads GitHub back. Each change ends in one of these states, and the plan's outcome says why:

VERIFIED: Ahena read the provider back and saw the desired state. The CLI shows ✓ only for VERIFIED.
APPLIED_UNVERIFIED: The provider accepted the change, but the re-read doesn't show it yet (after bounded polling), or the re-read failed.

After applying, Ahena re-reads GitHub and re-plans: environments, variable values, the ruleset and the webhook must all be visible for the plan to come back empty.

Secrets are existence-only: GitHub never returns secret values, so Ahena confirms each declared name exists, not what it holds.

A ruleset edited after the plan was made is refused at apply rather than overwritten.

If a request may have reached GitHub but the answer was lost, Ahena re-reads before deciding: done, safe to retry, or “check before retrying”.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the GitHub docs.

Check	What it means
`github.token.expiration`	The token expires within 14 days (WARNING) or 3 days (FAIL).
`github.repository`	The repository is reachable with this token.
`github.protection`	Production declared: the default branch has protection.
`github.protection.checks`	Declared required checks and reviews are in force.
`github.environment`	The declared GitHub environment exists.
`github.variables`	Declared variables exist and match.
`github.secrets`	Declared secret names exist; `gh secret set` steps otherwise.
`github.webhook`	The webhook to the declared URL exists, is active and has the declared events.

More on findings, health and continuous checks: Doctor.

Approvals

GitHub changes here are classified CONFIRMATION_REQUIRED and MANUAL. Every change is planned and shown as a diff first. Ahena itself enforces who can approve it:

SAFE changes are applied without asking.
In production, every other change needs approval in the Ahena dashboard, signed in, by an admin.
In other environments, CONFIRMATION_REQUIRED changes are approved in the CLI; BILLABLE and DESTRUCTIVE changes always need the dashboard.
MANUAL steps are never applied by Ahena.

--yes and --allow-billable don't replace a dashboard approval. See approvals for how it works and why the browser.

Manual steps

These are MANUAL: Ahena never does them. It lists them with the exact steps when they apply.

Set secret values with gh secret set <NAME> --repo <owner>/<repo> (add --env <environment> for environment secrets). Doctor prints the commands.
Protect the production environment in GitHub: protected branches only and/or required reviewers.
For an organization's repository, an owner may need to approve the fine-grained token.

Credentials and permissions

Name	Secret	Notes
`GITHUB_TOKEN`	Yes	A fine-grained personal access token limited to this one repository (recommended). Classic tokens work but reach every repository you can.
`GITHUB_OWNER`	No	The user or organization that owns the repository; offered when you connect.
`GITHUB_REPO`	No	The repository name; offered when you connect.
`GITHUB_WEBHOOK_SECRET`	Yes	Created by Ahena with the webhook and stored encrypted in that environment.

Least privilege

Fine-grained token, this repository only: Metadata, Actions, Secrets and Pages read; Administration, Environments, Variables and Webhooks read and write (read-only for what you don't let Ahena change).
Read permissions are checked when you connect with reads that change nothing; write permissions can't be probed, so they show as unknown until an apply.
Ahena never needs Contents, Pull requests, Issues or Workflows permissions.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, plan, then apply. Placeholders (…) stand for your own values.

GITHUB_TOKEN=github_pat_… ahena connect github -e production --set GITHUB_OWNER=… --set GITHUB_REPO=…

Connect a fine-grained token for one repository.

```
ahena doctor -e production
```
Check protection, environments, variables, secret names and the webhook.
```
ahena plan -e production
```
See the environment, variable, ruleset and webhook changes.
```
ahena apply -e production
```
Approve in the dashboard; Ahena applies and re-reads GitHub.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How GitHub is tested

Tested against a simulated version of the GitHub REST API that follows its documented behaviour: 404 for repositories a token can't see, 403 with the needed permission, Link-header pagination and rate-limit headers.
Not yet verified against the real service. A live scenario is ready for a throwaway repository: it creates an environment, variables and a webhook, re-applies without duplicates, verifies by re-planning, and cleans up only what it made.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

Secret values are never read or set by Ahena; names are checked.
Rulesets on private repositories need GitHub Pro, Team or Enterprise.
Environment protection rules and existing webhooks are reported, not changed.
GitHub App installation tokens aren't supported.

Disconnecting

ahena disconnect github removes the stored token (delete it in GitHub's token settings); environments, variables, secrets, rulesets and webhooks stay in GitHub.