GitHub Operating Model

Status: living document Scope: the organisation, repositories, Project, labels, templates, automation, CI, security and every free GitHub feature that is useful to IRIX 7. Current state (2026-10-25): irix7/os is public; Issues and Projects are enabled; Discussions and Wiki are enabled; Project #2, IRIX 7 — Roadmap, is linked to the repository. The active Project fields are the P0–P9 architecture phases and the M1–M4 mesh gates; the native v0.1–v1.0 releases remain compatibility history. An existing Project, IRIX 6.5.7m rebuild, covers the precursor work.

The goal is a project-management goliath that costs $0/month and still behaves like a serious engineering organisation: every issue tracked, every release reproducible, every security signal visible, every decision recorded.

1. Principles

1. Public by default. irix7/os is GPL-3.0 and public, which unlocks the free GitHub feature set. The only private repository is irix7/irix6 (clean-room source).
2. Everything is an issue. A task that is not on the Project does not exist. A decision that is not an ADR is a rumour.
3. Labels are machine-readable; fields are human-readable. Labels drive automation and filtering. Project fields drive the roadmap and the board.
4. Automate the boring parts. Adding to the Project, status transitions, stale closure, release notes, size labels and security scans are automated.
5. Least privilege. GITHUB_TOKEN is read-only by default; workflows request only the permissions they need. Secrets live in environments, not in the repository.
6. Free tier only. No paid feature is required. If a feature is paid or unavailable, the plan says so and provides a fallback.

2. Organisation and repositories

Repository settings for irix7/os:

• Description and topics: irix, sgi, mips, rust, operating-system, clean-room.
• Default branch main; squash merge; delete branch on merge; linear history.
• Issues, Projects, Discussions, Wiki and Pages enabled.
• Private vulnerability reporting enabled; security policy linked.
• Dependabot alerts and security updates enabled.
• Secret scanning and push protection enabled (free for public repositories).
• CodeQL default setup enabled for Rust and Actions.
• Actions permissions: read-only GITHUB_TOKEN by default; allow select actions.
• Forking allowed; workflows from forks require approval for first-time contributors.
• Release immutability enabled if available.

3. Access and clean-room separation

Rules:

• 2FA is mandatory for every member.
• irix7/irix6 has no Actions, no forks, no public access and no external collaborators.
• Only clean-room reviewers may read irix6; their work product is the behavioural specification, not code.
• Every contribution carries a DCO sign-off (git commit -s).
• The similarity screen runs on every PR that touches kernel code.
• Secrets are never committed; secret scanning and push protection are on.

4. Labels

Create these labels in addition to GitHub’s defaults. Colours are suggestions; the names matter.

Area

Type

Priority, size and risk

Hardware and status

The bootstrap also creates the operational labels area/boot, area/hardware, type/task, type/debt, stale, dependencies, skip-changelog, and release/major, release/minor, release/patch.

5. Milestones

Create release milestones only; the Phase Project field carries P0–P9 and the Mesh gate field carries M1–M4.

Due dates are optional and should be set only when the milestone is active; a stale date is worse than no date.

6. Issue types, sub-issues and epics

