GitHub Repository Setup

Professional GitHub repository infrastructure for Impossible OS -- CI/CD, templates, security policies, and community assets.

Overview

The rizonesoft/impossible-os GitHub repository is configured with CI/CD pipelines, automated release management, issue/PR templates, branch protection, and community documentation. A secondary archived repo (rizonesoft/impossible-os-bootloader) exists but all development happens in the main repo.

Repository ownership and org policy. todo/00-infrastructure/TODO-09 tracks the completed transfer (executed 2026-04-27) from rizonesoft/impossible-os to rizonesoft/impossible-os (enterprise org), plus the §8 future move-back / public-visibility runbook (repository-move-back-runbook.md).

Moved back and made public 2026-09-27: owner is rizonesoft (personal account), visibility public, rizonetech/impossible-os 301-redirects here. Custom domain impossibleos.co (apex A records on GitHub Pages IPs, cert approved, HTTPS enforced). The admin bypass on the Default Branch Security ruleset is restored. Secret scanning and push protection are enabled. Execution record: move-back and public-visibility runbook.

DNS: the www CNAME targets rizonesoft.github.io (flipped 2026-09-27; re-checked 2026-09-28 through a public resolver, and https://www.impossibleos.co/ returns 301 to the apex). Operator-pending: the autonomous-agent boundary check (Settings -> Copilot -> Access policies) is an operator-only UI check with no public API.

The pre-transfer current-state baseline -- repository identity, Pages source mode, DNS, Actions/secrets/rulesets, hard-coded owner references, risk register -- is captured once in repository-transfer-preflight.md so the §5 / §7 audits and the eventual §8 move-back compare against a single source of truth.

graph TD
    subgraph "Repository"
        A[README.md] --> B[Professional landing page]
        C[CONTRIBUTING.md] --> D[Dev setup + code style]
        E[SECURITY.md] --> F[Vuln reporting policy]
        G[CODE_OF_CONDUCT.md] --> H[Community standards]
    end

    subgraph "CI/CD Workflows"
        I["build.yml (push/PR)"] --> J[Build + verify sentinel]
        K["release.yml (tag)"] --> L[Build + VDI + GitHub Release]
        M["stale.yml (cron)"] --> N[60d stale → 14d close]
        O["labeler.yml (PR)"] --> P[Auto-label by path]
        Q["pages.yml"] --> R[GitHub Pages deploy]
    end

    subgraph "Templates"
        S[bug-report.yml] --> T[Structured bug form]
        U[feature-request.yml] --> V[Feature proposal form]
        W[hardware-report.yml] --> X[HW compat report]
        Y[PR template] --> Z[Testing checklist]
    end

Repository Structure

Secure Boot release plan (decided 2026-06-16). At public release, the shim-review / Microsoft 3rd-party UEFI CA submission uses the main source (rizonesoft/impossible-os, which builds BOOTX64.EFI from src/boot/uefi/), NOT a separate bootloader repo. rizonesoft/impossible-os-bootloader was only ever a pre-release stopgap; it is not part of the future signing path. Retire it once the release main-source submission is accepted. Do not delete it while any upstream rhboot/shim-review submission referencing it is still open. The local bootloader git remote was removed 2026-06-16 (nothing syncs to it; the BOOTLOADER_REPO_TOKEN secret is orphaned with no consumer).

README & Community Documents

Professional README

README.md -- the project's public face. Features:

Badges (shields.io):

CONTRIBUTING.md

Contributor guidelines (160+ lines):

SECURITY.md

Vulnerability reporting policy:

Caution

MOK Private Key Security: The MOK private key (MOK.key) MUST NEVER be committed to any repository. Store in encrypted vault or hardware token. Compromise allows signing malware that bypasses Secure Boot on enrolled machines.

CODE_OF_CONDUCT.md

Contributor Covenant v2.1. Contact: derick@rizonetech.com.

LICENSE

GPL-3.0-only (changed from MIT in commit 474abac).

Versioning System

CalVer (Calendar Versioning)

Version scheme: YY.M.D.BUILD (e.g., 26.3.17.819).

graph LR
    A[Build triggered] --> B["Makefile reads date -u"]
    B --> C["YY.M.D → VERSION_MAJOR.MINOR.PATCH"]
    C --> D[".build_number → BUILD_NUMBER++"]
    D --> E["include/build_info.h generated"]
    E --> F["version_print() at boot"]

Note

CalVer was chosen over SemVer because Impossible OS is in rapid development with no stable API to version against. Can migrate to SemVer when releases become meaningful.

Git Tag Conventions

Tags are annotated: git tag -a v26.3.18 -m "Release v26.3.18"

Changelog Generation

scripts/generate-changelog.sh -- 175 lines, 20+ category mappings.

• Parses git log between tags
• Groups by commit prefix: Features, Fixes, Build, Drivers, Desktop, Kernel
• Outputs markdown with short commit hashes
• Generates 794+ lines from full history
• Integrated into release workflow

CI/CD Workflows

Build & Smoke Test (build.yml)

Triggers on push to main and pull requests.

graph LR
    A[Push/PR] --> B[Install LLVM-19]
    B --> C["Cache LLVM (actions/cache@v4)"]
    C --> D["bash scripts/build.sh clean"]
    D --> E{"tail -1 build.log == BUILD OK?"}
    E -->|Yes| F[Upload system-disk.img]
    E -->|No| G[Upload build.log + FAIL]

Dependencies installed:

• clang-19, lld-19 (from apt.llvm.org snapshot repo)
• nasm, mtools, dosfstools, ovmf, gcc, qemu-system-x86

Note

LLVM 19 is not in ubuntu-latest by default -- installed from apt.llvm.org. gcc is HOST_CC for host tools (mkfs-ixfs, make-system-disk). dosfstools provides mkfs.fat, mtools provides mcopy.

Automated Release (release.yml)

Triggers on tag push matching v*.

graph LR
    A["Push tag v26.3.18"] --> B[Checkout full history]
    B --> C[Install deps + VirtualBox]
    C --> D[Build + verify]
    D --> E["VBoxManage → .vdi"]
    E --> F[Generate changelog]
    F --> G["GitHub Release (softprops/action-gh-release@v2)"]

Release assets:

Stale Issue Cleanup (stale.yml)

Uses actions/stale@v9. Runs daily at 01:30 UTC.

Auto-Label PRs (labeler.yml)

Uses actions/labeler@v5 with changed-files / any-glob-to-any-file syntax.

Triggers on pull_request (opened, synchronize).

Issue & PR Templates

Issue Templates

Located in .github/ISSUE_TEMPLATE/:

config.yml: Blank issues disabled -- directs to Discussions + TODO roadmap.

Environment dropdown options: QEMU, VirtualBox, Hyper-V, VMware, Real Hardware

Component dropdown options: Kernel, Bootloader, Desktop, Drivers, Filesystem, Networking, Userland, Build System

PR Template

.github/PULL_REQUEST_TEMPLATE.md -- includes:

• Description section
• Related TODO reference
• Testing checklist (build.sh clean + run + serial check)
• Type of Change checkboxes
• Screenshots/Serial Output section

Labels & Project Board

Label Taxonomy

Priority labels (red gradient):

Component labels (blue gradient):

Type labels:

Status labels:

GitHub Project Board

"Impossible OS Development" -- GitHub Projects v2.

Milestones (matching TODO phases):

Branch Protection & Policies

Branch Protection Rules (main)

Branch Naming Convention

CODEOWNERS

.github/CODEOWNERS -- @derickpayne as default owner.

Critical path explicit ownership:

• src/boot/ -- bootloader
• src/kernel/memory/ -- memory management
• src/kernel/sched/ -- scheduler
• linker.ld -- linker scripts
• Makefile -- build system
• scripts/build.sh -- build script

GitHub Pages

The landing page, the design mockups and the documentation site, generated by scripts/site/build.py from gh-pages/ templates and docs/. Nothing generated is committed to main; the old gh-pages branch is dormant and kept, and the docs-releases branch holds only frozen release docs written by CI.

Key Files

Gotchas

Caution

MOK key in version control. The MOK.key private key must NEVER be committed. Store in encrypted vault or hardware token.

Warning

LLVM-19 not in ubuntu-latest. CI must install from apt.llvm.org snapshot repo. Cache key llvm-19-Linux-v1 -- bump suffix to invalidate.

Warning

VBoxManage in CI. Release workflow installs the virtualbox package for VDI conversion. This adds ~2 min to CI runtime.

Note

Build CI smoke test. Currently commented out in build.yml -- uncomment when scripts/test-smoke.sh is integrated into CI pipeline.

Note

License change. License was changed from MIT to GPL-3.0-only (commit 474abac). All badges and documentation reflect GPL-3.0-only.

OS Comparison

References

• Repository: rizonesoft/impossible-os
• CI config: .github/workflows/
• Templates: .github/ISSUE_TEMPLATE/
• Related: Development Tooling