fork-sync-all

Sync · Mirror · Automate

fork-sync-all is the control plane for the Interested-Deving-1896 GitHub org. It mirrors repositories into OpenOS-Project-OSP (GitHub) and then to openos-project (GitLab), manages READMEs across ~49 OSP-bound repos, syncs upstream forks, and runs org-wide maintenance workflows.

Quick navigation

fork-sync-all

When Git Platforms Give You Anxiety Attacks, Who Are You Going To Call? Fork-Sync-All!

Control plane for the Interested-Deving-1896 GitHub org. Runs 147 GitHub Actions workflows that keep three GitHub orgs and two GitLab groups in sync, manage READMEs and badges across OSP-bound repos, resolve CI failures, and maintain registered upstream imports.

How it works

┌─────────────────────────────────────────────────────────────────────────────┐
│  Mirror chain (outward, every 6h)                                           │
│                                                                             │
│  Interested-Deving-1896 ──► OpenOS-Project-OSP                              │
│          ▲                         │                                        │
│          │                         ▼                                        │
│          │              OpenOS-Project-Ecosystem-OOC                        │
│          │                         │                                        │
│          │                         ▼                                        │
│          │                  GitLab openos-project                           │
│          │             (14 subgroups, 225 repos mirrored)                   │
│          │                                                                  │
│          └──── upstream-commits / upstream-prs (OSP + OOC → I-D-1896) ─────┘
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  Full pipeline (manual / monthly)                                           │
│                                                                             │
│  flush-lifecycle ──► pre-flush-prep ──► full-chain-flush (25 stages) ──► post-flush-prep │
│       │                      │                             │                │
│  QUOTA_SNAPSHOT          QUOTA_SNAPSHOT               QUOTA_SNAPSHOT        │
│  (chain entry)           (chain start)                (chain exit)          │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  Quota & queue management (automatic, every 30 min)                         │
│                                                                             │
│  quota-reserve ──► queue-manager ──► rate-limit-rerun                       │
│                                           │                                 │
│                                    cancel-stale-runs                        │
│                                      quota-monitor                          │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  OTA system (versioned updates for independent forks)                       │
│                                                                             │
│  ota-release ──► ota-deliver ──► opted-in forks (PR per fork)               │
│       ▲                                                                     │
│  semver tag push                                                            │
│                                                                             │
│  ota-reconcile (weekly) ──► path A: stamp · B: drift PR · C: quota PR      │
└─────────────────────────────────────────────────────────────────────────────┘

This project provides automated management for git repositories and organizations across multiple git-based platforms. It addresses challenges such as keeping forks synchronized, generating READMEs, injecting badges, tracking upstream changes, mirroring repositories, and managing releases. It is used by developers and organizations to streamline repository maintenance and ensure consistency across distributed version control systems.

Documentation

Workflow groups

158 workflows across 20 functional groups. Full detail in DOCS/workflow-triggers.md.

Key config files

Secrets

gh secret set <SECRET_NAME> --repo Interested-Deving-1896/fork-sync-all

Rate limits

Both SYNC_TOKEN and GH_SYNC_TOKEN belong to the same user and share the same 5,000 req/hr REST bucket. Treat them as one pool. raw.githubusercontent.com fetches do not count against the quota.

quota-reserve.yml cancels low-priority queued runs when remaining quota drops below 1,000. Check current quota:

curl -sf -H "Authorization: token $SYNC_TOKEN" \
  "https://api.github.com/rate_limit" | \
  python3 -c "
import sys, json, datetime
d = json.load(sys.stdin)['resources']['core']
reset = datetime.datetime.utcfromtimestamp(d['reset']).strftime('%H:%M UTC')
print(f'remaining={d[\"remaining\"]}  resets={reset}')
"

GitLab subgroups

14 subgroups under gitlab.com/openos-project, 225 repos mirrored. Assignments are in config/gitlab-subgroups.yml.

All automation is implemented as Bash scripts in scripts/ and GitHub Actions workflows in .github/workflows/. There are no compiled artifacts, no Node.js runtime dependencies, and no build step — every workflow runs directly against the shell scripts.

.
├── .github/workflows/    # 147 GitHub Actions workflows
├── scripts/              # Bash automation scripts
│   └── includes/         # Shared helpers (gh-api.sh, budget.sh, quota-instrument.sh, …)
├── config/               # YAML config: subgroup maps, quota costs, priority tiers, …
├── DOCS/                 # mdBook source (architecture, runbooks, quota reference, …)
│   └── generated/        # Auto-generated pages (workflow reference, source tree, …)
├── services/             # Long-running service helpers (sync-in server)
├── vendor/               # Third-party components hosted by fork-sync-all
├── .devcontainer/        # Dev container definition and local features
├── .ona/                 # Ona automations (services + tasks)
├── registered-imports.json  # Upstream repos kept in sync
├── book.toml             # mdBook configuration
└── Dockerfile            # Container image for CI runners

Scripts communicate via environment variables and exit codes. Shared helpers in scripts/includes/ provide GitHub API access (gh-api.sh), quota budgeting (budget.sh), and run instrumentation (quota-instrument.sh). See Architecture for the full data-flow diagram.

The repository uses GitHub Actions for continuous integration and automation. Below are the workflows and their purposes:

• build.yml: Builds the project for all supported platforms. No secrets required.
• test.yml: Runs unit and integration tests. No secrets required.
• lint.yml: Checks code formatting and style using ESLint. No secrets required.
• sync-forks.yml: Synchronizes forks with upstream repositories. Requires UPSTREAM_TOKEN secret.
• mirror-orgs-full.yml: Mirrors repositories across organizations. Requires MIRROR_TOKEN secret.
• inject-badges.yml: Injects badges into README files. No secrets required.
• release.yml: Manages release creation and tagging. Requires RELEASE_TOKEN secret.
• check-ci.yml: Validates CI configuration files. No secrets required.
• cleanup-branches.yml: Deletes stale branches. Requires GITHUB_TOKEN secret.
• codeql-analysis.yml: Performs CodeQL security analysis. Requires GH_CODEQL_TOKEN secret.

Secrets must be configured in the repository settings under "Settings > Secrets and variables > Actions."

Origins

Auto-generated by generate-dep-graph.sh. Do not edit manually. Last generated: 2026-06-12 (stub — full graph generated on next scheduled run)

This graph maps every OSP-bound repo in Interested-Deving-1896 to its upstream origin(s), as declared in each repo's ## Origins README section.

Summary

• OSP-bound repos scanned: stub (full scan runs weekly via generate-dep-graph.yml)
• Tooling dependencies tracked: github-codeowners (CODEOWNERS auditing across all OSP repos)

Tooling Dependencies

Resources

Accessibility

This repo uses automated accessibility auditing via check-accessibility.yml.

Checks include: CODEOWNERS ownership coverage, README screen-reader compatibility, WCAG 2.1 AA HTML compliance, audio overview (espeak-ng), and Braille output (liblouis).

Run the Check Accessibility workflow to generate the first report and accessibility artifacts. See DOCS/accessibility.md for the full reference.

This repo is maintained in Interested-Deving-1896/fork-sync-all and mirrored through:

Interested-Deving-1896/fork-sync-all  ──►  OpenOS-Project-OSP/fork-sync-all  ──►  OpenOS-Project-Ecosystem-OOC/fork-sync-all

Changes flow downstream automatically via the hourly mirror chain in fork-sync-all. Direct commits to OSP or OOC are detected and opened as PRs back to Interested-Deving-1896.

Contributors

@Interested-Deving-1896: 480 commits
@github-actions[bot]: 78 commits
@actions-user: 7 commits
@dependabot[bot]: 6 commits
@web-flow: 5 commits

Note: This repository may be a mirror. Please refer to the upstream source for additional context.

License

AGENTS.md

Conventions, patterns, and known pitfalls for AI agents working in this repo.

Repository overview

fork-sync-all is the control plane for the Interested-Deving-1896 GitHub org. It mirrors repos into OpenOS-Project-OSP (GitHub) and then to openos-project (GitLab), manages READMEs across ~49 OSP-bound repos, syncs upstream forks, and runs org-wide maintenance workflows.

Key config files:

• config/gitlab-subgroups.yml — single source of truth for GitLab subgroup placement
• registered-imports.json — upstream repos to keep in sync
• scripts/ — all automation scripts
• .github/workflows/ — GitHub Actions workflows

Key directories:

• vendor/ — third-party components hosted/deployed by fork-sync-all (e.g. infra-dashboard). Everything in scripts/ is first-party automation. Do not move scripts into vendor/.

GitHub API quota

Both GH_TOKEN and SYNC_TOKEN belong to the same user (ID 202036334) and share the same 5000 req/hr REST bucket. Treat them as one pool.

• raw.githubusercontent.com fetches do not count against the quota
• GraphQL counts as 1 call regardless of how many repos are queried
• The quota pre-flight in workflows uses MIN_QUOTA (typically 1000–1500) to skip runs when the bucket is too low; quota-monitor.sh retries after reset

When quota is at 0, avoid any gh api, curl .../api.github.com/..., or gh_get calls. Check reset time with:

curl -sf -H "Authorization: token $SYNC_TOKEN" \
  "https://api.github.com/rate_limit" | jq '{remaining, reset: (.resources.core.reset | todate)}'

AI agent cost budgeting

This repo uses multiple AI agents. Each has a different billing model — understand which resource you're spending before starting a task.

OCU top-up packages (one-time, $0.25/OCU flat): 40 OCUs/$10 · 100/$25 · 200/$50 · 400/$100 · 1,000/$250 · 2,000/$500 · 4,000/$1,000 · 8,000/$2,000

Rough task sizing (Ona Agent on Standard environment):

• Small fix / single file: 1–4 OCUs
• Multi-file feature + tests: 8–12 OCUs
• Large session (3–4 hr, many files): 15–24 OCUs
• Full end-to-end update: 19–31 OCUs

GitHub API quota and OCUs are independent. GitHub quota exhaustion pauses the agent but does not consume OCUs. OCU exhaustion stops the session regardless of GitHub quota state.

Full reference: DOCS/ai-agent-costs.md Machine-readable profiles: config/agent-cost-profiles.yml Log a session: gh workflow run track-agent-costs.yml --field agent=ona --field ...

Script conventions

All logging helpers must write to stderr

Every script defines some combination of info(), warn(), dry(), and log(). All must use >&2:

info() { echo "[script-name] $*" >&2; }
warn() { echo "[warn] $*" >&2; }
dry()  { echo "[dry-run] $*" >&2; }
log()  { echo "[$(date -u '+%H:%M:%S')] $*" >&2; }

Why this matters: Several functions are called inside $(...) subshell captures where their stdout becomes the captured value (e.g. README content, repo lists, API responses). Any logging call without >&2 inside such a function will corrupt the captured data.

This applies to includes/gh-api.sh too — merge_upstream() status messages must go to stderr since callers may capture its output via result=$(merge_upstream ...).

Known functions called inside $(...) captures — never emit to stdout inside these:

• rewrite_readme() in update-readmes.sh
• fill_missing_sections() in update-readmes.sh
• build_readme() in create-readmes.sh
• generate_*() functions in update-readmes.sh
• merge_upstream() in scripts/includes/gh-api.sh

YAML parsing

Always use yaml.safe_load — never hand-rolled regex/indent parsers:

