cogni-dao/cogni / .claude/skills/git-app-expert
git-app-expert
VerifiedGitHub App + VCS operations expert for the cogni-template stack. Load this skill when working on anything involving: GitHub App permissions or installation auditing (cogni-node-template, cogni-git-review), VCS tool layer changes (VcsCapability interface, GitHubVcsAdapter, vcs-flight-candidate tool schema), operator flight dispatch debugging (workflow_dispatch permissions, Argo sync, buildSha verify), or wiring VCS flight dispatch end-to-end. Use proactively whenever the user mentions "flight", "flight dispatch", "workflow permissions", "GH_REVIEW_APP", "VcsCapability not configured", "actions:write", or asks to add a workflowRef / VCS tool parameter.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.7 KB |
| evals/evals.json | config | 2.1 KB |
SKILL.md
View on GitHub---
name: git-app-expert
description: >
GitHub App + VCS operations expert for the cogni-template stack. Load this
skill when working on anything involving: GitHub App permissions or installation
auditing (cogni-node-template, cogni-git-review), VCS tool layer changes
(VcsCapability interface, GitHubVcsAdapter, vcs-flight-candidate tool schema),
operator flight dispatch debugging (workflow_dispatch permissions,
Argo sync, buildSha verify), or
wiring VCS flight dispatch end-to-end. Use proactively whenever the user
mentions "flight", "flight dispatch", "workflow permissions", "GH_REVIEW_APP",
"VcsCapability not configured", "actions:write", or asks to add a workflowRef /
VCS tool parameter.
---
# Git App Expert
Route the work through [operator-architect](https://cognidao.org/knowledge/operator-architect) first; this skill adds the GitHub App and VCS rules on top of it.
You are the expert on Cogni's GitHub App integration, VCS tool layer, and candidate-a
flight pipeline. Your job is to audit, debug, and implement — from the GitHub org
installation level down to the tool schema and CI scripts.
> **Boundary first.** Read [CI/CD Platform Boundary & Freeze Policy](https://cognidao.org/knowledge/operator-plane-contract) before adding deploy/flight behavior. The operator deploy brain in `scripts/ci/*.sh` + `.github/workflows/*.yml` is **frozen** — new control logic routes to the substrate (catalog/overlay/Argo/ESO) or into the typed `.ts` operator control plane. `DeployCapability` (`packages/ai-tools/src/capabilities/deploy.ts`) is the **sibling of `VcsCapability`** — same `CAPABILITY_INJECTION`/`ADAPTER_SWAPPABLE` shape, adapter in `nodes/operator/app/src/adapters/server/`. v0 is read-only over live Argo state and reuses `dispatchCandidateFlight` for promotion (no second dispatch path; Argo stays the reconciler). When asked to add a flight/deploy feature, prefer a `DeployCapability` method over a new workflow input or a new `.sh`.
## GitHub Apps on Cogni-DAO Org
**One App per environment** — each App has exactly one webhook URL, so prod/preview/candidate-a
cannot share one. Create + wire per the canonical guide:
[`https://cognidao.org/knowledge/github-app-per-environment`](https://cognidao.org/knowledge/github-app-per-environment).
| App | ID | Install ID | env | webhooks → / installed on |
| -------------------------- | ------- | ---------- | ---------------- | ---------------------------------------------------------------------- |
| `cogni-operator-test` | 3956976 | 138046799 | candidate-a/test | `test.cognidao.org/...webhooks/github` · all repos on `cogni-test-org` |
| `cogni-operator` | 2994706 | 113665458 | production ops | `cognidao.org/...webhooks/github` · all repos on `Cogni-DAO` |
| `cogni-node-template` | 3062001 | 115515535 | legacy/vcs | selected repos; use only if the env's `GH_REVIEW_APP_ID` is `3062001` |
| `cogni-git-review` | 1761205 | 80293097 | production | `cognidao.org/...webhooks/github` · `Cogni-DAO/cogni` |
| `cogni-git-review-preview` | 2011345 | 87655574 | preview | `preview.cognidao.org/...webhooks/github` · selected preview repos |
**Node AI push tokens come from the operator App, narrowed.** `POST /api/v1/vcs/push-token` mints a 1-hour
installation token from the env's operator App (`GH_REVIEW_APP_*`) for ONE node repo with Contents and Pull requests
write only, gated on `node.flight` (`developer`). GitHub shows those pushes as the operator App; the route's terminal
log names the requesting principal and the node records its run. Design:
[node-ai-code-identity](https://node-template.cognidao.org/knowledge/node-ai-code-identity).
`Cogni-DAO/test-repo` is only a legacy review-webhook fixture. It is not
sufficient for node publish/flight testing: the candidate/test App must see the
template repo, parent pin repo, and freshly minted node repos in the disposable
GitHub org (`cogni-test-org`) without gaining access to production `Cogni-DAO`
repos. Pair this with `DOLTHUB_OWNER=cogni-test-nodes` for node knowledge repos.
**Where the App creds live (post-ESO migration, #1460/#1476):** the running operator pod reads
`GH_REVIEW_APP_ID` / `GH_REVIEW_APP_PRIVATE_KEY_BASE64` / `GH_WEBHOOK_SECRET` from **OpenBao**
`cogni/<env>/operator/*` (ESO → `operator-env-secrets` → `envFrom`) — **NOT** the GitHub env secret
directly. The GitHub env secret is only a provision-time seed; for a **live** env, write to OpenBao
via `pnpm secrets:set <env> operator GH_REVIEW_APP_*` + bounce the pod (Reloader isn't cluster-wide
yet). See the webhook-setup guide §"Deployed envs".
**Split-brain auth (`bug.5000`, open):** App auth is duplicated across **three** adapters —
`adapters/server/review/github-auth.ts` (webhook plane, payload-driven per-repo),
`adapters/server/vcs/github-vcs.adapter.ts` (flight + approve-checks, historically hardcoded to
`Cogni-DAO/cogni` via `getGithubRepo()`), and `scheduler-worker/.../ingestion/github-auth.ts`. They
diverge: review works repo-agnostically (why `preview-test-repo` PRs review) while VCS tools stub on
candidate-a if `GH_REVIEW_APP_ID` is empty or the repo is hardcoded. Desired end state = one shared
`github-core` primitive + capability-scoped per-repo token provider. Until then, configuring a new
env means setting all three planes' creds + matching the webhook secret on both the App and the pod
(the dual-plane class — see also dev2's webhook-secret-sync work).
**Permission audit**: to check live installation permissions:
```bash
gh api "orgs/Cogni-DAO/installations?per_page=20" | \
jq '.installations[] | select(.app_id == 2994706) | {app_slug, id, repository_selection, permissions}'
gh api "orgs/cogni-test-org/installations?per_page=20" | \
jq '.installations[] | select(.app_id == 3956976) | {app_slug, id, repository_selection, permissions}'
```
Operator mint/flight Apps require `actions:write`, `administration:write`, `contents:write`,
`workflows:write`, and `packages:write`. Package write reserves operator authority for future
package policy/visibility management; node-ref flight must not treat GitHub Packages metadata reads
as the deploy gate because private package metadata can false-negative even when the child image
exists. Do not add a PAT to child node repos for publishing: child workflows publish with their
repo-local `GITHUB_TOKEN` and `permissions.packages: write`. The operator flight and k3s image
pulls (operator only) are separate cross-repo read paths and still need either public packages, package Actions
access grants, or the existing `GHCR_DEPLOY_TOKEN`/registry credential path with `read:packages`.
If the installation lacks a newly requested permission, the org admin must approve the pending
permission upgrade at the installation URL:
```text
https://github.com/organizations/cogni-test-org/settings/installations/138046799
https://github.com/organizations/Cogni-DAO/settings/installations/113665458
```
The legacy `cogni-node-template` installation approval URL is
`https://github.com/organizations/Cogni-DAO/settings/installations/115515535`.
**Common gotcha**: the GitHub App _definition_ can request `actions:write` while the org
_installation_ still shows `read` — they diverge when the org hasn't accepted the expanded
permissions yet. Always check the installation, not the app definition.
## VCS Capability Layer
The VCS capability follows the hexagonal pattern: interface → adapter → bootstrap injection.
```
packages/ai-tools/src/capabilities/vcs.ts ← interface (VcsCapability)
packages/ai-tools/src/tools/vcs-*.ts ← AI tool schemas (5 tools)
nodes/operator/app/src/adapters/server/vcs/
github-vcs.adapter.ts ← GitHubVcsAdapter (Octokit + App auth)
nodes/operator/app/src/bootstrap/capabilities/
vcs.ts ← factory (reads env vars, returns adapter or stub)
nodes/operator/app/src/bootstrap/ai/
tool-bindings.ts ← wires VcsCapability into tool implementations
```
**Only the operator node has a real VcsCapability.** All other nodes (
`node-template`) export `stubVcsCapability` — it satisfies the binding requirement but throws
on use: `"VcsCapability not configured on this node."` This is intentional — VCS operations
live on the operator node.
### VcsCapability interface methods
```typescript
listPrs({ owner, repo, state? }) → PrSummary[]
getCiStatus({ owner, repo, prNumber }) → CiStatusResult // allGreen, pending, checks[]
mergePr({ owner, repo, prNumber, method }) → MergeResult
createBranch({ owner, repo, branch, fromRef }) → CreateBranchResult
dispatchCandidateFlight({ owner, repo, prNumber, headSha? }) → DispatchCandidateFlightResult
```
`CiStatusResult.allGreen` is the VCS flight gate: `true` only when all checks are `success`
and none are `pending`.
### GitHubVcsAdapter
`nodes/operator/app/src/adapters/server/vcs/github-vcs.adapter.ts`
Key design points:
- Constructed with `{ appId, privateKey }` — no installation ID at construction time
- `resolveInstallationId(owner, repo)` fetches and caches the installation ID per repo
- Each API call gets a fresh `Octokit` instance with that installation's token
- `dispatchCandidateFlight` hardcodes `ref: "main"` — the workflow YAML must live on main for
`workflow_dispatch` to work; dispatching from a feature branch would fail
**Adding `workflowRef` parameter** (the planned feature):
1. Add optional `workflowRef?: string` to `VcsFlightCandidateInputSchema` in
`packages/ai-tools/src/tools/vcs-flight-candidate.ts`
2. Add optional `workflowRef?: string` to `dispatchCandidateFlight` params in
`packages/ai-tools/src/capabilities/vcs.ts`
3. Change `ref: "main"` → `ref: params.workflowRef ?? "main"` in the adapter
4. Update `vcs-flight-candidate.ts` tool description to document the parameter
5. Run `pnpm typecheck` — TypeScript will catch any missed call sites
Use case: flight PR #1004 using PR #1003's workflow branch so the CI fix in #1003 is tested
while validating #1004's app build.
### AI tool contracts
```
core__vcs_list_prs — read_only — lists open PRs
core__vcs_get_ci_status — read_only — full CI state for one PR
core__vcs_merge_pr — state_change — squash/merge/rebase into staging
core__vcs_create_branch — state_change — naming: agent/<work-item-id>/<desc>
core__vcs_flight_candidate — state_change — operator flight (POST /api/v1/vcs/flight)
```
**NO_AUTO_FLIGHT invariant**: `core__vcs_flight_candidate` must only be called when a human
or scheduled run explicitly requests it. Enforced via tool description —
not in code. The tool description repeats this to the planner.
## Operator flight anatomy (operator only)
`.github/workflows/candidate-flight.yml` flights an operator PR to its candidate. It is dispatched by `POST /api/v1/vcs/flight`, never by a personal `gh` credential. Per-`(env, target)` workflow concurrency serializes mutation. It is not a reviewer reservation, and the old slot-lease file is retired.
A node PR does not use this workflow. A node PR ships with `POST /api/v1/deploy/workloads {nodeId, env:"candidate-a", workload, sourceSha}`. Read [cicd-e2e-required-sequence](https://cognidao.org/knowledge/cicd-e2e-required-sequence).
Verify an operator flight by `/version.buildSha` on the candidate host. A flight whose `promoted_apps` is empty must show verify as skipped, not green. A PR with promoted apps and a skipped verify is a contradiction and fails.
## Flight Debugging Checklist
When a flight fails or dispatch errors, work through this in order:
1. **VcsCapability not configured** → `GH_REVIEW_APP_ID` or `GH_REVIEW_APP_PRIVATE_KEY_BASE64`
not set in the node's environment. Check candidate-a GitHub environment secrets.
2. **403 / "Resource not accessible by integration"** → GitHub App installation lacks
`actions:write`. Check:
```bash
gh api "orgs/Cogni-DAO/installations?per_page=20" | \
jq '.installations[] | select(.app_id == 3062001) | .permissions.actions'
```
Fix: approve permission upgrade at GitHub org settings for installation 115515535.
3. **Slot busy** → another flight holds the lease. Check lease file (command above). If the
run that owns it is no longer active, the lease will expire after TTL (60 min default).
4. **`promoted_apps` empty** → PR Build CI built no images (CI-only PR, or affected-only
scope missed a node). Nothing to verify — flight is a no-op no-error skip.
5. **`verify-buildsha` fails for operator** → operator `/version` returns HTML (404). This is
a pod health or ingress routing issue on the candidate-a VM, not a code problem.
Check: `curl -s https://test.cognidao.org/version`
6. **`verify-buildsha` fails for a node the PR never touched** → that node's images weren't
promoted in this flight, but the verify script is checking it anyway. This means
`promoted_apps` output is wrong or the verify script isn't scoped correctly.
7. **`wait-for-argocd` times out** → wrong `EXPECTED_SHA` passed (source SHA instead of
deploy branch SHA), or Argo is out of sync with the deploy branch. SSH to VM and run
`kubectl get applicationset -n argocd` to check sync state.
## Environment Variables Reference
| Var | Where set | Purpose |
| ---------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------- |
| `GH_REVIEW_APP_ID` | **OpenBao** `cogni/<env>/operator/*` (ESO); GH env secret is provision seed only | GitHub App ID for VcsCapability |
| `GH_REVIEW_APP_PRIVATE_KEY_BASE64` | **OpenBao** `cogni/<env>/operator/*` (ESO); GH env secret is provision seed only | Base64-encoded PEM private key |
| `GH_WEBHOOK_SECRET` | **OpenBao** `cogni/<env>/operator/*` (ESO); must MATCH the App's webhook-secret field | Webhook signature verification |
| `GH_REPOS` | candidate-a + production GitHub env **vars** (config, not secret) | VCS repo scope (review is payload-driven) |
| `DOMAIN` | candidate-a env var: `test.cognidao.org` | Used in smoke + buildSha verify |
| `VM_HOST` | candidate-a GitHub env secret | SSH target for Argo reconcile |
| `SSH_DEPLOY_KEY` | candidate-a GitHub env secret | SSH key for VM access |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |