Phase 4: Publish to GitHub

Goal

Make Harmony publicly available on GitHub as the primary community hub for issues, pull requests, and discussions. CI runs on self-hosted runners.

Prerequisites

Phase 3 complete: LFS removed, git history cleaned, repo is small
README polished with quick-start, architecture overview, examples
All existing tests pass

Tasks

4.1 Clean git history

# Option A: git filter-repo (preferred)
git filter-repo --strip-blobs-bigger-than 10M

# Option B: BFG Repo Cleaner
bfg --strip-blobs-bigger-than 10M
git reflog expire --expire=now --all
git gc --prune=now --aggressive

Verify final repo size is reasonable (target: <50MB including all code, docs, templates).

4.2 Create GitHub repository

Create NationTech/harmony (or chosen org/name) on GitHub
Push cleaned repo as initial commit
Set default branch to main (rename from master if desired)

4.3 Set up CI on self-hosted runners

GitHub is the community hub, but CI runs on your own infrastructure. Options:

Option A: GitHub Actions with self-hosted runners

Register your Gitea runner machines as GitHub Actions self-hosted runners
Port .gitea/workflows/check.yml to .github/workflows/check.yml
Same Docker image (hub.nationtech.io/harmony/harmony_composer:latest), same commands
Pro: native GitHub PR checks, no external service needed
Con: runners need outbound access to GitHub API

Option B: External CI (Woodpecker, Drone, Jenkins)

Use any CI that supports webhooks from GitHub
Report status back to GitHub via commit status API / checks API
Pro: fully self-hosted, no GitHub dependency for builds
Con: extra integration work

Option C: Keep Gitea CI, mirror from GitHub

GitHub repo has a webhook that triggers Gitea CI on push
Gitea reports back to GitHub via commit status API
Pro: no migration of CI config
Con: fragile webhook chain

Recommendation: Option A. GitHub Actions self-hosted runners are straightforward and give the best contributor UX (native PR checks). The workflow files are nearly identical to Gitea workflows.

# .github/workflows/check.yml
name: Check
on: [push, pull_request]
jobs:
  check:
    runs-on: self-hosted
    container:
      image: hub.nationtech.io/harmony/harmony_composer:latest
    steps:
      - uses: actions/checkout@v4
      - run: bash build/check.sh

4.4 Polish documentation

README.md: Quick-start (clone → run → get prompted → see result), architecture diagram (Score → Interpret → Topology), link to docs and examples
CONTRIBUTING.md: Already exists. Review for GitHub-specific guidance (fork workflow, PR template)
docs/: Already comprehensive. Verify links work on GitHub rendering
Examples: Ensure each example has a one-line description in its Cargo.toml and a comment block in main.rs

4.5 License and legal

Verify workspace license field in root Cargo.toml is set correctly
Add LICENSE file at repo root if not present
Scan for any proprietary dependencies or hardcoded internal URLs

4.6 GitHub repository configuration

Branch protection on main: require PR review, require CI to pass
Issue templates: bug report, feature request
PR template: checklist (tests pass, docs updated, etc.)
Topics/tags: rust, infrastructure-as-code, kubernetes, orchestration, bare-metal
Repository description: "Infrastructure orchestration framework. Declare what you want (Score), describe your infrastructure (Topology), let Harmony figure out how."

4.7 Gitea as internal mirror

Set up Gitea to mirror from GitHub (pull mirror)
Internal CI can continue running on Gitea for private/experimental branches
Public contributions flow through GitHub

Deliverables

Git history cleaned, repo size <50MB
Public GitHub repository created
CI running on self-hosted runners with GitHub Actions
Branch protection enabled
README polished with quick-start guide
Issue and PR templates created
LICENSE file present
Gitea configured as mirror

4.0 KiB Raw Permalink Blame History