import yaml
with open(config_path) as f:
    config = yaml.safe_load(f)
subgroups = config.get("subgroups", {}) or {}

This applies to gitlab-subgroups.yml parsing in all scripts.

includes/ scripts

scripts/includes/budget.sh, scripts/includes/gh-api.sh, and scripts/includes/quota-instrument.sh are sourced by many scripts and workflows. Changes there have broad impact.

• budget.sh — provides budget_init, budget_check, budget_report, osp_priority_repos, and workflow_min_quota. The latter reads per-workflow min_quota from config/workflow-quota-costs.yml.
• gh-api.sh — provides gh_api, gh_get, gh_api_graphql, merge_upstream, get_default_sha. All status messages use >&2. Guard against double-sourcing is in place (_GH_API_LOADED). gh_get URL is a convenience GET wrapper around gh_api with full retry and reset-aware backoff — the canonical implementation that individual scripts should migrate to (see consolidation note below).
• platform-adapter.sh — uniform interface for GitHub, GitLab, Gitea, Forgejo, and Codeberg. See Platform adapter below.
• fsa-node-identity.sh — extends fsa-mode.sh with a chain position layer. See Node identity below.
• auto-merge-prs.sh — standalone script (not an include); see Auto-merge PRs below.

gh_get / gh_api consolidation (complete)

All scripts now source includes/gh-api.sh for gh_get. The three tiers that existed during migration have been fully consolidated:

All new scripts should source includes/gh-api.sh and use gh_get directly. Do not define a local gh_get() in any new script.

• quota-instrument.sh — provides qi_begin / qi_end for measuring REST quota consumption per workflow run. Wire into the main job step of any workflow you want to instrument. Writes a structured HTML comment to GITHUB_STEP_SUMMARY that update-quota-costs.yml parses weekly to compute observed p50/p95 values.

  qi_begin/qi_end must be in the same run: step — _QI_BEFORE is a shell variable that does not survive across step boundaries. When the work spans multiple steps (e.g. delete-stale-repos.yml), persist the value via a temp file:

  # Step A — sample before
  source scripts/includes/quota-instrument.sh
  qi_begin
  echo "$_QI_BEFORE" > /tmp/qi_before
  
  # Step B (always()) — emit delta
  source scripts/includes/quota-instrument.sh
  if [[ -f /tmp/qi_before ]]; then
    _QI_BEFORE=$(cat /tmp/qi_before)
    qi_end
  fi
  

  If Step A is skipped (e.g. quota pre-flight exits early), /tmp/qi_before will not exist and the qi_end block silently no-ops — no spurious delta is recorded.

REST → GraphQL conversion

Prefer GraphQL over paginated REST for any loop that fetches the same data for multiple repos. GraphQL counts as 1 REST call regardless of how many repos are queried.

Standard pattern for org repo lists:

result=$(curl -sf \
  -H "Authorization: token ${GH_TOKEN}" \
  -H "Content-Type: application/json" \
  "${GH_API}/graphql" \
  -d "{\"query\":\"{ organization(login: \\\"${ORG}\\\") { repositories(first: 100) { nodes { name } pageInfo { hasNextPage endCursor } } } }\"}" \
  2>/dev/null || echo "{}")
echo "$result" | python3 -c "
import json,sys
d=json.load(sys.stdin)
for n in d.get('data',{}).get('organization',{}).get('repositories',{}).get('nodes',[]):
    print(n['name'])
" 2>/dev/null

Prefetch pattern for per-repo metadata (existence, pushedAt, README): Batch all repos into a single GraphQL call using aliases, populate an associative array, then read from the cache in the loop — zero REST calls per repo:

declare -A _REPO_EXISTS=()
# ... build aliases, fire one GraphQL call, populate _REPO_EXISTS ...
# In the loop:
[[ -z "${_REPO_EXISTS[$repo]:-}" ]] && continue  # skip non-existent repos

See sync-registered-imports.sh (prefetch_repo_metadata), mirror-releases.sh (prefetch_upstream_existence), and inject-badges.sh (list_gh_repos + _README_CACHE) for reference implementations.

What cannot be converted to GraphQL:

• check-runs and statuses endpoints — not exposed in GraphQL
• actions/workflows and actions/secrets — not in GraphQL
• Write operations (create repo, push file, cancel run) — REST only

Tree fetches

Use ?recursive=1 on the git trees endpoint to get all file paths in one call, then check membership with grep -qxF before fetching individual files:

tree_json=$(gh_get "${GH_API}/repos/${owner}/${repo}/git/trees/HEAD?recursive=1")
tree_paths=$(echo "$tree_json" | jq -r '.tree[] | select(.type=="blob") | .path')
echo "$tree_paths" | grep -qxF "package.json" && # file exists, fetch it

Never probe file existence with per-file /contents/ calls in a loop.

YAML-safe shell in run: blocks

GitHub Actions run: blocks are YAML block scalars. The YAML parser processes the file before the shell runner sees it, so certain shell constructs break parsing even though they would be valid bash.

Patterns that break YAML — never use these inside run: blocks:

Safe alternatives:

# Multi-line python: collapse to one line
repos=$(python3 -c "import yaml; d=yaml.safe_load(open('config/x.yml')); print(' '.join(d.get('repos',[])))")

# Multi-line variable: use printf into a temp file
printf 'line1\nline2\n' > /tmp/body.txt

# Multi-line commit message: ANSI-C quoting
git commit -m $'subject\n\nbody line 1\nbody line 2'

# Or chained -m flags (each becomes a paragraph)
git commit -m "subject" -m "body paragraph"

# Heredoc end-marker: use a non-YAML-keyword name
cat > file.yml << 'CONFIG_EOF'
...
CONFIG_EOF

The validator catches these: python3 scripts/validate-workflow-guards.py runs a YAML parse check across all 75 workflow files. Run it after editing any workflow. The full-suite parse check is also embedded in validate-config.yml.

Workflow patterns

Queue and quota management

Four workflows protect the system from quota exhaustion cascades and runner starvation:

Priority tiers — single source of truth in config/workflow-priority-tiers.yml:

• Tier 1 CRITICAL — never cancelled (token rotation, queue/reserve management, config validation)
• Tier 2 HIGH — mirror chain, sync operations
• Tier 3 MEDIUM — READMEs, CI checks (default for unknown workflows)
• Tier 4 LOW — translation, dep graph, maintenance (cancelled first)

When adding a new workflow, add it to both:

1. config/workflow-priority-tiers.yml — by workflow name: field (not filename). Both queue-manager.sh and quota-reserve.sh load tiers from this file at runtime — no script edits needed.
2. config/workflow-sync.yml — under github_only (most workflows) or paired (if it has a GitLab CI counterpart). validate-workflow-guards.py warns on any workflow file not listed in either section.

Run python3 scripts/validate-workflow-guards.py after adding any workflow to confirm zero warnings.

dispatch-and-wait.sh exit codes:

• 0 — workflow completed successfully
• 1 — workflow failed or timed out
• 2 — workflow was cancelled (by queue-manager or manually) — retriable, not a real failure

full-chain-flush.yml and critical-deploy.sh both handle exit 2 with a warning rather than aborting.

Concurrency groups

All workflows triggered by schedule or workflow_run must have a concurrency group to prevent queue pile-ups:

concurrency:
  group: workflow-name
  cancel-in-progress: true

workflow_run triggers

Each workflow should have at most one workflow_run upstream trigger. Multiple triggers cause fan-out: N completions × M downstream workflows = queue explosion.

Every name in workflow_run.workflows: must exactly match the name: field of a workflow file that actually exists in .github/workflows/. A phantom name causes the trigger to fire on every push but the job fails immediately — GitHub cannot resolve the upstream workflow. validate-workflow-guards.py (Check 5) catches this automatically.

Quota pre-flight

All hourly/daily/frequent workflows include a quota pre-flight step before doing any API work. The step sets skip=true when remaining < MIN_QUOTA and subsequent steps check if: steps.quota.outputs.skip == 'false'.

Quota cost registry

config/workflow-quota-costs.yml is the single source of truth for per-workflow REST call cost estimates. It drives:

• quota-reserve.sh — cost-aware cancellation (min_quota per workflow)
• budget.sh workflow_min_quota() — pre-flight helper for self-skipping
• DOCS/quota-costs.md — rendered documentation in mdBook

Phase 1 values are code-audit estimates (basis: code-audit). Phase 2 (update-quota-costs.yml, weekly) replaces them with observed p50/p95 values (basis: observed) once ≥5 run samples exist per workflow.

When adding a new workflow that makes significant REST calls, add it to config/workflow-quota-costs.yml with estimated min_quota, cost_low, cost_mid, cost_high, and basis: code-audit. Wire qi_begin/qi_end from scripts/includes/quota-instrument.sh into its main job step so Phase 2 can measure it automatically.

Instrumented workflows (Phase 2 active):

• Sync All Forks
• Inject Built-with-Ona Badges
• Reconcile Org References
• Cleanup Stale Branches
• Check OSP-Bound CI Status
• Check Shell Tools CI
• Sync Registered Imports
• Sync Shell Tools
• Sync UAA Vendor
• Mirror Interested-Deving-1896 → OSP
• Pre-Mirror CI Gate
• Verify Mirror Integrity
• Post-Flush Verification
• Pipeline Telemetry
• Translate Docs
• Integrate Shell Tools
• Onboard Repo
• Critical Deploy
• Critical Deploy — OSP
• Critical Deploy — OOC
• GitLab Critical Deploy
• Critical Deploy — All (all four deploy jobs)
• Flush Active Watchdog
• Branch Hygiene Report
• btrfs-devel sync
• Delete Stale Repos

FLUSH_ACTIVE mutex

FLUSH_ACTIVE is a GitHub Actions repo variable (true/false) used as a mutex to prevent queue-manager and quota-reserve from cancelling runs during a flush pipeline. It is set by flush-lifecycle.yml and cleared by flush-active-watchdog.yml.

The force-cancel problem: If a flush run is cancelled via the GitHub UI, its always() cleanup step never executes, leaving FLUSH_ACTIVE=true permanently. Three layers defend against this:

1. Primary — flush-active-watchdog.yml: Fires on workflow_run: completed for Flush Lifecycle Manager + all 5 critical-deploy variants. Unconditionally clears FLUSH_ACTIVE=false regardless of conclusion (success/failure/cancelled).

2. Belt-and-suspenders — TTL check in queue-manager.sh + quota-reserve.sh: Both scripts read the variable's updated_at timestamp and treat it as unset if >8h old. A stuck mutex auto-expires even if the watchdog misses an event.

3. Pipeline guard — scripts/includes/pipeline-guard.sh: Reusable include sourced by all critical-deploy workflows. Provides pipeline_guard_start, pipeline_guard_checkpoint, and pipeline_guard_end helpers that manage FLUSH_ACTIVE state and emit step-summary annotations.

When adding a new workflow that participates in the flush pipeline:

• Source scripts/includes/pipeline-guard.sh and call pipeline_guard_start / pipeline_guard_end around the protected work.
• Add the workflow's name: to flush-active-watchdog.yml's workflow_run.workflows: list.

queue-manager.sh and quota-reserve.sh FLUSH_ACTIVE check:

