Zyeta Enterprise operations

Deployment runbook

The operator's document: how to stand this repository up in an organization, how to ship a release, how to deploy the website, and what to do when something goes wrong.

Work top to bottom the first time. After that, jump to Routine operations or Rollback.

Ownership. One named person owns this runbook and ticks the boxes. Owners are listed in ../governance/teams.yaml. If nobody owns it, it is not a control.

Evidence rule. A step is complete when there is a command output, a run link, or a screenshot recorded in the phase record — not when the setting looked right. Every phase ends with an Evidence line for exactly that reason.


Phase 0 — Preflight

Goal: know what you have before you change it. Owner: engineering lead. Time: 30 minutes.

0.1 Confirm the plan

SSO, SCIM, enterprise AI controls and audit streaming exist only on GitHub Enterprise Cloud. On Free or Team those toggles either do not appear or do nothing.

gh api orgs/<org> --jq '{plan: .plan.name, seats: .plan.filled_seats}'

If the answer is free or team, read ../governance/org.json .plan_requirements before promising anyone a control you cannot enable. A trial is available from the org's billing page.

0.2 Name the owners

Two or three, one of them the engineering lead. Owners can change everything, so the list stays short. Record them in teams.yaml → owners.

gh api orgs/<org>/members?role=admin --jq '.[].login'

0.3 Prepare the operator machine

gh auth status                                   # authenticated, with admin:org
gh auth refresh -s admin:org,repo,read:org       # add scopes if needed
command -v jq node npm                           # all required
npm ci && npm --prefix archify ci                # repository test dependencies

0.4 Pin the action SHAs

The security workflows ship with readable versions and a PIN-TODO marker. CI fails until they are pinned (security / action pins).

enterprise/governance/pin-actions.sh --dry-run
enterprise/governance/pin-actions.sh
git diff --stat .github/workflows

0.5 Take a baseline

enterprise/governance/verify.sh --org <org> --repo <org>/archify --report baseline.md || true

Keep baseline.md. It is what "drift" is measured against on day 30.

Evidence: plan name, owner list, baseline.md, pinned-SHA diff.


Phase 1 — Foundation

Goal: lock the doors before anyone moves in. Owner: security lead. Time: 45 minutes.

1.1 Apply the org settings

enterprise/governance/apply.sh --org <org> --scope org --dry-run   # read the requests
enterprise/governance/apply.sh --org <org> --scope org

This sets: default repository permission none, private-repo creation only, forking of private repositories off, member-created Pages off, mandatory 2FA, sign-off on web commits, and scanning defaults for new repositories.

1.2 Warn people before 2FA is enforced

Anyone without 2FA is removed from the org when the setting turns on. Announce it a few days ahead, then confirm:

gh api orgs/<org> --jq .two_factor_requirement_enabled   # true

1.3 UI-only member privileges

These are in org.json → .manual because the REST API does not expose them on every plan. Do them by hand: Org Settings → Member privileges.

1.4 Verified domain and profile

Verify:

enterprise/governance/verify.sh --org <org> --repo <org>/archify | sed -n '/Organization/,/Team access/p'

Rollback: re-run apply.sh with the previous org.json, or set the two or three changed fields by hand. Nothing in this phase is destructive.

Evidence: verify.sh output for the Organization section, screenshot of Member privileges, domain verification badge.


Phase 2 — Teams and repository standards

Goal: access flows through teams, never through individual people. Owner: platform lead. Time: 30 minutes.

2.1 Create the teams

enterprise/governance/apply.sh --org <org> --scope org

Creates org-admins, engineering (parent), platform, security, ai-agents, then sets each team's permission on this repository:

TeamPermission on archifyHolds
org-adminsadmin2–3 owners
engineeringreadeveryone in engineering, via sub-teams
platformmaintainCI, deploys, environment approvals
securitywritealert triage, security review — write, because approval requires write
ai-agentswriteno people — GitHub App installations only

