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.
Git App Expert
Route the work through 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 before adding deploy/flight behavior. The operator deploy brain in
scripts/ci/*.sh+.github/workflows/*.ymlis frozen — new control logic routes to the substrate (catalog/overlay/Argo/ESO) or into the typed.tsoperator control plane.DeployCapability(packages/ai-tools/src/capabilities/deploy.ts) is the sibling ofVcsCapability— sameCAPABILITY_INJECTION/ADAPTER_SWAPPABLEshape, adapter innodes/operator/app/src/adapters/server/. v0 is read-only over live Argo state and reusesdispatchCandidateFlightfor promotion (no second dispatch path; Argo stays the reconciler). When asked to add a flight/deploy feature, prefer aDeployCapabilitymethod 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.
| 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 |
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:
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:
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
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
Octokitinstance with that installation's token dispatchCandidateFlighthardcodesref: "main"— the workflow YAML must live on main forworkflow_dispatchto work; dispatching from a feature branch would fail
Adding workflowRef parameter (the planned feature):
- Add optional
workflowRef?: stringtoVcsFlightCandidateInputSchemainpackages/ai-tools/src/tools/vcs-flight-candidate.ts - Add optional
workflowRef?: stringtodispatchCandidateFlightparams inpackages/ai-tools/src/capabilities/vcs.ts - Change
ref: "main"→ref: params.workflowRef ?? "main"in the adapter - Update
vcs-flight-candidate.tstool description to document the parameter - 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.
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:
-
VcsCapability not configured →
GH_REVIEW_APP_IDorGH_REVIEW_APP_PRIVATE_KEY_BASE64not set in the node's environment. Check candidate-a GitHub environment secrets. -
403 / "Resource not accessible by integration" → GitHub App installation lacks
actions:write. Check: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.
-
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).
-
promoted_appsempty → 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. -
verify-buildshafails for operator → operator/versionreturns 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 -
verify-buildshafails 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 meanspromoted_appsoutput is wrong or the verify script isn't scoped correctly. -
wait-for-argocdtimes out → wrongEXPECTED_SHApassed (source SHA instead of deploy branch SHA), or Argo is out of sync with the deploy branch. SSH to VM and runkubectl get applicationset -n argocdto 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: 469k | 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: 469k | 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: 469k | 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 |