# Both scripts skip cancellation when FLUSH_ACTIVE=true AND updated within 8h.
# If updated_at is >8h ago the variable is treated as stale and ignored.
flush_active=$(gh api "/repos/${REPO}/actions/variables/FLUSH_ACTIVE" \
  --jq '.value' 2>/dev/null || echo "false")
flush_updated=$(gh api "/repos/${REPO}/actions/variables/FLUSH_ACTIVE" \
  --jq '.updated_at' 2>/dev/null || echo "")
# TTL check: ignore if >8h old

Pipeline guard pattern

All critical-deploy workflows use scripts/includes/pipeline-guard.sh to standardise how they interact with FLUSH_ACTIVE:

source scripts/includes/pipeline-guard.sh

# At job start — sets FLUSH_ACTIVE=true, emits step-summary header
pipeline_guard_start

# Mid-run quota check — logs remaining quota to step summary
pipeline_guard_checkpoint

# At job end (in always() step) — clears FLUSH_ACTIVE=false
pipeline_guard_end

Each critical-deploy workflow also has a sentinel job that runs in parallel with the deploy job (needs: [], if: always()). The sentinel holds a runner slot for the duration of the deploy, preventing the runner pool from being exhausted by lower-priority queued work during a critical operation.

Path filters + required status checks (gate job pattern)

When a workflow uses path filters to skip jobs on irrelevant changes, required status checks will block PRs indefinitely if the filtered jobs never run. Fix this with a gate job that always runs and reflects the filtered outcomes:

