Skip to main content

GitHub Actions governance for the connected core

Decision​

GitHub Actions is the estate's continuous verification and bounded publication layer.

It is not:

  • the source of architectural truth;
  • a substitute for local development;
  • a hidden cross-repository orchestrator;
  • the canonical store for research or data artifacts;
  • a place where scheduled jobs silently mutate main.

The repository-local SYSTEM.yaml remains authoritative for repository boundaries. This document and estate/ci-governance.yaml define how those boundaries may be exercised by GitHub Actions.

Evidence basis​

The first readiness scan observed 25 repositories across six components. Every repository had SYSTEM.yaml, but only seven exposed workflows. Existing workflows ranged from proper CI to deployment-only and stale scheduled automation. The scan was metadata-only: it did not clone repositories or execute commands.

Selected workflow inspection found:

  • projects: bounded metadata validation through make check;
  • accounting-workflows: make validate;
  • site-factory-showcase: typecheck, lint, tests, and build;
  • office-auto-lab: documentation frontend checks only;
  • atlas-pobreza-docs: Pages deployment without a repository-owned quality gate;
  • IPC-Argentina: disabled daily job that mutates the default branch;
  • microdatos-EPH-INDEC: disabled updater, broken cross-repository dispatch, and a workflow that enumerates secret names.

Workflow lanes​

1. Pull-request quality​

Runs on pull_request and on pushes to the default branch.

Permitted work:

  • compilation and imports;
  • lint and formatting checks;
  • unit and fixture tests;
  • schema and contract validation;
  • deterministic smoke checks;
  • documentation or application builds;
  • verification of committed snapshot semantics.

PR quality must not:

  • use repository or environment secrets;
  • access private production data;
  • call paid APIs;
  • mutate external systems;
  • push commits;
  • dispatch work to other repositories.

2. Deployment​

Deployment is separate from PR quality.

A deployment workflow must:

  • depend on a successful quality job;
  • run only from the default branch or an explicit release;
  • use a named GitHub environment when credentials or publication rights are involved;
  • declare the one authoritative deployment destination;
  • use the minimum write permissions;
  • support a bounded smoke check of the deployed surface.

External providers such as Vercel remain authoritative when already used. GitHub Actions should validate those repositories, not create a second deployment path.

3. Snapshot verification​

Data-bearing repositories may run offline checks over committed artifacts:

  • declared cutoff;
  • observed versus projected regions;
  • schema;
  • duplicates and invariants;
  • synthetic or imputed sections;
  • provenance metadata.

Snapshot verification is CI. Source acquisition is not.

4. Source probes and refreshes​

A source probe asks whether an upstream release exists and whether its interface still matches expectations. It may run manually or on a justified schedule.

A refresh:

  • is workflow_dispatch by default;
  • runs behind an environment when credentials or external mutation are involved;
  • produces a manifest with source URL, timestamp, checksum, row count, and code SHA;
  • uploads a bounded candidate artifact or opens a reviewable PR;
  • never commits canonical data directly to the default branch.

Low-activity public repositories must not rely on scheduled Actions as their only scheduler. GitHub may automatically disable scheduled workflows after repository inactivity.

5. Cross-repository actions​

The default GITHUB_TOKEN is repository-scoped. Cross-repository dispatch, PR creation, or artifact publication requires a dedicated GitHub App installation token with narrowly declared permissions.

There will be no personal access token acting as an undocumented estate-wide service account.

Required workflow baseline​

Every new or materially revised workflow must include:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Every job must declare timeout-minutes.

Additional rules:

  1. Do not use pull_request_target for repository-code validation.
  2. Do not enumerate secrets or secret names.
  3. Pin external actions to full commit SHAs; configure Dependabot for github-actions.
  4. Write permissions are exceptional and job-local.
  5. PR workflows cannot receive secrets.
  6. Use path filters only when skipped checks cannot leave a required status permanently pending.
  7. Upload only bounded diagnostic artifacts with short retention.
  8. CI commands must work locally before they are encoded in Actions.
  9. Full research experiments, live accounting runs, and large data refreshes do not run on ordinary PRs.
  10. A green deployment job does not certify analytical or data correctness.

Rollout sequence​

Wave 0 — quarantine and normalize​

  • remove or quarantine the three legacy workflows in microdatos-EPH-INDEC;
  • replace the IPC-Argentina daily mutating updater with snapshot verification;
  • add snapshot verification to canastasINDEC;
  • add permissions, concurrency, and timeouts to the existing workflows in:
    • accounting-workflows;
    • projects;
    • site-factory-showcase;
    • office-auto-lab.

Wave 1 — proven local commands​

Add CI where a bounded command already exists:

  • kb-contracts: npm ci && make check;
  • kb-artifacts: make test smoke contract-release-verify;
  • knowledge-inspect: make health smoke verify-run-evidence-demo;
  • income-modeling-eph: make lint test;
  • accounting-doc-triage: fixture-safe package install and pytest;
  • office-review: dependency install and production build;
  • web-grafo: dependency install and production build;
  • web-professional-template: dependency install and production build.

Wave 2 — command discovery and repair​

Codex/local packets must establish real checks before adding workflows to:

  • accounting-docs;
  • accounting-viewer;
  • capture-site;
  • context-routing;
  • paper-kb;
  • matias-context-mcp;
  • indice-pobreza-UBA;
  • weekly-ops-governance.

eph-censo-aligner is blocked until its generated placeholder make smoke becomes a real fixture-driven check.

Wave 3 — deployment gates and integration​

  • repair the Atlas configuration, then gate GitHub Pages on verifier + build;
  • add core CI to office-auto-lab while retaining its separate docs frontend workflow;
  • validate component seams with bounded fixtures;
  • introduce a dedicated GitHub App only when a real cross-repository mutation is approved.

Branch protection​

After a repository's CI has passed reliably on several PRs, Matías may make its stable job name a required check on the default branch.

Do not require a check before:

  • the workflow exists on the default branch;
  • it has been proven deterministic;
  • path filters and job naming are stable;
  • emergency recovery steps are documented.

Completion condition​

The governance campaign is complete when:

  • all 25 repositories have a declared Actions policy;
  • unsafe or misleading legacy workflows are removed;
  • every active quality workflow follows the baseline;
  • repositories without a proven local command remain explicitly blocked rather than receiving speculative CI;
  • deployments are separated from quality;
  • scheduled jobs have an owner, cadence, failure path, and non-mutating review boundary.