GitHub CI and security tools — Design Spec
Milestone: harness Manual: contributor-facing.
Tags: [OK] built and tested · [PARTIAL] built, partly proven or partly wired · [GAP] intended, never built (needs an issue) · [BROKEN] regression, code contradicts the rule (needs an issue).
Intent
The repository is public, so GitHub Actions (including macOS arm64 runners), CodeQL, secret scanning and Dependabot cost nothing. They add a second, independent reading of every change beside the builder’s own ladder; they do not replace it. Spec-change: owner 2026-11-20.
Dependabot
ci.dependabot[PARTIAL] (#6600; the file and its shape test are in the tree, no run of it on GitHub has been read yet) —.github/dependabot.ymlopens weekly update PRs (version and security) againstintegrationforfichero-server(uv, readinguv.lock), the Swift packagefichero/fichero-api-client(the onePackage.swiftunderfichero/; Dependabot’s swift ecosystem reads aPackage.swift, not the Xcode project’sPackage.resolved, so the app project has no entry), and GitHub Actions. Minor and patch updates are grouped per ecosystem and labelleddependenciesplus the ecosystem. Dependabot edits the manifests andPackage.resolveditself; nobody edits aPackage.resolvedby hand.fichero-builderhas no manifest or lock file today, so it has no entry; adding apyproject.tomlor requirements file there is what would bring it in. Acceptance:.github/dependabot.ymlparses, isversion: 2, and every entry hastarget-branch: integration, a weekly schedule and adirectorythat exists in the tree; aswiftentry’s directory holds aPackage.swift. Test:fichero-server/tests/unit/scripts/test_github_ci_files.py::test_dependabot_yml_targets_integration_weekly_over_directories_that_existin fichero-server/tests/unit/scripts/.
Security workflow
ci.security-workflow[PARTIAL] (#6600; the file and its shape test are in the tree, no run of it on GitHub has been read yet) —.github/workflows/security.ymlruns on pull requests tointegrationand nightly. It does not add a second scanner: jobscannersreads the pins and theosvswitch fromharness.toml [check.security], installs bandit and semgrep byuv tool installand gitleaks from its release at exactly those pinned versions (osv-scanner too, only whenosvis true), then runsscripts/security_scan_run.pywith those pins and the baselines underscripts/: bandit, semgrep, gitleaks, and osv-scanner over the Python lock and both SwiftPackage.resolvedfiles read by the rung’ssecurity_rung.read_osvonly whenosv = true(it is false while lane deps-security has open alerts, and the workflow follows it, so a PR is not red for an alert it did not cause). A red row fails the job, and so does aREFUSEDline or a scanner that wrote no JSON: a scanner that did not run is never a green. Jobcodeqlruns CodeQL for Python (ubuntu) and Swift (macos-15,build-mode: none; if the Swift extractor refuses that mode the job is changed to a manual build, which needs the Xcode project and is not attempted here). CodeQL results go to code scanning; blocking a merge on high or critical alerts is a repository ruleset setting. The owner switches on, in Settings > Code security: secret scanning, push protection, and code scanning as a required check onintegration; these are settings, not code, and this workflow does not set them. Acceptance: the workflow triggers onpull_requesttointegrationand on a schedule, namessecurity_scan_run.py, reads the pins andosvfromharness.toml, fails on a refused scanner, and its CodeQL matrix is Python and Swift. Test:fichero-server/tests/unit/scripts/test_github_ci_files.py::test_security_workflow_runs_on_prs_and_nightly_reuses_the_rungs_scanner_and_adds_codeqlin fichero-server/tests/unit/scripts/.
Test workflow
ci.test-workflow[PARTIAL] (#6600; the file and its shape test are in the tree, no run of it on GitHub has been read yet) —.github/workflows/tests.ymlruns on pull requests tointegration, report-only (every job iscontinue-on-error, so a red run blocks nothing until the maintainer has read a few weeks of results). Jobengine(macos-15, arm64; uv with its cache keyed onfichero-server/uv.lock) runs everyscripts/check_spec_*.pyguard and thenpytest tests/unitinfichero-server. Jobswift(macos-15) builds theFichero (Dev Local)scheme and runs its unit tests with signing off. Public repositories pay nothing for these minutes; the first runs are the measure of whether the Swift job fits in a run the builder can wait for, and if it does not it is split or moved to Xcode Cloud (seereviews/2026-11-20-ci-review.md). Acceptance: the workflow triggers onpull_requesttointegration, has exactly the jobsengineandswift, bothcontinue-on-erroronmacos-15, and the engine job enables the uv cache. Test:fichero-server/tests/unit/scripts/test_github_ci_files.py::test_test_workflow_runs_on_prs_to_integration_report_only_with_a_cached_uv_engine_job_and_a_swift_jobin fichero-server/tests/unit/scripts/.
Dependency and security audits
ci.dependency-audit[PARTIAL] (#6600) — one auditor reads both sides, not one per language: osv-scanner reads the engine’sfichero-server/uv.lockand both SwiftPackage.resolvedfiles (the app project’s, which Dependabot cannot read, and the api-client package’s), andsecurity_rung.read_osvinfichero-builder/fichero_builder/security_rung.pyturns its findings into the rung’s rows. pip-audit is not added: it would read the same advisories for the Python lock alone. Swift advisories arrive the same way, and as Dependabot security alerts for the api-client package. Built: the reader, the pinned version and the workflow step. Left:harness.toml [check.security] osv = false, so neither the rung nor the workflow runs it today; it is switched on when the open alerts are cleared. Acceptance: withosv = truea vulnerable pin in a fixture lock is a red row naming the package and the advisory, for the Python lock and for aPackage.resolved; withosv = falsethe row says not run, never green.
Python test tiers on Actions
ci.python-tiers[GAP] (#6600) — GitHub Actions runs every Python tier a hosted runner can, one job per tier, so the builder can read each by name. Built: the engine’stests/unittier and thecheck_spec_*guards (ci.test-workflow). Left: the builder’s own suite (fichero-builder/tests) and the engine’s contract tier (fichero-server/tests/contracts) have no job. The integration and perf tiers need models, libraries and a quiet machine and stay on the Macs. Acceptance:tests.ymlhas one job per tier it runs, named for the tier, and the shape test infichero-server/tests/unit/scripts/test_github_ci_files.pynames each.
Xcode Cloud
ci.xcode-cloud-swift-only[GAP] (#6600) — Xcode Cloud, if it is used, builds and tests Swift only: the app schemes and the Swift test target. It never runs Python: no engine tests, no guards, no engine (Briefcase) build. Python stays on GitHub Actions and the Macs. Nothing is configured today: the tree holds no Xcode Cloud workflow or script, and the Swift job runs on Actions (ci.test-workflow) until its measured time says it should move. Acceptance: a custom script added for Xcode Cloud starts no Python interpreter, and a test of the CI files says so.
Repository settings
ci.settings-are-the-owners[GAP] (#6600) — secret scanning, its push protection, Dependabot alerts and security updates, and code scanning as a required check onintegrationare repository settings. The owner switches them on; no workflow, script or builder verb sets them, and a worker has no token that could. Until they are on, a secret is caught only by the gitleaks scan ofci.security-workflowand the builder’s own security rung, after the push, not before it.
The builder reads the results
ci.builder-reads-actions[GAP] (#6600) —builder checkmay take a green GitHub Actions run for the same commit as one rung, so the three Macs do less. It is opt-in:[check.github] use_actions = falseinharness.toml, off until the owner turns it on. How it reads a run, on the manager’s side only (workers have no GitHub token and never call it):gh run list --commit <head sha> --workflow tests.yml --json databaseId,status,conclusionfor the exact head sha of the batch, then the run’s jobs throughgh api(the Actions “list jobs for a workflow run” endpoint). The jobs arecontinue-on-error, which makes the run’s own conclusionsuccesseven when a job failed, so the rung reads each JOB’s conclusion and each step’s conclusion, never the run’s. The rung is satisfied only when the run iscompleted, its head sha equals the batch head exactly, and theenginejob’s stepsSpec guardsandUnit testsaresuccess. It then stands in for the engine unit-test rung and the spec-guard rung of that batch, and the ladder row saysfrom GitHub run <id>. A run that is missing, still running, for another sha, red, cancelled, or unreadable (nogh, no network, a bad reply) is never a pass: the rung runs on the Macs as it does today and the row says why the run was not used. Thebuild,perf, red-on-base and review rungs never come from GitHub. The security rung’s scanners may be taken the same way from thesecurity.ymljobscanners, and CodeQL alerts are read from code scanning for the head sha and listed in the review prompt under SECURITY SCAN as reported, never as a gate. Acceptance (no network, a fakegh): a completed run for the head sha whoseUnit testsstep succeeded satisfies the rung; the same run with the step failed, a run for the parent sha, a run stillin_progress, aghthat exits non-zero, anduse_actions = falseeach leave the rung to run locally with the reason in its row. Built: nothing yet; the workflows above are what it will read.
What the builder reads from Actions and what it runs on the Macs
ci.actions-or-local[GAP] (#6600) — each check has one place it may come from. Today every row below is run on the Macs:harness.tomlhas no[check.github]table andfichero-builder/fichero_builder/check_tool.pyhas no reader (ci.builder-reads-actions). Acceptance: every rung’s row names its source,local, a runner, orfrom GitHub run <id>; a rung in the last two rows of the table never names a GitHub run.
| Check | Read from GitHub | Run on the Macs |
|---|---|---|
| Engine unit tests, spec guards | a green tests.yml job for the exact head, when use_actions is on |
otherwise, and always when the run is missing, red or unreadable |
| bandit, semgrep, gitleaks, osv-scanner | the scanners job of security.yml, the same way |
otherwise |
| CodeQL | code scanning alerts for the head, listed for the reviewer | never run locally; never a gate in the builder |
| Dependabot | its pull requests and alerts live on GitHub | nothing in the builder reads them yet |
| Builder’s own tests, contract tier | not yet (ci.python-tiers) |
yes |
| Pinned checks, ready, diff bound, red-on-base, the build rung, Swift tests, perf, review | never | always |
| Nightly verify, DMG, notarize, smoke, publish | never | always |