Role semantics, personas and the traps that cost an afternoon each: team-access.md. The one line to remember: a read member can comment on a pull request but their approval does not satisfy the ruleset.

2.2 Add people to teams, not repositories

gh api -X PUT orgs/<org>/teams/<slug>/memberships/<login> -f role=member

Never add a person to a repository directly. When they leave a team, their access to every repository that team can see disappears with it.

2.3 Repository standards

Verify:

gh api orgs/<org>/teams --jq '.[].slug'
gh api orgs/<org>/teams/ai-agents/repos/<org>/<repo> --jq .permission   # write
gh api orgs/<org>/teams/ai-agents/members --jq 'length'                  # 0

Rollback: delete a team with gh api -X DELETE orgs/<org>/teams/<slug>. Doing so removes its access, so check nothing depends on it first.

Evidence: team list, ai-agents permission and empty member list.


Phase 3 — Protect the main branch

Goal: nothing reaches main without a pull request and a human approval. Owner: platform lead. Time: 30 minutes. Do not skip.

3.0 The ordering constraint

Apply this phase after ci.yml and security.yml have run at least once on the default branch. A required context that has never reported leaves every pull request pending forever.

# Has CI run on main yet?
gh run list --branch main --limit 5
# Which check names actually exist?
gh api "repos/<org>/<repo>/commits/main/check-runs?per_page=100" --jq '[.check_runs[].name] | unique'

Compare that list with required_status_checks in ../governance/rulesets/protect-main.json. If a context is missing, fix the job name in the workflow or remove the context from the file. Do not remove it to "get unblocked" without recording why.

3.1 Apply the rulesets

enterprise/governance/apply.sh --org <org> --scope org
enterprise/governance/apply.sh --org <org> --scope org --verify-checks

protect-main gives you:

protect-release-tags makes v* tags immutable and restricts creation to org admins, because a moved tag is a forged release.

3.2 Raise the approval count where it matters

Payment, auth and infra repositories get 2 approvals. For this repository, 1 is the floor; raise required_approving_review_count in protect-main.json and re-apply if the risk changes.

3.3 CODEOWNERS