jobs:
  changes:
    name: Detect changes
    runs-on: ubuntu-latest
    outputs:
      shell: ${{ steps.filter.outputs.shell }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            shell:
              - '**/*.sh'

  lint:
    name: ShellCheck
    needs: changes
    if: needs.changes.outputs.shell == 'true'
    runs-on: ubuntu-latest
    steps: [...]

  # Set THIS as the required status check — not the individual jobs above.
  ci-required:
    name: CI Required
    runs-on: ubuntu-latest
    needs: [lint]
    if: always()
    steps:
      - name: Check results
        run: |
          if echo "${{ join(needs.*.result, ' ') }}" | grep -qw "failure"; then
            exit 1
          fi

Branch protection must require CI Required (the gate job name), not the individual filtered job names. If the individual names are listed as required checks, PRs that skip those jobs will be permanently blocked.

Applied in: btrfs-dwarfs-framework/.github/workflows/ci.yaml

Autonomous-fallback mode

Consumer repos that receive the infra-core or upstream-sync profile get a bundle of operational workflows (rate-limit rerun, CI resolver, queue manager, quota reserve, notify-poller, branch cleanup) as autonomous fallbacks.

Managed mode (default): fork-sync-all is present and handles all of these centrally. The bundled workflows detect this and skip themselves.

Autonomous mode: if a consumer repo is forked independently without fork-sync-all alongside it, the bundled workflows activate and self-manage, scoped to the repo's own owner.

Mode detection (scripts/includes/fsa-mode.sh)

Three-tier hybrid check, evaluated in order:

sync-template.sh sets FSA_MANAGED=true as a repo Actions variable on every successful consumer sync via PUT /repos/{owner}/{repo}/actions/variables/FSA_MANAGED.

Adding the guard to a workflow

- name: Check FSA mode
  id: fsa
  env:
    GH_TOKEN: ${{ secrets.SYNC_TOKEN }}
    FSA_MANAGED: ${{ vars.FSA_MANAGED }}
    REPO_OWNER: ${{ github.repository_owner }}
  run: |
    source scripts/includes/fsa-mode.sh
    if fsa_is_managed; then
      echo "managed=true" >> "$GITHUB_OUTPUT"
      echo "Managed by fork-sync-all — skipping."
    else
      echo "managed=false" >> "$GITHUB_OUTPUT"
    fi

# Then on work steps:
- name: Do work
  if: steps.fsa.outputs.managed == 'false'

For workflows without a checkout (e.g. notify-poller.yml), inline the three-tier check directly in the step's run: block rather than sourcing fsa-mode.sh. See notify-poller.yml for the canonical inline implementation. The inline version replicates checks B → A → C using curl and python3.

Node identity (fsa-node-identity.sh)

scripts/includes/fsa-node-identity.sh extends fsa-mode.sh (managed/autonomous binary) with a position layer — each instance knows where it sits in the mirror chain and adjusts which operations it runs accordingly.

Three positions:

Mirror nodes skip source-only operations (readmes, badges, fork-sync, templates, translate) to prevent duplicate work across the chain.

Detection order (first match wins):

1. Explicit FSA_CHAIN_POSITION env var override
2. GITHUB_REPOSITORY matches canonical slug (Interested-Deving-1896/fork-sync-all)
3. FSA_UPSTREAM_OWNER env var set → mirror
4. fsa_is_managed() returns true + non-canonical owner → mirror
5. Default → downstream-fork

Exported variables (also written to GITHUB_OUTPUT):

• FSA_NODE_POSITION — source | mirror | downstream-fork
• FSA_NODE_OWNER — the org this instance manages
• FSA_UPSTREAM_OWNER — the org being mirrored from (empty for source/fork)
• FSA_CHAIN_DEPTH — 0=source, 1=first mirror, 2=downstream-fork

Capability predicates — return 0 (true) or 1 (false):

fsa_can_mirror_to_github   # push repos to a downstream GitHub org
fsa_can_mirror_to_gitlab   # push repos to a GitLab group
fsa_can_update_readmes     # write README files (source + fork only)
fsa_can_inject_badges      # inject badges (source + fork only)
fsa_can_sync_forks         # sync upstream forks (source + fork only)
fsa_can_translate          # run translation (source + fork only)
fsa_can_manage_templates   # push templates to consumers (source + fork only)

Usage:

source scripts/includes/fsa-node-identity.sh
fsa_node_detect
fsa_node_summary   # prints position + active capabilities to stderr

fsa_can_update_readmes && bash scripts/update-readmes.sh

Override env vars (set in workflow env: block):

• FSA_CHAIN_POSITION — force a specific position (skips all detection)
• FSA_UPSTREAM_OWNER — declare the upstream org (triggers mirror detection)
• FSA_CANONICAL_OWNER — override the canonical source org (default: Interested-Deving-1896)

Scope narrowing in autonomous mode

Workflows that are org-wide in managed mode narrow their scope in autonomous mode:

Template manifest — source:dest remap syntax

Include entries in config/template-manifest.yml support a source:dest remap:

include:
  - assets/docs-scaffold/SUMMARY.md:DOCS/SUMMARY.md   # read from assets/, write to DOCS/
  - scripts/write-summary.sh                           # plain entry: source == dest

sync-template.sh splits on the first : — the left side is the path relative to the template root (read), the right side is the path written into the target repo. Plain entries (no :) write to the same path.

Scaffold-only behaviour: entries whose source starts with assets/docs-scaffold/ are skipped if the destination file already exists in the target repo. This prevents overwriting a consumer's existing DOCS/ content on subsequent syncs.

Devcontainer template propagation

devcontainer.template.json and automations.template.yaml are propagated to consumer repos via source:dest remaps in config/template-manifest.yml. Both are scaffold-only — skipped if the destination already exists in the consumer.

include:
  - .devcontainer/devcontainer.template.json:.devcontainer/devcontainer.json
  - .devcontainer/automations.template.yaml:.ona/automations.yaml

These entries are present in the infra-core, upstream-sync, standalone, and shell-tools profiles. The .devcontainer/ directory is otherwise excluded from template sync (it contains fork-sync-all-specific config that consumers should not receive).

Template divergence rule: devcontainer.template.json and the live .devcontainer/devcontainer.json must stay in sync. When updating either:

• Pin headroom-ai to a specific version in both files
• Keep --no-ccr-inject-tool in the headroom proxy start command in both automations.template.yaml and .ona/automations.yaml
• Run python3 scripts/devcontainer-validate.py to catch divergences

Devcontainer feature — git-platform-clis

.devcontainer/features/git-platform-clis/ is a devcontainer feature that installs CLIs for all major git hosting platforms.

Installed by default: gh (GitHub CLI), glab (GitLab CLI), tea (Gitea CLI)

Optional via feature options: hub (legacy GitHub CLI), bb (Bitbucket CLI), forgejo-cli (Forgejo/Gitea v1.21+ API client) — all false by default.

Referenced in devcontainer.json and devcontainer.template.json by local path. When published to GHCR via devcontainer-sdk.yml publish mode, consumers can reference it by URI: ghcr.io/Interested-Deving-1896/fork-sync-all/git-platform-clis:1

The feature has not yet been published to GHCR. Until a publish run completes, only local path references work. Run devcontainer-sdk.yml with mode: publish to push it.

Devcontainer feature — sync-in-server

.devcontainer/features/sync-in-server/ installs the Sync-in server binary at container build time from github.com/Sync-in/server releases.

Binary resolution order in services/sync-in/start.sh (hybrid A→B→C→D):

If all four fail, the service exits with a clear message and suggests running the Install Sync-in Server automation task.

services/sync-in/install.sh is the shared install helper used by both postCreateCommand (B) and the automations task (C). It skips silently if the binary is already present; set FORCE=true to reinstall.

Both services/sync-in/start.sh and services/sync-in/install.sh are scaffold-only includes in all four template manifest profiles — consumers receive them on first sync, subsequent syncs skip them if already present.

Sync-in workflow (sync-in.yml)

Manages the Sync-in server/client lifecycle. Every devcontainer starts a local Sync-in server automatically via the sync-in-server automation service (port 3284, admin token at ~/.local/share/sync-in/.admin_token).

Enable/disable toggle — vars.SYNC_IN_ENABLED:

Set as a repo Actions variable (not a secret — it's plain text):

# Enable
gh api --method POST /repos/{owner}/{repo}/actions/variables \
  -f name="SYNC_IN_ENABLED" -f value="true"

# Disable (maintenance mode)
gh api --method PATCH /repos/{owner}/{repo}/actions/variables/SYNC_IN_ENABLED \
  -f value="false"

Decision matrix in secrets-check job:

Required secrets (only needed when SYNC_IN_ENABLED=true):

• SYNC_IN_SERVER_URL — public URL of the Sync-in instance (must be reachable by GitHub Actions runners — localhost:3284 only works from inside the container)
• SYNC_IN_ADMIN_TOKEN — admin token from ~/.local/share/sync-in/.admin_token

Federated mesh — config/sync-in-peers.yml is the peer registry. Each entry declares a node's node_id, secret names for its URL and token, role (server/client/both), and managed orgs. The register-with-peers action in sync-in-client.sh announces this node to each peer's /api/v1/peers endpoint. Dispatch with role=register-peers or role=all.

Devcontainer SDK workflow (devcontainer-sdk.yml)

Three modes, selectable via workflow_dispatch:

Supporting scripts: scripts/devcontainer-validate.py, scripts/devcontainer-build.sh, scripts/devcontainer-publish-features.sh, scripts/devcontainer-base-image.py.

Verify Fork Integrity

verify-fork-integrity.yml / scripts/verify-fork-integrity.sh — single-repo equivalent of verify-mirror-integrity.yml. Compares this repo's default-branch HEAD against its upstream (fork parent or upstream_override).

Upstream resolution order:

1. inputs.upstream_override (workflow dispatch input)
2. .ota/config.yml upstream_override field
3. GitHub fork parent API field (auto-detected)

Returns status: identical | ahead | behind | diverged. Set BLOCK_ON_DRIFT=true to exit 1 on behind or diverged.

OTA system — autonomous upstream resolution

Both ota-self-update.yml and ota-opt-in.yml now resolve their upstream dynamically rather than hardcoding Interested-Deving-1896/fork-sync-all:

ota-opt-in.yml writes the resolved upstream into .ota/config.yml as upstream_override so subsequent ota-self-update.yml runs use Check 1 (zero API calls for resolution).

ota-opt-in.yml opens the registration issue against the resolved upstream repo (not hardcoded fork-sync-all). The upstream repo must have an ota-registration label and a config/ota-registry.yml for the issue to be actionable.

resolve-failures.sh — EXCLUDED_REPOS convention

EXCLUDED_REPOS in scripts/resolve-failures.sh is intentionally empty. The resolver appends [skip ci] to every fix commit, which prevents CI re-triggers in all standard repos. Only add a repo to EXCLUDED_REPOS when [skip ci] is genuinely insufficient — for example, a repo with a push hook that ignores [skip ci] and would cause an infinite fix→trigger→fail→fix loop.

README & repo description management — autonomous single-repo mode

In autonomous mode (fork-sync-all not present), README workflows scope to the current repo only:

• update-readmes.sh: set SINGLE_REPO=<repo-name> to bypass the org fetch and process exactly one repo. update-readmes.yml sets this automatically via the FSA mode check.
• translate-readmes.sh: SCOPE=single sets REPOS to the current repo name (extracted from GITHUB_REPOSITORY). translate-readmes.yml sets this automatically in autonomous mode.

resolve-failures.sh — rate-limit rerun

Before sending a failed run to the AI fixer, resolve-failures.sh calls rerun_if_rate_limited(), which checks job logs for rate-limit signal patterns and re-triggers via POST /repos/{owner}/{repo}/actions/runs/{id}/rerun-failed-jobs. This covers all three orgs (I-D-1896 OSP-bound, OSP, OOC). The loop guard checks for "rate_limit_rerun": "true" in the step summary — a second rate-limit failure is logged but not re-triggered again.

Template sync profiles

config/template-consumers.yml controls which repos receive automatic file updates from sync-template.yml. Each consumer has a profile that determines what gets injected.

Profile assignments

Critical rule

Never assign mirror profile to consumer repos. The mirror profile injects the full fork-sync-all mirror/sync suite (60+ workflow files, 100+ scripts) into repos that are targets of the mirror chain, not operators of it. This causes template pollution — files that have no purpose in the target repo and clutter its .github/workflows/ and scripts/ directories.

Template pollution cleanup

If a repo has been polluted by the mirror profile:

1. Check which files don't belong:

for f in .github/workflows/*.yml; do
  grep -q "SYNC_TOKEN\|openos-project\|mirror-to-osp\|registered-imports" "$f" \
    && echo "POLLUTION: $(basename $f)" \
    || echo "native:    $(basename $f)"
done

2. Remove them with git rm --cached and commit:

git rm --cached .github/workflows/add-mirror-repo.yml  # etc.
git commit -m "chore: remove fork-sync-all template pollution"

3. Delete the untracked files from disk:

git status --short | grep "^??" | awk '{print $2}' | xargs rm -f

4. Trigger cleanup-pollution.yml (workflow_dispatch) to clean remaining consumer repos automatically.

Repos cleaned of mirror pollution (2026-06-06)

• KPort — 74 files removed
• btrfs-dwarfs-framework — 133 files removed
• All other infra-core consumers — cleaned via cleanup-pollution.yml

Queue pile-up pattern

Workflows that trigger on .github/workflows/** (e.g. validate-config, update-workflow-triggers-doc) must have concurrency: cancel-in-progress: true to prevent stacking. Without it, rapid pushes create a queue of identical runs that consume quota on every reset, causing a deadlock where the queue can't drain because quota is always 0.

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

Brandable backend

config/brand.yml allows fork-sync-all to be adopted as a white-label subsystem. When brand.enabled=true, sync-template.sh substitutes {{FSA_*}} tokens in propagated file content with the consumer's own identity values.

Default state: brand.enabled=false — no behaviour change until a consumer explicitly opts in by setting enabled: true in their own config/brand.yml.

Substitution tokens

Applying brand substitution

scripts/apply-brand.py reads config/brand.yml and rewrites tokens in a target file. Called by sync-template.sh after writing each propagated file when brand.enabled=true.

python3 scripts/apply-brand.py path/to/file.yml

skin.files overrides

The skin.files list in config/brand.yml maps source files to destination paths in consumer repos, applied after the profile include list. Entries are scaffold-only by default (scaffold_only: true). Set scaffold_only: false to always overwrite.

Git subtree / submodule / umbrella scaffold

config/subtree-manifest.yml declares three relationship types between this repo and external repos. scripts/manage-subtrees.sh implements all operations. manage-subtrees.yml runs weekly (Sunday 01:00 UTC) and on manual dispatch.

Relationship types

manage-subtrees.sh commands

bash scripts/manage-subtrees.sh sync          # pull all subtrees + update all submodules
bash scripts/manage-subtrees.sh add <name>    # add a new subtree/submodule from manifest
bash scripts/manage-subtrees.sh status        # show drift vs upstream for all entries
bash scripts/manage-subtrees.sh umbrella-init # initialise umbrella children as submodules

Adding a new entry

Add to the appropriate list in config/subtree-manifest.yml, then run manage-subtrees.sh add <name>. Do not run git subtree add or git submodule add manually — the script handles squash flags, shallow clones, and .gitmodules consistency.

Nested submodule policy

nested.recurse=false by default. Enable only when a submodule itself has submodules you need. nested.max_depth=2 prevents runaway recursion.

OSP-bound repo list

The canonical list of ~49 repos that are mirrored to GitLab lives in config/gitlab-subgroups.yml. Parse it with yaml.safe_load — do not hardcode repo names anywhere else.

To get the list in bash:

python3 -c "
import yaml
data = yaml.safe_load(open('config/gitlab-subgroups.yml'))
for sg in data.get('subgroups', {}).values():
    for repo in (sg.get('repos') or []):
        print(repo)
"

GitLab subgroup IDs

OSP leg — openos-project (gitlab.com/openos-project)

All IDs are authoritative — sourced from config/gitlab-subgroups.yml. Do not hardcode them elsewhere.

OOC leg — openos-project-ooc-ecosystem (gitlab.com/openos-project-ooc-ecosystem)

Root group ID: 134901804

OOC subgroup names mirror OSP exactly — same slugs, different GitLab group. Config: config/gitlab-subgroups-ooc.yml.

All IDs are authoritative — sourced from config/gitlab-subgroups-ooc.yml.

Subgroup mirroring convention: when adding a new subgroup to the OSP config, add the same slug to the OOC config with id: null and repos: []. The two repos: lists are populated independently — OSP repos and OOC repos are distinct even when they share a subgroup name.

README & Repo Description Management

AI marker format

<!-- AI:start:section-name -->
content
<!-- AI:end:section-name -->

Eight AI-owned sections: what-it-does, architecture, ci, mirror-chain, contributors, origins, resources, license.

Human-owned sections (Install, Usage, Configuration, License) never get AI markers — they get placeholder HTML comments on first creation.

Three modes in update-readmes.sh

• rewrite — no AI markers present → build full template from scratch
• fill — some markers present but missing sections → inject missing ones
• update — all markers present → regenerate AI section content

check-readme-render.sh

Run this against any README before committing. It catches: leaked log lines, unclosed fences, unclosed AI markers, empty sections, missing H1, broken tables, bare [text] links, raw angle brackets.

bash scripts/check-readme-render.sh path/to/README.md

Per-file repo descriptions (generate-repo-descriptions.sh)

Generates a one-line AI description for every file in a repo and commits the results to DESCRIPTIONS.md. Uses GitHub Models (gpt-4o-mini by default — high volume, short outputs, no frontier reasoning needed).

Inspired by ioncakephper/repo-description — reimplemented using llm.sh (GitHub Models) instead of Groq + Node.js.

Output format (DESCRIPTIONS.md):

# File Descriptions
<!-- AI:generated -->

| File | Description |
|---|---|
| `scripts/sync-forks.sh` | Syncs all upstream forks via the GitHub merge-upstream API |
| `config/gitlab-subgroups.yml` | Maps OSP-bound repos to their GitLab subgroup placement |

Workflow: generate-repo-descriptions.yml — runs weekly (Sunday 03:30 UTC), dispatches manually with target_repo, model, max_files, file_filter inputs. SKIP_EXISTING=true by default so incremental runs only describe new files.

Key env vars:

• TARGET_REPO — repo to describe (defaults to fork-sync-all itself on schedule)
• MAX_FILES — cap per run (default: 200) to control quota consumption
• MODEL — override model (default: openai/gpt-4o-mini)

Repo settings management (manage-repo-settings.sh)

Declarative repo settings drift detection and enforcement across all OSP-bound repos. Reads config/repo-settings.yml and either reports drift (check mode) or enforces declared state (apply mode) via the GitHub REST API.

Inspired by andrewthetechie/gha-repo-manager — reimplemented as a shell script using gh-api.sh + budget.sh infrastructure.

Settings file: config/repo-settings.yml — defaults block applies to all repos, overrides block provides per-repo overrides, skip list excludes repos.

Supported fields: description, homepage, has_issues, has_projects, has_wiki, has_discussions, allow_squash_merge, allow_merge_commit, allow_rebase_merge, allow_auto_merge, delete_branch_on_merge, squash_merge_commit_title, squash_merge_commit_message, topics, vulnerability_alerts.

Workflow: manage-repo-settings.yml — runs weekly in check mode (Monday 04:30 UTC). Apply mode is manual-only (workflow_dispatch with mode: apply) to prevent accidental bulk changes.

API cost: 1 REST call per repo in check mode. 1–3 REST calls per drifted repo in apply mode (PATCH settings + PUT topics + PUT/DELETE vulnerability alerts).

GitLab CI variables

These must be set as masked CI/CD variables in the openos-project/fork-sync-all GitLab project settings (not GitHub secrets):

Headroom proxy

A context compression proxy runs on port 8787 (started automatically via .ona/automations.yaml). To use it with Claude:

ANTHROPIC_BASE_URL=http://localhost:8787 claude
# or
headroom wrap claude

Check savings: headroom stats

Token rotation

Tracked tokens

The "PAT name" column is the display name shown at github.com/settings/tokens (classic).

| ACTIVITYSMITH_API_KEY | n/a (external service) | ActivitySmith API | ActivitySmith | unknown | full-chain-flush.yml (live activity tracking) — optional, skipped if unset | manual | | ACTIVITYSMITH_CHANNELS | n/a (external service) | ActivitySmith channel IDs | ActivitySmith | n/a | full-chain-flush.yml — optional, skipped if unset | manual | | ANTHROPIC_API_KEY | n/a (external service) | Anthropic API | Anthropic | n/a | validate-config.yml (AgentShield scan) — optional, skipped if unset | manual |

How to rotate a repo secret (SYNC_TOKEN, GH_SYNC_TOKEN, etc.)

1. Generate a new PAT at https://github.com/settings/tokens
2. Go to rotate-token.yml → Run workflow
3. Select the secret name from the dropdown
4. Paste the new token value into the token_value field
5. Leave validate checked — it confirms the token works before finishing
6. After the run completes, update the expiry date in this table

How to rotate an OSP org secret (ORG_MIRROR_OSP_TO_OOC, MIRROR_TOKEN)

OSP org secrets live in OpenOS-Project-OSP and require a token with admin:org on that org. SYNC_TOKEN only covers Interested-Deving-1896.

The rotate-token.yml workflow resolves the OSP token automatically in this priority order:

Option 1 — GitHub App (preferred, permanent)

A GitHub App installation token never expires and has fine-grained permissions.

One-time setup:

1. Create a GitHub App at https://github.com/settings/apps/new
   • Name: fork-sync-all-osp-rotator (or similar)
   • Permissions: Organization secrets → Read and write
   • Uncheck everything else
2. Install the App on OpenOS-Project-OSP org
3. Note the App ID (shown on the app settings page)
4. Generate a private key (PEM format) from the app settings page
5. Add two repo secrets to Interested-Deving-1896/fork-sync-all:
   • OSP_APP_ID — the numeric App ID
   • OSP_APP_PRIVATE_KEY — the full PEM contents (including header/footer)
6. Run rotate-token.yml — it will use the App automatically

Option 2 — Dedicated PAT (bridge until App is set up)

1. Generate a new PAT at https://github.com/settings/tokens with:
   • admin:org scope
   • Authorized for OpenOS-Project-OSP org (SSO authorize if required)
2. Add it as repo secret OSP_ADMIN_TOKEN in Interested-Deving-1896/fork-sync-all
3. Run rotate-token.yml — it will use OSP_ADMIN_TOKEN automatically

Option 3 — Manual fallback

If neither OSP_APP_* nor OSP_ADMIN_TOKEN is set, the workflow prints the exact error and the two options above. You can also update manually:

1. Generate a new PAT with admin:org on OpenOS-Project-OSP
2. Go to OSP org secrets and update the secret value directly
3. Update the expiry date in scripts/token-monitor.sh (OSP_ORG_SECRETS array) and in the table above

⚠️ Upcoming rotations (as of 2026-06-08):

• ADD_MIRROR_REPO_SYNC — expires 2026-08-13 (66 days). token-health.yml will open an issue around 2026-06-29.
• MIRROR_TOKEN / ORG_MIRROR_OSP_TO_OOC — expire 2026-09-01 (85 days). Alert ~2026-07-17.
• SYNC_TOKEN — expires 2026-09-02 (86 days). Alert ~2026-07-18.
• GH_SYNC_TOKEN / OSP_ADMIN_TOKEN — expire 2026-09-03 (87 days). Alert ~2026-07-19.

Automated monitoring

token-health.yml runs weekly (Monday 09:00 UTC) and warns at 45 days before expiry. When a token needs attention it opens a GitHub issue labelled token-monitor. Run it manually at any time to get a current status report.

vendor/ conventions

Agnostic-by-default rule

Everything imported into vendor/ must be deployment-agnostic. No distro names, org-specific URLs, org/repo slugs, or arch/repo paths may appear as hardcoded fallback values in shell ${VAR:-...}, YAML || '...', or TypeScript ?? '...' expressions. All deployment-identity values belong in CI variables or repo vars set per deployment.

Enforcement

scripts/check-vendor-agnostic.sh scans a vendor directory and exits 1 on violations:

bash scripts/check-vendor-agnostic.sh vendor/infra-dashboard   # specific component
bash scripts/check-vendor-agnostic.sh vendor                   # all of vendor/

enforce-agnostic-vendor.yml runs this automatically on every push/PR touching vendor/.

To suppress a specific line that is intentionally non-agnostic:

SOME_VAR="${SOME_VAR:-specific-value}"  # check-vendor-agnostic: ignore

What the checker flags vs. allows

Flagged (deployment-identity):

• Public URLs as fallbacks: ${VITE_ENDPOINT_URL:-https://api.myorg.com}
• Org/repo slugs: ${MIRRORLIST_REPO:-MyOrg/my-repo}
• Arch/repo paths: ${MIRROR_REPO_PATHS:-x86_64/core,x86_64/extra}
• Bare distro names: ${DISTRO:-cachyos}, ${DISTRO:-ubuntu}

Allowed (generic defaults):

• Localhost dev URLs: ${API_URL:-http://localhost:5862}
• Generic relative paths: ${MIRRORLIST_PATH:-mirrorlist/mirrorlist}
• Single-word tokens: ${LOG_LEVEL:-info}, ${ENV:-production}
• UI strings: ${APP_NAME:-Infra Dashboard}

Workflow integrations

import-repo → immediate sync

When ongoing_sync=true, import-repo.sh writes to registered-imports.json and then immediately dispatches sync-registered-imports.yml with repo_filter=<name> and force_sync=true. This avoids the up-to-6h wait for the scheduled run to pick up the new entry.

If the dispatch fails (quota, permissions), it falls back gracefully — the entry is still registered and will sync on the next scheduled run.

merge-to-monorepo → OSP mirror chain

merge-to-monorepo.yml has a mirror_monorepo boolean input (default: false). When set, it dispatches add-mirror-repo.yml for the newly created monorepo after a successful merge, entering it into the standard OSP mirror chain automatically.

Action version pinning

Canonical versions (verified 2026-06-24). Use these exactly — do not downgrade, do not guess from memory.

Before adding a new action or bumping a version, verify with:

curl -sf "https://api.github.com/repos/actions/checkout/releases/latest" \
  -H "Authorization: token $GH_TOKEN" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['tag_name'])"

History: This repo has had repeated bulk regressions from agents writing versions from memory. checkout moved v4→v5→v6→v7 across sessions; each transition caused a mass failure. The table above is the single source of truth — update it here when versions change, then do a bulk find-replace across .github/workflows/.

GitHub Actions expression and permissions constraints

These are constraints GitHub's own validator enforces that pyyaml does not catch locally. All three produce the same symptom: the run shows "This run likely failed because of a workflow file issue" with 0s duration — the runner never starts.

Diagnose with:

gh workflow run <workflow-file>.yml --repo <owner>/<repo> [--field key=val]
# HTTP 422 response body contains the exact line/col and error message

Secrets not allowed in if: conditions

# ❌ GitHub rejects this — secrets context unavailable in if: expressions
- name: Deploy via SSH
  if: ${{ secrets.SSH_KEY != '' }}

# ✅ Use an env var and branch in the run: block instead
- name: Deploy
  env:
    SSH_KEY: ${{ secrets.SSH_KEY }}
  run: |
    if [[ -n "$SSH_KEY" ]]; then
      # SSH path
    else
      # fallback path
    fi

Invalid permissions: scopes

GitHub Actions only accepts a specific set of permission scopes. secrets and variables are not valid — they will cause a parse failure.

# ❌ Both of these are rejected
permissions:
  secrets: write
  variables: write

# ✅ Valid scopes only
permissions:
  contents: read
  actions: read
  # Full list: actions, checks, contents, deployments, id-token, issues,
  # discussions, packages, pages, pull-requests, repository-projects,
  # security-events, statuses, workflows

Note: writing repo variables requires the actions: write scope (via the Actions API), not a dedicated variables scope.

Dynamic step outcome access (steps[var].outcome)

GitHub Actions expressions do not support dynamic property access via variables. steps[check].outcome where check is a shell variable is rejected.

# ❌ Rejected — dynamic bracket access not supported
- name: Summarise
  run: |
    for check in check_yaml check_guards; do
      result="${{ steps[check].outcome }}"
    done

# ✅ Pass all step outcomes via toJSON(steps) and read with python3
- name: Summarise
  env:
    STEPS_JSON: ${{ toJSON(steps) }}
  run: |
    for check in check_yaml check_guards; do
      result=$(echo "$STEPS_JSON" | python3 -c \
        "import json,sys; d=json.load(sys.stdin); print(d.get('${check}',{}).get('outcome','skipped'))")
    done

workflow_run trigger + reusable workflow call (uses:)

GitHub prohibits calling a reusable workflow from a workflow_run-triggered workflow. The combination produces startup_failure (0s duration, "workflow file issue") even though the YAML is syntactically valid and pyyaml accepts it.

# ❌ startup_failure — workflow_run + reusable call is forbidden
on:
  workflow_run:
    workflows: ["Validate Config"]
    types: [completed]
jobs:
  guard:
    uses: ./.github/workflows/pr-lifecycle-guard.yml  # NOT allowed

Fix: inline the reusable workflow's logic as steps in the calling job. schedule and workflow_dispatch triggers are unaffected — only workflow_run has this restriction.

Detection: scan for the combination with:

python3 -c "
import re, pathlib
for wf in pathlib.Path('.github/workflows').glob('*.yml'):
    c = wf.read_text()
    if re.search(r'^\s+workflow_run:', c, re.MULTILINE) and \
       re.search(r'^\s{4}uses:\s+\./', c, re.MULTILINE):
        print(wf.name)
"

actions/checkout must precede quota-snapshot.sh

scripts/includes/quota-snapshot.sh sources time_format.py via a path relative to BASH_SOURCE[0]. Without actions/checkout the script file does not exist on the runner and the source call fails with No such file or directory.

Rule: in every job that sources quota-snapshot.sh, actions/checkout must be the first step.

# ✅ correct
steps:
  - uses: actions/checkout@v7
  - name: Quota pre-flight
    run: |
      source scripts/includes/quota-snapshot.sh
      quota_snapshot

# ❌ wrong — source fails before checkout runs
steps:
  - name: Quota pre-flight
    run: |
      source scripts/includes/quota-snapshot.sh   # file not found
      quota_snapshot
  - uses: actions/checkout@v7

validate-workflow-guards.py Check 7 detects this automatically. Run it after adding any new workflow that uses quota-snapshot.sh.

SUBGROUPS_CONFIG relative path and cd into work dirs

scripts/mirror-osp-to-gitlab.sh does cd "$work_dir" into a git mirror clone. Any relative path passed via env var before that cd will break.

The workflow passes SUBGROUPS_CONFIG: config/gitlab-subgroups-ooc.yml (relative). The script now resolves it to absolute at startup:

_raw="${SUBGROUPS_CONFIG:-config/gitlab-subgroups.yml}"
if [[ "${_raw}" != /* ]]; then
  GL_SUBGROUP_CONFIG="${REPO_ROOT}/${_raw}"
else
  GL_SUBGROUP_CONFIG="${_raw}"
fi

General rule: resolve any env-var path to absolute before any cd that could change the working directory.

Incus daemon and runner capabilities

The incusd service and sync-in-server service require Linux capabilities that are not available on standard Ona Cloud runners. This section documents what is needed and how to enable it.

Capability requirements

On standard Ona Cloud runners the incusd service will fail to start with CAP_SYS_ADMIN not available. The Incus client (incus CLI) is still installed and can manage remote Incus servers.

Enabling on a self-hosted runner

To run incusd locally in the devcontainer, the runner VM must:

1. Expose capabilities — run the devcontainer with --privileged or grant CAP_SYS_ADMIN + CAP_NET_ADMIN + seccomp=unconfined.
2. Enable nested virtualization — for KVM-accelerated VMs, the host must have vmx/svm CPU flags and expose /dev/kvm to the container. Without KVM, Incus falls back to QEMU TCG (software emulation — slower but functional for testing and image building).
3. Expose /dev/fuse — for fuse-overlayfs rootfs driver.

On AWS, use a metal instance type (e.g. c5.metal) or an instance with nested virtualization enabled. On GCP, enable "Enable nested virtualization" in the VM configuration.

Service startup order

When the runner supports it, start services in this order:

gitpod automations service start incusd        # starts incusd, runs incus admin init --auto
gitpod automations service start sync-in-server # launches syncin/server via incus launch docker:...

sync-in-server calls incus info at startup and exits immediately if incusd is not running.

OCI image source

Sync-in/server is published to Docker Hub as syncin/server (tags: latest, 2, 2.4.1, etc.). Incus pulls it via docker:syncin/server:latest using its built-in OCI image support — no Docker daemon required.

The ./features/incus/install.sh feature detects capabilities at build time:

• If CAP_SYS_ADMIN + CAP_NET_ADMIN are present → installs full daemon from zabbly daily channel + QEMU
• Otherwise → installs client only from zabbly stable channel

Known pitfalls

• fill_missing_sections case statement — must handle all 8 AI sections. If you add a new section to ALL_AI_SECTIONS, add it to the case in fill_missing_sections, rewrite_readme, and the update mode loop.

• sync-registered-imports.sh does not create repos — ensure_gh_repo() handles creation now, but the target repo must be reachable via the GitHub API. New entries in registered-imports.json will auto-create the repo on first run.

• GitLab mirror chain — two independent legs:

  • OSP leg: I-D-1896 → OpenOS-Project-OSP (GitHub) → openos-project (GitLab)
  • OOC leg: OpenOS-Project-Ecosystem-OOC (GitHub) → openos-project-ooc-ecosystem (GitLab)

  Adding a repo to gitlab-subgroups.yml (OSP) or gitlab-subgroups-ooc.yml (OOC) is required for GitLab mirroring on the respective leg. Adding to registered-imports.json is required for upstream sync. All three are independent — a repo can be in any combination.

• _inter_repo_sleep in update-readmes.sh — quota-aware pacing. No delay when quota > 2000; scales to 30s when < 500. The cached _quota_remaining variable is decremented by 10 per repo to trigger re-checks before actually hitting the threshold.

FSA-API

fsa-api/ is a two-layer HTTP API over the fork-sync-all control plane. Full reference: fsa-api/README.md. Key conventions for agents:

Layer structure

fsa-api/uaa/          — Unified Agnostic API (generic, platform-agnostic)
fsa-api/core/         — FSA-specific adapters (GitHub-org-specific)
fsa-api/config/       — fsa-routes.yml + fsa-toggles.yml + fsa-deployments.yml
fsa-api/server/       — fsa-start.sh (merges both route files)

Never put FSA-specific logic in fsa-api/uaa/. UAA is propagated to consumer repos via sync-template.sh. FSA-specific adapters belong in fsa-api/core/adapters/<domain>/.

Adding an adapter

Every new adapter must:

1. Source fsa-adapter.sh (not adapter.sh directly)
2. Call fsa_quota_check N before any API calls
3. Check its toggle with toggle_enabled <name> if the domain has one
4. Have a route entry in fsa-api/config/fsa-routes.yml
5. Pass python3 scripts/validate-workflow-guards.py with zero warnings

#!/usr/bin/env bash
# GET /api/fsa/<domain>/<resource>
source "$(dirname "${BASH_SOURCE[0]}")/../../lib/fsa-adapter.sh"

fsa_quota_check 50 || exit 0
toggle_enabled my_toggle || { fsa_error "disabled" 503; exit 0; }
# ... logic ...
fsa_ok '{"result":"..."}'

shared.sh — UAA ↔ FSA sync point

fsa-api/uaa/lib/shared.sh is sourced by both uaa/lib/adapter.sh and fsa-api/core/lib/fsa-adapter.sh. It contains platform-agnostic logic shared between the two layers:

• Toggle system: toggle_get / toggle_enabled / toggle_set / toggle_list reads UAA_TOGGLES_FILE (set to fsa-api/config/fsa-toggles.yml by FSA)
• Quota guard: quota_check N / quota_fetch — FSA overrides quota_fetch() with the GitHub-specific implementation; UAA defaults to 9999 (unlimited)
• JSON helpers: json_ok / json_error / json_list — fsa_ok / fsa_error / fsa_list are aliases kept for backward compatibility
• Route merge: merge_routes_files FILE... — merges multiple route manifests
• Capability registry: register_capability / list_capabilities

When adding logic that is genuinely platform-agnostic (no GitHub/GitLab coupling), add it to shared.sh so both UAA consumers and FSA adapters benefit. When adding logic that is GitHub-specific, add it to fsa-adapter.sh only.

Platform-agnostic adapters (fsa_platform_init)

fsa-adapter.sh sources scripts/includes/platform-adapter.sh. Every FSA adapter can switch platforms by calling fsa_platform_init:

fsa_platform_init gitlab          # switches to GitLab, selects GITLAB_TOKEN
pa_list_repos "openos-project"    # uses GitLab API
fsa_platform_init github          # switch back

Token selection is automatic: github→GH_TOKEN, gitlab→GITLAB_TOKEN, gitea→GITEA_TOKEN, forgejo→FORGEJO_TOKEN, codeberg→CODEBERG_TOKEN.

workflows/list.sh and workflows/run.sh have platform branches for all 5 platforms. New workflow-management adapters should follow the same pattern: check PA_PLATFORM and branch accordingly.

Deployment registry (config/fsa-deployments.yml)

Single source of truth for all known FSA instances. The deployments adapter domain reads this file — do not hardcode deployment coordinates in adapters.

deployments:
  - id: source
    platform: github
    org: Interested-Deving-1896
    ...
  - id: osp-gitlab
    platform: gitlab
    group_path: openos-project/ops
    ...

When a new FSA instance is created (new org, new platform), add it here. The /api/fsa/deployments/* routes and codebase/drift will pick it up automatically.

codebase/sync dispatch rule

POST /api/fsa/codebase/sync always dispatches on the source repo (Interested-Deving-1896/fork-sync-all), never on FSA_REPO. The source workflow (sync-fsa-forks.yml) then pushes updates to all mirrors. force=true dispatches critical-deploy-gitlab.yml instead (direct git push, bypasses mirror sync chain — use for emergency GitLab mirror recovery).

Route manifest conventions

fsa-api/config/fsa-routes.yml extends the UAA route format. Fields:

- path: /api/fsa/<domain>/<resource>
  script: core/adapters/<domain>/<verb>.sh
  method: GET|POST|PUT|DELETE
  auth: true          # require FSA_API_TOKEN header (write operations)
  toggle: <name>      # gate on fsa-toggles.yml entry
  # comment describing query params or body shape

fsa-start.sh merges fsa-api/uaa/config/routes.yml + fsa-api/config/fsa-routes.yml using shared.sh's merge_routes_files(). Last writer wins on path+method conflicts.

Platform adapter (platform-adapter.sh)

scripts/includes/platform-adapter.sh provides a uniform interface for interacting with any supported git hosting platform so that sync scripts can be written once and work against any backend.

Supported platforms: github | gitlab | gitea | forgejo | codeberg

Initialisation — must be called before any other pa_* function:

PLATFORM=gitlab PLATFORM_TOKEN="$GITLAB_TOKEN" pa_init gitlab
# With self-hosted host override:
PLATFORM=gitea PLATFORM_TOKEN="$TEA_TOKEN" pa_init gitea https://gitea.myco.com

Sets PA_HOST, PA_API, PA_AUTH_HEADER, PA_CLONE_PREFIX as internal state. Guard against double-sourcing is in place (_PLATFORM_ADAPTER_LOADED).

Public functions:

Rate-limit retry — pa_api_get retries HTTP 429/403 up to 3 times with reset-aware backoff. Reads X-RateLimit-Reset (GitHub/Gitea/Forgejo) or RateLimit-Reset (GitLab) from response headers; falls back to 60s if absent.

Auth header format per platform:

• GitHub: Authorization: token TOKEN
• GitLab: PRIVATE-TOKEN: TOKEN
• Gitea/Forgejo/Codeberg: Authorization: token TOKEN

Clone URL prefix per platform:

• GitHub: https://x-access-token:TOKEN@github.com
• GitLab: https://oauth2:TOKEN@gitlab.com
• Gitea/Forgejo/Codeberg: https://x-access-token:TOKEN@HOST

git-platform-sync.sh is the primary consumer. It uses pa_init twice per sync leg (once for source, once for dest) and calls pa_list_repos, pa_repo_exists, pa_clone_url, pa_push_url, and pa_create_repo. The git-platform-sync.yml workflow replaces the deprecated sync-to-gitlab.yml (direction=push) and sync-from-gitlab.yml (direction=pull) — both are now no-op stubs kept only for workflow_run name resolution.

Template consumer tiers

config/template-consumers.yml has a tier field that controls whether sync-template.sh may write to a repo:

• tier: protected — skipped in all three modes (create, inject, propagate). Used for fork-sync-all itself and all its mirrors (OSP GitHub, OOC GitHub, both GitLab groups). These repos receive updates via the mirror chain, not direct template injection. Adding a new fork-sync-all mirror: list it here with tier: protected — no script changes needed.
• tier: managed — normal sync target (default when omitted).

The guard is enforced at three layers:

1. scripts/sync-template.sh — reads tier from the YAML parser (line 10 of the record format); skips protected entries in all three run_ functions.
2. .github/workflows/sync-template.yml — validate job calls check_protected() and rejects protected targets before any runner runs.
3. config/template-consumers.yml — prominent comment at the top of the file.

Known pitfall: sync-template.sh CREATE mode cannot read tier from the consumers file for a repo that doesn't exist yet. It does a runtime lookup against the consumers file by name — so a new fork-sync-all mirror must be added to template-consumers.yml with tier: protected before anyone attempts to CREATE it via sync-template.

sync-template contamination — what happened and how it's prevented

In June 2026, sync-template.sh was run with fork-sync-all as a target (either CREATE or INJECT mode). Because the script runs from a fork-sync-all checkout and copies the working tree into the target, this committed ~224 eggs-ai application source files (src/, bin/, myclaw/, install.sh, package.json, etc.) directly into fork-sync-all over several weeks.

Root causes fixed:

1. fork-sync-all was listed in template-consumers.yml as a managed consumer with profile: full — removed and replaced with tier: protected.
2. No guard existed in the script or workflow against self-targeting — added (see Template consumer tiers above).
3. mirror.yaml (a raw git-push mirror introduced via the contamination) was pointing at Interested-Deving-1896/eggs-ai instead of the OSP mirror — removed entirely (superseded by mirror-to-osp.yml).
4. actions/checkout@v6 (non-existent) was in 113 workflow files — replaced with @v4 across all workflows.

If you see chore: add template file <eggs-ai-path> [skip ci] commits in the log, the contamination has recurred. The fix is to revert those commits and verify the tier guard is in place.

GitLab token scopes

Two different tokens are used for GitLab operations:

GITLAB_SYNC_TOKEN is not injected into Ona environments — it only exists as a GitHub Actions secret. Any operation that needs to push to GitLab must be done via a dispatched workflow, not directly from an agent environment.

GITLAB_TOKEN in the Ona environment has zero length if the project secret wasn't set at environment creation time. Check with echo ${#GITLAB_TOKEN}.

Auto-merge PRs

scripts/auto-merge-prs.sh merges open PRs once their required checks pass. Three hybrid detections run per PR at runtime — no static configuration needed.

Scope detection (which PRs to merge)

Priority order — first match wins:

1. Label auto-merge present → merge (explicit opt-in)
2. PR author login ends in [bot], or matches the SYNC_TOKEN owner → merge (automation output)
3. AUTO_MERGE_ALL=true env var → merge all open PRs
4. Default → skip (human PRs require explicit opt-in)

Bot detection uses the token owner resolved via GET /user at startup (1 API call, cached for the run). Any login matching *[bot] is also treated as a bot regardless of token ownership.

Strategy detection (how to merge)

Per-PR, based on commit history (GET /repos/{repo}/pulls/{n}/commits):

• Single commit → rebase (linear history, no merge commit)
• Multiple commits, single author → squash (clean history)
• Multiple commits, multiple authors → merge (preserves attribution)

Override with MERGE_STRATEGY=squash|rebase|merge.

Mechanism detection (when to fire)

Detected once per run via GET /repos/{repo}/branches/{base}/protection:

• Required status checks configured → native auto-merge (gh pr merge --auto). GitHub queues the merge and fires it exactly when checks pass. Zero polling, no runner time consumed waiting.
• No branch protection / no required checks → poll mergeable_state until clean, then merge directly. Polls every POLL_INTERVAL_SEC (default 30s) up to POLL_TIMEOUT_MIN (default 30min).

Override with MERGE_MECHANISM=native|poll.

Workflow trigger

auto-merge-prs.yml fires on:

• workflow_run completion of Validate Config with conclusion == success (primary — fires immediately after CI passes on any PR)
• Schedule every 2h at :55 (fallback for PRs already green before the workflow existed)
• workflow_dispatch with optional pr_filter (comma-separated PR numbers)

Registered: tier 3 MEDIUM, min_quota: 300.

Architecture

The three-org chain

fork-sync-all is the control plane for a three-organisation mirror chain on GitHub, with a fourth leg into GitLab:

Interested-Deving-1896  ──►  OpenOS-Project-OSP
        ▲                           │
        │                           ▼
        │              OpenOS-Project-Ecosystem-OOC
        │                           │
        │                           ▼
        │                  GitLab openos-project
        │             (14 subgroups, 225 repos mirrored)
        │
        └──── upstream-commits / upstream-prs (OSP + OOC → I-D-1896)

All automation runs in Interested-Deving-1896/fork-sync-all. The other orgs are passive recipients — they do not run their own automation except for the GitLab CI mirror job that pushes back to GitLab.

Data flow

Inbound (upstream → I-D-1896)

Three paths bring upstream changes into Interested-Deving-1896:

1. sync-forks.yml (daily) — syncs all GitHub forks with their upstream parents
2. sync-registered-imports.yml (daily at 04:55 UTC) — re-syncs repos registered in registered-imports.json, including non-GitHub sources (GitLab, Bitbucket, Codeberg, etc.)
3. upstream-commits.yml / upstream-prs.yml (daily) — detects direct commits and open PRs in OSP/OOC that haven't been reflected upstream, and opens PRs in I-D-1896

Outbound (I-D-1896 → OSP → OOC → GitLab)

The mirror chain runs in sequence, each leg triggered by the previous:

mirror-to-osp.yml  ──►  mirror-osp-to-ooc.yml  ──►  GitLab CI (sync-to-gitlab.yml)
   (every 6h at :13)     (every 6h at :45)           (on OSP push)

flush-lifecycle.yml is the top-level entry point for a full pipeline run. It sets FLUSH_ACTIVE=true, holds a sentinel runner slot, and coordinates the three-stage sequence with quota reservation and pause/resume at reset windows:

flush-lifecycle.yml
  └─ pre-flush-prep.yml    ← cancels stale runs, merges PRs, validates config
  └─ full-chain-flush.yml  ← all mirror + README + CI stages in order
  └─ post-flush-prep.yml   ← integrity checks and queue health verification

full-chain-flush.yml orchestrates the pipeline stages themselves — mirror chain, README updates, sync, and validation — but should be triggered via flush-lifecycle.yml rather than directly, so the FLUSH_ACTIVE mutex and quota reservation are active for the full run.

GitLab subgroup placement

config/gitlab-subgroups.yml is the single source of truth for which repos go into which GitLab subgroup. The 14 subgroups map to topic areas:

Repos not listed in any subgroup fall into the ops default subgroup.

Quota management

Both GH_TOKEN and SYNC_TOKEN belong to the same GitHub user and share a single 5000 req/hr REST bucket. The system has three layers of protection:

quota-reserve.yml  ──►  queue-manager.yml
  (every 30 min)          (every 30 min)

quota-monitor.yml is a separate manual-dispatch-only tool for waiting out quota exhaustion. It is not part of the automatic quota management loop — see Operations for when and how to use it.

Workflow priority tiers are defined in config/workflow-priority-tiers.yml. Tier 1 (CRITICAL) runs are never cancelled. See Operations for the full quota reference.

Config files

vendor/

vendor/ contains third-party components that fork-sync-all hosts or deploys. It is distinct from scripts/ (first-party automation) and config/ (config data).

Current components:

All vendored components must be deployment-agnostic — no distro names, org-specific URLs, or hardcoded deployment values. See Contributing for the enforcement workflow.

Token architecture

Two GitHub PATs are in active use, both owned by the same user (ID 202036334) and sharing the same 5000 req/hr quota:

GitLab operations use GITLAB_SYNC_TOKEN (api, read/write_repository scope).

Token expiry is monitored weekly by token-health.yml. See Token Rotation for rotation procedures.

Workflow Triggers

All workflows in .github/workflows/. Grouped by function, with every trigger listed.

Plain-text version: DOCS/workflow-triggers.txt
Published: interested-deving-1896.github.io/fork-sync-all/workflow-triggers.html
Auto-generated on 2026-07-03 from .github/workflows/ and config/workflow-quota-costs.yml

Index

Jump to any section:

Quick links: Glossary · Schedule Summary · Source

Accessibility

AI & Cost Tracking

BDFS / Filesystem Workspace

Bugzilla Integration

Build & Release

CI & Failure Resolution

Documentation & Publishing

Fork & Import Sync

Full Pipeline

Git Platform Sync

Infrastructure & Environment

Maintenance & Housekeeping

Mirror Chain

OSP-Bound Repo Management

OTA System

PR Governance & Trust

Quota & Queue Management

README Management

Security & Compliance

Utility / On-Demand

Glossary

Key terms used in this document. Full glossary: DOCS/generated/glossary.md

dispatch : Manual workflow_dispatch trigger — run from the Actions UI or via gh workflow run.

workflow_run : Trigger that fires when another named workflow completes. Used to chain workflows.

quota pre-flight : Step that checks remaining REST quota before doing API work. Sets skip=true when below MIN_QUOTA.

MIN_QUOTA : Minimum remaining REST quota required before a workflow proceeds. Per-workflow value from workflow-quota-costs.yml.

OSP : OpenOS-Project-OSP — second org in the mirror chain (GitHub).

OOC : OpenOS-Project-Ecosystem-OOC — third org in the mirror chain (GitHub).

mirror chain : Three-org pipeline: Interested-Deving-1896 → OSP → GitLab.

DRY_RUN : When true, scripts print what they would do without making changes.

SYNC_TOKEN : Cross-org GitHub token. Shares the 5000 req/hr bucket with GH_TOKEN.

OTA : Over-the-air update system delivering workflow/config updates to consumer repos.

pre-flush-prep : Pre-flight workflow run before full-chain-flush.

full-chain-flush : End-to-end pipeline: pre-flush-prep → mirror chain → post-flush-prep.

priority tiers : Tier 1 CRITICAL → Tier 4 LOW. Controls queue-manager and quota-reserve cancellation order.

consumer repo : Repo receiving template files from fork-sync-all via sync-template.sh.

OSP-bound repo : Repo mirrored into OSP and managed by fork-sync-all.

Schedule Summary (UTC)

Workflow Scheduling Guide

Optimal trigger windows, quota requirements, and timing constraints for every scheduled workflow. Use this when deciding when to manually dispatch a workflow or when to adjust a cron schedule.

How to read this guide

Quota cost — REST API calls consumed per run (mid = typical, high = worst case). Source: config/workflow-quota-costs.yml. GraphQL calls count as 1 REST call regardless of how many repos are queried.

Best window — the UTC hour range where quota headroom is highest and concurrency with other workflows is lowest.

Avoid — hours where the scheduled burst is already high or where a dependency workflow hasn't finished yet.

Quota floor — the minimum remaining quota required before the workflow will run (from min_quota in config/workflow-quota-costs.yml). If quota is below this, the workflow skips itself and waits for the next reset.

Time format note

Per-workflow tables show two schedule columns:

• Schedule (UTC) — 24h UTC, the authoritative cron time
• Schedule (EST) — EST (UTC−5, Nov–Mar). Add 1h for EDT (UTC−4, Mar–Nov).

Example: 09:05 UTC = 4:05 AM EST = 5:05 AM EDT.

The timing map and "Best manual dispatch windows" tables use the full 24h UTC / 12h UTC / 12h ET (EST/EDT) format for completeness.

Daily quota budget

Check current quota before dispatching:

curl -sf -H "Authorization: token $SYNC_TOKEN" \
  "https://api.github.com/rate_limit" | \
  python3 -c "
import sys,json,datetime
d=json.load(sys.stdin)['resources']['core']
print(f\"remaining={d['remaining']}  resets={datetime.datetime.utcfromtimestamp(d['reset']).strftime('%H:%M UTC')}\")
"

Scheduled workflow timing map

All times UTC (24h) with 12h UTC and approximate ET equivalents. [*/2] = every other day (even days of month). (*/30) = every 30 min.

Hour (UTC)     12h UTC        ET (EDT/EST)    Workflows
─────────────────────────────────────────────────────────────────────────────
00:xx          12:xx AM       8:xx PM / 7:xx PM    mirror-to-osp (:13)  sync-in (:37)
                                                    mirror-osp-to-ooc (:45)  auto-merge-prs (:55)
01:xx          1:xx AM        9:xx PM / 8:xx PM    sync-pieroproietti-forks (:07)
                                                    mirror-osp-to-gitlab (:23)
                                                    sync-to-gitlab-variant (:50)
02:xx          2:xx AM        10:xx PM / 9:xx PM   mirror-artifacts (:10)  mirror-orgs-full (:17)
                                                    setup-osp-mirrors (:45)
03:xx          3:xx AM        11:xx PM / 10:xx PM  upstream-prs (:33)  upstream-commits (:47)
04:xx          4:xx AM        12:xx AM / 11:xx PM  git-platform-sync/pull (:27)
                                                    sync-registered-imports (:55)
05:xx          5:xx AM        1:xx AM / 12:xx AM   sync-btrfs-devel-branches (:02)
                                                    rebase-prs [*/2] (:10)
                                                    reconcile-org-refs [*/2] (:50)
06:xx          6:xx AM        2:xx AM / 1:xx AM    queue-manager (*/30)  quota-reserve (*/30)
                                                    [Mon only: update-infra-deps (:11)]
07:xx          7:xx AM        3:xx AM / 2:xx AM    resolve-ci (:43)
08:xx          8:xx AM        4:xx AM / 3:xx AM    check-ci (:05)  inject-badges [*/2] (:15)
09:xx          9:xx AM        5:xx AM / 4:xx AM    git-platform-sync/push (:23)
                                                    check-shell-tools-ci (:30)
10:xx          10:xx AM       6:xx AM / 5:xx AM    sync-in/daily (:15)
                                                    translate-readmes [*/2] (:43)
11:xx          11:xx AM       7:xx AM / 6:xx AM    translate-docs [*/2] (:15)
12:xx–23:xx    12:xx PM–      8:xx AM–             mirror-releases (:03 at 12:xx)
               11:xx PM       7:xx PM              queue-manager + quota-reserve (*/30, all hours)

Per-workflow scheduling reference

Core mirror chain

Mirror chain dependency order: Mirror I-D-1896 → OSP must complete before Mirror OSP → OOC. The :13/:45 stagger (32 min gap) is intentional — do not reduce this gap when manually dispatching both.

CI check + resolver

Note: Check CI Status requires a 1,500 quota floor — the highest of any workflow. If quota is below 1,500 at 09:05 UTC (4:05 AM EST / 5:05 AM EDT), it skips and waits for the next day. Manually dispatch after the 14:00 UTC reset if you need it to run same-day.

Sync operations

README + badge operations

Infrastructure / quota management

Heavy / manual-only workflows

Pre-Flush Prep has the highest floor (3,000) because it validates config, merges PRs, and then dispatches the full flush chain. Trigger it immediately after the 14:00 UTC (9:00 AM EST / 10:00 AM EDT) reset for maximum headroom.

Best manual dispatch windows

Highest quota headroom

Lowest concurrency (fewest parallel jobs)

Avoid

Pre-flush-prep checklist

Before triggering pre-flush-prep.yml:

# 1. Check quota
curl -sf -H "Authorization: token $SYNC_TOKEN" \
  "https://api.github.com/rate_limit" | \
  python3 -c "
import sys,json,datetime
d=json.load(sys.stdin)['resources']['core']
reset=datetime.datetime.utcfromtimestamp(d['reset']).strftime('%H:%M UTC')
ok = '✅' if d['remaining'] >= 3000 else '❌'
print(f\"{ok} remaining={d['remaining']} (need 3000)  resets={reset}\")
"

# 2. Run validators locally
python3 scripts/validate-workflow-guards.py
python3 scripts/validate-gitlab-subgroups.py config/gitlab-subgroups.yml
python3 scripts/validate-registered-imports.py registered-imports.json
python3 scripts/validate-priority-tiers.py config/workflow-priority-tiers.yml
python3 scripts/validate-cost-profiles.py config/workflow-cost-profiles.yml

# 3. Check for open PRs that would block the flush
gh pr list --state open --json number,title,mergeable

Ideal trigger time:

5 minutes after the hourly reset — maximum quota headroom before any scheduled workflows consume from the fresh bucket.

Quota drain reduction history

Current baseline: ~3,200 calls/day (~133/hr average).

Remaining quota reduction opportunities

These are known but not yet applied — each has a trade-off noted.

Speed improvement opportunities

Scripts

Workflows

Runner minutes

Public repos on GitHub get unlimited free runner minutes. If this repo is public, runner minutes are not a constraint. If private:

• Current worst-case estimate: ~8,000 min/month (well over 2,000 free tier)
• Self-hosted runner eliminates the cap entirely
• Alternatively: reduce timeout-minutes on workflows that consistently finish in < 5 min but have 30 min timeouts — this doesn't save minutes (billing is actual runtime, not timeout) but prevents runaway jobs

Workflows with oversized timeouts relative to typical runtime:

Quota Cost Registry

GitHub's REST API allows 5,000 requests per hour per user (shared across all tokens belonging to the same user). This page documents how many REST calls each workflow consumes per run, the minimum quota required before a workflow should start, and how the quota management system uses this data.

GraphQL counts as 1 call regardless of how many repos are queried. raw.githubusercontent.com fetches are exempt entirely.

How quota is managed

Three mechanisms work together:

The single source of truth for costs is config/workflow-quota-costs.yml.

Cost table

Costs are estimated from code audit (Phase 1). Phase 2 will replace these with observed p50/p95 values from actual run measurements.

min_quota = minimum REST calls required before this workflow should be allowed to start.

Tier 1 — Critical (never cancelled)

Tier 2 — High

Tier 3 — Medium

Tier 4 — Low (cancelled first)

Daily quota budget

At 5,000 calls/hour reset, the effective daily budget depends on how many resets are consumed cleanly vs. drained by backlog. With the schedule reductions applied (June 2026), the expected daily workflow run count dropped by ~172 runs/day.

REST → GraphQL conversion log

Scripts converted from per-repo REST loops to batched GraphQL calls:

Phase 2: observed cost tracking (planned)

Phase 2 will add lightweight instrumentation to measure actual REST consumption per run:

1. scripts/includes/quota-instrument.sh — records remaining_before and remaining_after as workflow step summary annotations
2. update-quota-costs.yml — weekly workflow that reads the last 30 run summaries via GraphQL, computes p50/p95 per workflow, and commits updated values back to config/workflow-quota-costs.yml with basis: observed

Once Phase 2 is active, the tables above will show observed values alongside the code-audit estimates, and quota-reserve.sh will automatically use the more accurate figures.

Operational Reference: GitHub Actions Limits & Quotas

This document covers the GitHub Actions limits that affect fork-sync-all, what consumes them, how to detect exhaustion, and how to recover.

GitHub API Rate Limit

Quota: 5,000 requests/hour per authenticated user token.

Resets: Top of every hour (rolling window).

What consumes it:

How fork-sync-all burns it:

• Every workflow_run trigger fires a new run, which itself may call the API
• rate-limit-rerun.yml (formerly hourly) scans all recent failed runs
• stuck-run-detector.yml (formerly hourly) lists all queued/in-progress runs
• translate-readmes.yml was triggering after 10 workflows — each trigger consumed dozens of API calls for the org scan
• Bulk-cancelling queued runs during cleanup consumes ~1 req per cancel — if the queue is large and quota is already low, the cancel loop itself can exhaust the remaining quota

Detecting exhaustion:

gh api rate_limit --jq '.resources.core | "remaining: \(.remaining)/\(.limit)  resets: \(.reset | todate)"'

Recovery: Wait until the top of the next hour. GraphQL remains available during REST exhaustion and can be used for read-only queries.

GitHub Actions Runner Minutes

Free tier: 2,000 minutes/month. Resets on your billing cycle date (the day of the month your GitHub account was created — check Settings → Billing → Actions for the exact date).

Paid: Billed per minute beyond the free tier; Linux runners cost 1×, Windows 2×, macOS 10×. All workflows in this repo use ubuntu-latest (Linux, 1×).

What counts against the monthly quota:

• Every job that runs on ubuntu-latest (GitHub-hosted runner)
• Time is measured from job start to job end, rounded up to the nearest minute
• Jobs that are queued but never start do not consume minutes
• Jobs that exit immediately (e.g. if: condition is false at the job level) still consume ~1 minute for runner provisioning

What does NOT count:

• workflow_dispatch triggers that are never clicked
• Runs that are cancelled before a job starts
• Skipped jobs (if: evaluated to false before the runner is assigned)
• Self-hosted runners (zero cost regardless of usage)

How fork-sync-all was burning minutes (before May 2026 fixes):

1. mirror-orgs-watchdog fired after every mirror completion (5 workflows × hourly cadence = ~120 runs/day), each consuming ~1 min even on success
2. update-readmes triggered after 7 workflows including high-frequency syncs
3. inject-badges triggered after mirror workflows that run hourly
4. stuck-run-detector and rate-limit-rerun ran hourly as meta-workflows, each consuming minutes to manage other workflows
5. workflow_run listeners fired on every completed event (success, failure, cancelled) — not just on the outcomes they actually needed

Detecting exhaustion:

Symptoms (in order of appearance):

1. ubuntu-latest jobs queue but never start
2. No in-progress runs despite many queued
3. Runs queued for hours with 0 runners active
4. Billing API returns 404 (needs user OAuth scope — check web UI instead)

Check via GitHub web UI: Settings → Billing → Actions.

Recovery: Wait until the billing cycle reset date. In the meantime:

• Cancel all queued runs (they will never start)
• Do not push commits that trigger new workflow runs
• Use workflow_dispatch manually only for critical operations

Concurrency Groups & Stuck Runs

How they work: A concurrency group allows only one run at a time for a given key. If cancel-in-progress: false, a second run queues behind the first. If the first run never finishes (e.g. runner minutes exhausted mid-job), the queued run is permanently stuck.

The cascade pattern:

1. Runner minutes exhaust mid-job → job hangs in in_progress
2. Next scheduled run queues behind it (cancel-in-progress: false)
3. The in-progress run never finishes → queue grows indefinitely
4. API calls to cancel are themselves rate-limited → nothing can be cleared

Orphaned runs: A run can become permanently orphaned if it was triggered from an older version of a workflow file that contained a job (e.g. Update cost profile) that no longer exists in the current file. The run accepts cancel API calls but GitHub immediately re-queues it because the concurrency group from the old code is still technically active. These runs time out automatically after GitHub's maximum queue wait (~6 hours). New runs from the same workflow are not blocked — they use the current file.

Policy in this repo (May 2026): All workflows use cancel-in-progress: true except those that perform multi-repo writes where mid-run cancellation would leave state partially applied:

Detecting stuck runs:

gh api "repos/Interested-Deving-1896/fork-sync-all/actions/runs?per_page=100" \
  --jq '[.workflow_runs[] | select(.status == "queued")] | length'

Bulk cancel (check quota first — cancel loop consumes ~1 req per run):

gh api rate_limit --jq '.resources.core.remaining'

gh api "repos/Interested-Deving-1896/fork-sync-all/actions/runs?per_page=100" \
  --jq '[.workflow_runs[] | select(.status=="queued") | .id] | .[]' | \
  xargs -I{} gh api -X POST \
    "repos/Interested-Deving-1896/fork-sync-all/actions/runs/{}/cancel"

workflow_run Trigger Cost Model

workflow_run fires on every completed event regardless of conclusion (success, failure, cancelled, skipped). A listener that only needs to act on failures still consumes a runner minute for every successful upstream run unless gated at the job level.

Pattern used in this repo:

# For workflows that act on upstream SUCCESS (content processors):
jobs:
  my-job:
    if: |
      github.event_name != 'workflow_run' ||
      github.event.workflow_run.conclusion == 'success'

# For workflows that act on upstream FAILURE (watchdogs/retriers):
jobs:
  retry:
    if: |
      github.event_name == 'workflow_dispatch' ||
      github.event.workflow_run.conclusion == 'failure'

This exits immediately (no runner cost) when the conclusion doesn't match, while keeping the trigger automatic.

All workflow_run listeners and their gates (May 2026):

Current Workflow Schedule Summary

Schedules as of June 2026. All times UTC (24h) / UTC (12h) / ET (EDT, UTC−4). See DOCS/workflow-scheduling.md for full per-workflow quota and window details.