GitHub’s Issue Types and sub-issues are used where the org has them enabled; otherwise the type/* labels and task lists are the fallback.

• Epic = an architecture phase, a mesh gate or a cross-cutting workstream. One epic per P0–P9 and M1–M4 plus the seven cross-cutting workstreams.
• Sub-issue = a feature, research task, hardware task or bug inside an epic.
• Task list = the checklist inside an epic; every unchecked item links to an issue.
• Draft issue = a Parking-lot idea in the Project, not yet promoted to a repository issue.

Epic body template:

## Goal
## Demo
## Acceptance criteria
- [ ] ...
## Dependencies
## Out of scope
## Links
- Spec:
- ADR:
- Research:

7. Issue forms

The .github/ISSUE_TEMPLATE/ directory contains YAML issue forms:

config.yml disables blank issues and links to Discussions, the architecture spec and the plan.

8. Pull requests and review

• Trunk-based: short-lived branches, squash merge to main, linear history.
• Conventional commits: feat:, fix:, docs:, refactor:, test:, chore:, build:, ci:, perf:, spec:, adr:.
• PR template: summary, linked issue, milestone, type, tests, hardware, clean-room checklist, licence check, documentation.
• Review:
  • docs and trivial changes: 1 approval;
  • kernel, unsafe, capability or security code: 2 approvals, one from a maintainer;
  • clean-room-sensitive changes: 1 clean-room reviewer.
• Required checks: ci, licence, security, docs (when they exist); the merge is blocked until green.
• CODEOWNERS: * @belikh for now; replace with teams as they form.
• Merge queue: use it if the free plan offers it; otherwise require up-to-date branches.

9. Projects v2

Create a project IRIX 7 — Roadmap owned by irix7, linked to irix7/os.

9.1 Fields

GitHub creates a default Status field (Todo, In Progress, Done). The Project uses a separate Workflow field for the detailed state; the default Status is kept for the built-in “item closed” automation.

9.2 Views

9.3 Workflows

Built-in Project workflows:

• Auto-add to project: issues and PRs in irix7/os with type/epic, type/feature, type/bug, type/research, type/adr, type/hardware are added to the project.
• Item closed: set Workflow = Done (and the built-in Status = Done).
• Pull request linked: set Workflow = In Review.
• Item reopened: set Workflow = Ready.
• Auto-archive: archive items done for more than 30 days.
• Stale: mark items with no activity for 60 days; close after 14 more.

GitHub Actions fills the gaps:

• .github/workflows/project.yml adds new issues/PRs and maps labels to fields.
• .github/workflows/stale.yml runs the stale policy.
• .github/workflows/release-drafter.yml drafts release notes.

9.4 Templates

• Epic: goal, demo, acceptance criteria, dependencies, out of scope.
• Feature: problem, proposal, alternatives, acceptance criteria.
• Bug: build, hardware, steps, expected/actual, logs.
• ADR: context, decision, consequences, alternatives.
• Research: question, sources, findings, recommendation.
• Hardware: machine, board, serial, steps, result.
• Release checklist: tests, hardware, docs, SBOM, signature, announcement.

10. Actions and CI

10.1 Workflow inventory

CodeQL is enabled through the repository’s default setup (Settings → Code security), not a custom workflow. A custom codeql.yml cannot coexist with the default setup; the default setup is the GitHub-native, zero-maintenance option.

10.2 Runners

• ubuntu-latest for host builds, linting, docs and security.
• ubuntu-latest with a QEMU/iris container for emulator boot tests (when the image is available).
• Self-hosted indy for real-hardware tests: a small machine connected to the Indy’s serial console, network and power. Self-hosted runners are free; the hardware is the project’s.

10.3 Caching

• Swatinem/rust-cache for Cargo.
• actions/cache for the Nix store and the iris binary.
• GitHub Actions cache is free up to 10 GB per repository; prune old caches.
• Cross-build artefacts are uploaded with actions/upload-artifact and downloaded by the boot-test job.

10.4 Secrets and environments

Environment protection rules: release requires a maintainer approval; hardware is limited to the main branch.

10.5 Permissions

Every workflow starts with:

permissions:
  contents: read

and adds only what it needs (contents: write for releases, security-events: write for CodeQL/Scorecard, pages: write/id-token: write for Pages, issues: write/pull-requests: write for project automation).

11. Security features

The security policy and threat model live in security.md and ../SECURITY.md.

12. Discussions, wiki and pages

• Discussions: enable with categories Announcements, Roadmap, Q&A, Show and tell, Hardware, Research. Use Discussions for open-ended questions; use Issues for tracked work.
• Wiki: enable for the lab notebook and meeting notes only; canonical docs stay in docs/. If the wiki duplicates the repo, close it.
• Pages: build docs/ with mdBook and deploy to https://irix7.github.io/os/. Pages is free for public repositories.

13. Releases and packages

• Releases: every v* tag creates a GitHub Release with:
  • kernel, boot bundle and EROFS image;
  • SHA-256 checksums;
  • SBOM (SPDX and CycloneDX);
  • cosign signature and attestation;
  • release notes generated from PR labels;
  • upgrade and rollback instructions.
• Packages: use GitHub Packages only if we publish an MCP client or container image; the free tier is sufficient for public packages.
• Container registry: not required for v1.

14. Insights and metrics

Use the free Insights tabs and the Project charts:

• Pulse: weekly activity.
• Contributors: bus-factor awareness.
• Dependency graph: licence and vulnerability view.
• Network: branch and fork activity.
• Project charts: burn-up by milestone, throughput, cycle time, WIP.

Track monthly:

• open issues by area and priority;
• WIP (should stay small);
• cycle time from Ready to Done;
• bug rate (bugs found after Done);
• milestone burn-up;
• hardware-test pass rate.

15. Codespaces and devcontainer

Codespaces is useful for docs, CI debugging and contributor onboarding, not for the Indy hardware.

• A .devcontainer/devcontainer.json with Nix, Rust, gh, just, mdbook and the cross-toolchain stubs.
• Free quota: 120 core-hours and 15 GB-month for a personal account; stop idle codespaces.
• Do not commit secrets; use Codespaces secrets for MCP_TOKEN if needed.

16. CLI bootstrap

scripts/github/bootstrap.sh is idempotent and performs the setup. It created Project #2 and the original native epics on 2026-10-20.

1. Checks gh auth status and the required scopes (repo, workflow, project).
2. Enables Discussions and Wiki, disables blank issues.
3. Creates the labels in §4.
4. Creates the milestones in §5.
5. Creates the IRIX 7 — Roadmap project, links it to irix7/os.
6. Creates the fields in §9.1.
7. Creates the P0–P9 and M1–M4 epics (and the cross-cutting epics) as issues, adds them to the project, and sets Phase, Mesh gate, Area, Priority, Size, Risk, Hardware, Target.
8. Prints the project URL and the next manual steps (views, rulesets, CodeQL, Pages), because some features have no stable CLI/API.

Run it with:

gh auth refresh -s project,repo,workflow
scripts/github/bootstrap.sh

The script never deletes labels, issues, milestones or projects. Re-running it is safe.

16.1 Known limitations

• The gh project CLI reports unknown owner type for some organisation-owned projects. Use the GraphQL API or the Project UI for fields and items.
• The Projects API applies a cost-based secondary rate limit. A burst of item/field edits can fail even when the hourly quota looks healthy. The issues are created first, so no work is lost; re-run the bootstrap later or drag the issues into the Project in the UI. The initial bulk sync was completed on 2026-10-21; the caveat applies to future bulk changes.
• The views are created with the right layout. Filters, grouping and visible fields are configured in the UI (the API for views is limited).
• PROJECT_URL and PROJECT_TOKEN must be set manually for project.yml and the scheduled roadmap sync in docs.yml; until then project.yml skips and the docs build falls back to closed epics and release tags. PROJECT_TOKEN needs the project scope, plus repository write access if it is used to open the roadmap/sync pull request. The sync is described in tree/README.md.
• The default CodeQL setup is used; do not add a custom codeql.yml.

17. Free-feature matrix

Not used: Copilot paid tiers, Advanced Security for private repos, Enterprise, merge queue if it is paid-only, GitHub Models for project management.

18. Setup order

1. scripts/github/bootstrap.sh — labels, milestones, project, fields, epics.
2. Enable Discussions and Wiki; create categories.
3. Create the Project views in the UI (the GraphQL view API is not exposed by gh project).
4. Create the main ruleset: require PR, 1–2 approvals, linear history, required checks, no force-push, no deletion.
5. Enable CodeQL default setup, Dependabot alerts, secret scanning, push protection.
6. Enable Pages with GitHub Actions as the source; run docs.yml.
7. Create the release and hardware environments with protection rules and secrets.
8. Register the self-hosted indy runner.
9. Create the first epic issues and add them to the project (the bootstrap does this).
10. Post an announcement in Discussions with the plan links.