.github/CODEOWNERS already names the owner for .github/** and enterprise/**. Those paths cannot be changed without a Code Owner's approval, which is how path-level write restriction is expressed — GitHub rulesets cannot match file paths.

Verify:

enterprise/governance/verify.sh --org <org> --repo <org>/archify | sed -n '/Rulesets/,/Environments/p'

Rollback: set enforcement to disabled in the ruleset JSON and re-apply, or delete the ruleset in the UI. evaluate (log-only) is a GitHub Enterprise feature and does not exist on Team. Do not remove the bypass actor as a "fix" — that is the control.

Evidence: verify.sh Rulesets section showing active and the exact context list, plus one real pull request that was blocked by the ruleset.


Phase 4 — Security scanning and secrets

Goal: every scanner on, and a password never enters the repository. Owner: security lead. Time: 45 minutes.

4.1 Repository-level scanning

enterprise/governance/apply.sh --org <org> --scope repo

Turns on secret scanning, push protection, non-provider patterns, validity checks, and private vulnerability reporting.

On private repositories these need Secret Protection and Code Security. The API returns 200 even when the feature is inactive on your plan, so read the response body, do not trust the status code:

gh api repos/<org>/<repo> --jq .security_and_analysis

4.2 Code scanning

security.yml runs CodeQL on every pull request from this repository, on every push to main/dev, and weekly. Fork PRs are analysed post-merge because GitHub does not grant security-events: write to fork workflows — the code_scanning rule in the ruleset still blocks a merge on a high-severity alert.

Alternatively, use default setup (Settings → Code security) and delete the codeql job. Pick one. Running both produces duplicate alerts and confusing counts.

4.3 Dependency updates

.github/dependabot.yml covers all three package roots plus Actions, grouped and weekly. Dependabot alerts alone do not patch anything; the update PRs are the patching mechanism.

gh api repos/<org>/<repo>/vulnerability-alerts -i | head -1     # 204 = on

4.4 Who reviews alerts

The security team, weekly, in a recorded slot. See Day-2 calendar.

Verify:

enterprise/governance/verify.sh --org <org> --repo <org>/archify | sed -n '/Repository settings/,$p'
gh api repos/<org>/<repo>/code-scanning/analyses --jq '.[0] | {tool, created_at}'

Rollback: disable a scanner in the UI. Push protection is the last one to turn off — with agents writing code, it matters more, not less.

Evidence: security_and_analysis output, first CodeQL analysis link, first Dependabot PR.


Phase 5 — Automation and deploys

Goal: lock down what Actions can run and who can ship. Owner: platform lead. Time: 60 minutes.

5.1 Org Actions policy

Org Settings → Actions → General (UI; record a screenshot):

Confirm the default from the API:

gh api orgs/<org>/actions/permissions/workflow --jq '{default: .default_workflow_permissions, can_approve_prs: .can_approve_pull_request_reviews}'

Every workflow in this repository already declares a top-level permissions: contents: read, so the org default is a second layer, not the only one.

5.2 Environments

enterprise/governance/apply.sh --org <org> --scope repo
EnvironmentProtectionUsed by
productionplatform reviewer, no self-review, tag v* + branch mainrelease.yml
cloudflare-pagesplatform reviewer, branch mainci.yml deploy-cloudflare
github-pagesbranch main onlyci.yml deploy-pages
previewnone (non-production)preview.yml
[object Object]

5.3 Secrets and variables

Names and owners are in ../governance/secrets-inventory.yaml. Values are set by hand and never committed.

# Cloudflare (production + preview environments)
gh secret set CLOUDFLARE_API_TOKEN --env cloudflare-pages
gh secret set CLOUDFLARE_API_TOKEN --env preview
gh variable set CLOUDFLARE_PAGES_PROJECT --body archify-site
gh variable set CLOUDFLARE_ACCOUNT_ID --body <32-hex-account-id>

# Governance drift (read-only org administration)
gh secret set GOVERNANCE_TOKEN
gh variable set GOVERNANCE_ORG --body <org>

CLOUDFLARE_PAGES_PROJECT empty means both Cloudflare jobs skip. That is the intended way to run without Cloudflare.

5.4 Required checks

Already applied in Phase 3. If you added or renamed a job, update protect-main.json and re-apply, then run --verify-checks.

5.5 First full run

gh workflow run ci.yml
gh run watch
gh workflow run security.yml
gh run watch

Expect security / action pins to fail until Phase 0.4 is committed.

Verify:

gh api repos/<org>/<repo>/environments --jq '.environments[] | {name, rules: [.protection_rules[].type]}'
gh secret list --env cloudflare-pages

Rollback: an environment with no reviewer is inert, not dangerous — remove the reviewer requirement rather than the environment if a release is stuck, and restore it immediately after.

Evidence: Actions policy screenshot, environment list with protection rules, secret names (never values), first green ci.yml and security.yml run links.


Phase 6 — AI agents

Goal: agents get their own identity, the smallest access that works, and no power to merge. Owner: AI lead. Time: 45 minutes, then a one-month pilot.

6.1 Enterprise AI controls (Enterprise Cloud)

Enterprise Settings → AI controls:

6.2 Guardrails

6.3 Register before installing

Add the entry to ../governance/agent-register.yaml first: name, human owner, repos, permissions, approval date, review date. Then follow agent-governance.md to create the app and install it on selected repositories only.

6.4 Approved custom agents

Define them once in a .github-private repository, and add a ruleset so only org-admins can change files under agents/ and .github/agents/.

Verify:

gh api orgs/<org>/installations --jq '.[] | {app: .app_slug, selection: .repository_selection}'
gh api orgs/<org>/teams/ai-agents/repos/<org>/<repo> --jq .permission   # write, never admin

Rollback: uninstall the app (gh api -X DELETE orgs/<org>/installations/<id>). That revokes every token it holds, immediately. Update the register in the same change.

Evidence: AI controls screenshots, installation list, register entry, one agent-authored pull request that required a human approval to merge.


Phase 7 — Oversight and spending

Goal: answer "who or what changed this, and what did it cost" at any time. Owner: engineering lead + security lead. Time: 30 minutes, then recurring.

7.1 Spending limits

Billing → spending limits: set a cap for Actions, Copilot and each paid security product. Agents burn usage fast; a cap converts an incident into a notification.

7.2 Audit log

The audit log UI is included in Team. The audit log API is not: gh api orgs/<org>/audit-log returns 404 on Team and needs Enterprise. Review in the UI, and export by hand if a record is needed:

# Enterprise only — expect 404 on Team
gh api "orgs/<org>/audit-log?per_page=100&phrase=action:repo.change_merge_setting" --jq '.[] | {actor, action, created_at}'

7.3 Drift

governance.yml runs verify.sh daily and on any change under enterprise/governance/. A red run is a real finding, not noise: either the live state drifted or the desired state in this repository is stale.

7.4 Recurring reviews

See Day-2 calendar.

Evidence: spending-limit screenshot, first monthly audit review entry, first green governance / drift run.


Phase 8 — Company login (later)

Do this when the company adopts Google Workspace, Microsoft Entra or Okta, and the org is on Enterprise Cloud.

Until then, personal GitHub accounts with mandatory 2FA are acceptable. Record the decision and its date so it does not silently become permanent.


Routine operations

Cut a release

  1. Prepare the version. Bump archify/package.json and archify/skill-release.json; update CHANGELOG.md; rebuild the archive.

``sh scripts/build-zip.sh archify.zip npm run test:full ``

  1. Land it through the normal path. Pull request to dev, then a promotion PR dev → main that records the tested revision, the real-task evidence, and any unresolved issue. CI is not trial-use acceptance.
  1. Tag. Stable releases need an annotated tag, and the tag must match archify/package.json:

``sh git tag -a v3.3.0 -m "archify 3.3.0" git push origin v3.3.0 ``

  1. Approve the production gate. release.yml waits on the production environment. A platform reviewer — not the person who pushed the tag — approves:

``sh gh run list --workflow release.yml --limit 1 gh api repos/<org>/<repo>/actions/runs/<run_id>/pending_deployments \ --jq '.[] | {environment: .environment.name, id}' gh api -X POST repos/<org>/<repo>/actions/runs/<run_id>/pending_deployments \ -F environment_ids[]=<environment_id> -f state=approved -f comment="Release v3.3.0 approved" ``

The job then re-runs the full suite, checks the archive is deterministic, and publishes the Release with archify.zip attached.

  1. Publish the update manifest in a follow-up commit. stable.json must point at the Release that now exists. The published-update-manifest gate verifies the asset, the tagged archive and the digest before the site deploys — that is why the manifest is a separate commit and not part of the tag.
  1. Confirm provenance. provenance.yml runs on release: published and attaches SHA256SUMS.txt and a CycloneDX SBOM:

``sh gh release view v3.3.0 --json assets --jq '.assets[].name' gh attestation verify archify.zip --repo <org>/archify ``

  1. Public acceptance. Install from the advertised path in an isolated environment and confirm the version users actually get. Only then is the channel complete.

Deploy the website

Automatic. A push to main deploys GitHub Pages after every required gate, and Cloudflare Pages if CLOUDFLARE_PAGES_PROJECT is set. Both jobs re-check that main still points at the commit they built, and skip themselves as obsolete if it does not.

gh run list --workflow ci.yml --branch main --limit 3
gh api repos/<org>/<repo>/deployments --jq '.[0:5][] | {environment, ref, created_at}'

Preview a website change

Automatic for a same-repo pull request touching website/**. The URL is posted as a comment marked <!-- archify-preview -->, updated in place on each push. Fork PRs are skipped by design.

Hotfix

A production defect does not change the rules; it changes the urgency.

  1. Branch from main, fix, open a pull request.
  2. One approval is still required. The bypass list is for emergencies only and using it requires a written record in the incident.
  3. Tag a patch release and follow Cut a release from step 3.

Rollback

Roll back a release

Tags are immutable, so a bad release is superseded, never rewritten.

SymptomAction
Broken install for usersPublish a patch release with the fix. This is the only path that reaches users who already updated.
Release published by mistakegh release edit v3.3.0 --prerelease (removes it from "latest"), then publish the correct version.
Notifier offering a bad versionRevert the stable.json commit on main. The gated deploy re-verifies and republishes the site; the notifier stops offering it after that deploy.
Provenance or asset mismatchTreat as an incident, not a rollback: the published bytes do not match the tag. See Incident response.

Roll back the website

  1. git revert <commit> on main through a pull request (the ruleset still applies).
  2. The merge triggers a fresh deploy of the reverted build.
  3. Confirm the live page and the deployment record.

Re-running an old successful deploy run does not work: the obsolete-run guard compares main HEAD with the run's SHA and skips itself. That guard exists so a stale build cannot overwrite a newer one. Use a revert.

Roll back a configuration change

git checkout <previous-commit> -- enterprise/governance/
enterprise/governance/apply.sh --org <org> --dry-run
enterprise/governance/apply.sh --org <org>

Configuration is data. Rolling it back is a diff and a re-apply, not a UI archaeology exercise.


Incident response

SeverityExampleResponse
SEV1Published archive does not match its tag; a secret was pushed; an agent merged codeContain within 15 minutes, notify owners, rotate credentials
SEV2Required check permanently red; deploy blocked; drift persists after re-applyFix within a business day
SEV3A single scanner noisy; a docs build flakyNext scheduled review

Contain

# Stop all workflows in the repository.
gh api -X PUT repos/<org>/<repo>/actions/permissions -F enabled=false

# Revoke a leaked token or a compromised agent.
gh api -X DELETE orgs/<org>/installations/<installation_id>

# Rotate a deploy credential.
gh secret set CLOUDFLARE_API_TOKEN --env cloudflare-pages

Preserve evidence

# Audit log API is Enterprise-only; on Team export from Org Settings → Logs instead.
gh api "orgs/<org>/audit-log?per_page=100" > incident/audit-$(date -u +%Y%m%dT%H%M).json || \
  echo 'audit-log API unavailable on this plan: capture the UI export by hand' >&2
gh run list --limit 50 --json databaseId,workflowName,conclusion,headSha,createdAt > incident/runs.json
gh release view <tag> --json assets,createdAt > incident/release.json

Do not delete a bad release or a workflow run before this is captured. Deleting the evidence is how a small problem becomes an unattributable one.

Recover

  1. Rotate every credential the actor could read. Rotate first, investigate second.
  2. Fix forward through the normal pull-request path.
  3. Re-enable Actions only after the fix is merged.
  4. Write the record: timeline, root cause, the control that should have caught it, and the change to enterprise/governance/ that closes it. If no file changes, the incident is not closed.

Day-2 calendar

CadenceTaskOwnerWhere
Dailygovernance / drift resultplatformActions
WeeklyAlert triage: CodeQL, secret scanning, DependabotsecuritySecurity tab
WeeklyDependabot PRs reviewed and mergedplatformPull requests
MonthlyAudit log reviewsecurityOrg Settings → Logs
MonthlySpend against limitseng leadBilling
QuarterlyTeam membership reviewsecuritygh api orgs/<org>/teams/<slug>/members
QuarterlyAgent register review; remove unused appsAI leadagent-register.yaml
QuarterlyRuleset review: approvals, contexts, bypass listplatformrulesets/*.json
Per releaseRelease checklist and public acceptanceplatformCONTRIBUTING.md

Offboarding a person

Same day, in this order:

  1. gh api -X DELETE orgs/<org>/members/<login>
  2. Remove from every team; confirm no direct repository collaborator remains
  3. Revoke personal access tokens and SSH keys
  4. Rotate every shared secret they could read (secrets-inventory.yaml says which)
  5. Transfer ownership of any app, environment or release they owned
  6. Record the date in the access review log

Step 4 is the one that gets skipped. A leaver who could read CLOUDFLARE_API_TOKEN is a reason to rotate it, not a reason to hope.


When a gate is red

CheckLikely causeAction
security / action pinsA PIN-TODO marker is still in a workflowenterprise/governance/pin-actions.sh, commit, re-run
scopeThe diff cannot be classifiedCheck scripts/ci-scope.mjs; full coverage is the safe default, so investigate rather than widen
zip-freshnessarchify.zip is stalescripts/build-zip.sh archify.zip, commit the result
published-update-manifeststable.json points at a version with no Release, or a mismatched assetPublish the Release first; the manifest is a follow-up commit
test (18/20/24)A runtime-specific API was usedFix the code; do not drop a runtime from the matrix
Windows test portabilityA path assumption that only holds on POSIXUse the portable path helpers under archify/renderers/shared/
security / codeqlA genuine finding, or a fork PRFork PRs are expected to skip; a same-repo finding is a real alert
governance / driftLive state changed outside this repository, or desired state is staleverify.sh names the field; decide which side is right, then fix that side
Release job waitingproduction environment approvalA platform reviewer approves; the tag pusher cannot self-approve

Appendix A — Command reference

# Apply and verify
enterprise/governance/apply.sh --org <org> --repo <org>/archify --dry-run
enterprise/governance/apply.sh --org <org> --repo <org>/archify
enterprise/governance/verify.sh --org <org> --repo <org>/archify --report drift.md
enterprise/governance/pin-actions.sh

# Access
gh api orgs/<org>/members?role=admin --jq '.[].login'
gh api orgs/<org>/teams --jq '.[].slug'
gh api orgs/<org>/teams/ai-agents/members --jq 'length'

# Protection
gh api orgs/<org>/rulesets --jq '.[] | {name, target, enforcement}'
gh api orgs/<org>/rulesets/<id> --jq '.rules[].type'
gh api repos/<org>/<repo>/environments --jq '.environments[].name'

# Scanning
gh api repos/<org>/<repo> --jq .security_and_analysis
gh api repos/<org>/<repo>/code-scanning/analyses --jq '.[0]'

# Release
gh run list --workflow release.yml --limit 5
gh release view <tag> --json assets --jq '.assets[].name'
gh attestation verify archify.zip --repo <org>/archify

Appendix B — Phase record template

## Phase <n> — <name>
Date:            <YYYY-MM-DD>
Operator:        <name>
Plan:            Free | Team | Enterprise Cloud
Applied by:      apply.sh <scope> | UI | both
Verify output:   <link or inline>
Evidence:        <links, screenshots, run ids>
Deviations:      <what was skipped and why, with owner and follow-up>
Rollback tested: yes | no

A phase with an empty Deviations line is either genuinely complete or unexamined. Say which.

Appendix C — Decision log

Record decisions that will otherwise be relitigated:

DecisionDateOwnerRationale
Auto-merge disabled repository-wide2026-11-03platformNo unattended merge path for a bot or agent
CodeQL required via ruleset rule, not a required check2026-11-03securityFork PRs cannot upload results; the rule blocks regardless of author
1 approval on archify, 2 on payment/auth/infra repos2026-11-03eng leadSingle-maintainer repository; revisit when the team grows
Personal accounts + 2FA until an IdP exists2026-11-03eng leadNo company login system yet; EMU decided before the team grows
Preview deployments hold the Cloudflare token2026-11-03platformEnvironment separation prevents fork access; revisit at 5+ contributors