mortennordbye/homelab/setup-github-repo

Setup GitHub Repo

When invoked, configure the current repository to the standard below using git, the GitHub CLI (gh), and automated commits.

What this skill does not do

State the boundaries up front so nothing lands by surprise. This skill:

• Never overwrites your content unasked. Existing non-empty files are audited

read-only and improvements are offered additively (Principle 7). .gitignore and .gitattributes only ever gain missing lines. The one path that reorganizes existing prose — restructuring a badly-organized README — happens only after you approve it explicitly, and even then it reflows your content without rewording it (Phase 3).

• Never treats "already present" as "done." Every skipped file is still audited for

gaps against the standard below, in setup mode as well as audit mode (Principle 7).

• Never picks a license. Legal decision — asked in Phase 1, never auto-selected.
• Never invents CI commands. If the stack can't be detected, CI is skipped and

reported; a green check that tests nothing is worse than none (Principle 3).

• Never installs GitHub Apps. Renovate needs the Mend app installed by hand — the

skill commits the config and prints the install URL as a manual step.

• Never does what has no API. Social preview image, and anything else GitHub exposes

only in the UI, land in the manual-steps summary rather than being attempted.

• Never runs interactive auth. gh auth login / gh auth refresh are yours to run;

the skill detects the gap and stops (Phase 0).

• Never force-pushes, deletes branches, or rewrites history — the ruleset it installs

forbids exactly that.

• Never commits secrets, and never `git add .` — files are staged by explicit path

(Principle 5).

• Never applies protection that can lock you out. Solo repos never require

self-approval; light-profile direct pushes stay open.

• Never touches a repo it shouldn't. Archived, fork, or non-admin aborts in Phase 0;

a private repo drops the public-only features instead of erroring through them.

Modes

Two switches, both resolved before anything runs.

Run mode — setup (default) or audit. When invoked with "audit" or "dry-run", execute Phase 0 plus every read-only check from Phases 5–7 and print the compliance table (compliant / missing / would-change) without writing anything. Use it before a first run, and re-run it later to detect drift on repos that were set up earlier. Setup mode audits too: it never overwrites an existing file, but it still reads each one against the standard and reports the gaps (Principle 7) — audit-only mode just stops before the writing.

Profile — light (default) or strict. Security that runs invisibly is always on; what the profile controls is friction. A hobby project should not feel like filing a change request to push to its default branch.

Principles

1. Idempotent. Safe to re-run. Never overwrite a non-empty existing file; skip it,

note it, and audit it (Principle 7). Settings calls (gh repo edit, gh api PUT/PATCH) are naturally idempotent. End every run with a summary table: applied / skipped (already present, with any audit gaps) / manual steps.

1. Ordering matters. Files first, merge them, then rulesets and required checks.

Applying protection that requires reviews or status checks before those exist locks the maintainer out of their own repo.

1. Detect before generating. Infer language/ecosystem from lockfiles and manifests,

and only generate what applies. Never commit a CI workflow with echo placeholder steps — if you cannot fill in real commands for the detected stack, skip CI and report it. A meaningless green check is worse than no check.

1. Practice what you preach. Every workflow you commit must itself pass the standard:

actions pinned to a version tag (never @master/@main), an explicit least-privilege permissions: block, a concurrency group on CI, and never pull_request_target combined with a checkout of PR head code.

1. Commit surgically. Stage generated files by explicit path. Never git add .. For

every commit use the same three steps: git status --porcelain (confirm only intended files changed) → git add <exact/path> ... → git commit -m "type(scope): summary".

1. No heredocs for API bodies. Some agent harnesses corrupt shell heredocs

(<<'EOF') through quote or newline handling. For any gh api call that takes a JSON body, write the payload to a temp file outside the working tree (so it can't be staged or trip the clean-tree check — use your file-writing tool or printf, not a heredoc), apply it with gh api ... --input "$f", and delete it after. The JSON blocks below are payloads to write, not commands to paste into a shell.

1. Audit, don't just skip. A skipped file is not a finished file. For every existing

file on the skip-list — README, LICENSE, SECURITY.md, dependabot.yml, existing workflows, dotfiles — audit it read-only against this skill's standard and record every gap as a finding in the Phase 7 summary, then offer to apply the missing pieces additively (insert blocks, keep the author's content). This runs in setup mode, not only the dedicated audit mode: an "already present" line in the summary must always be paired with what, if anything, that file still lacks — never a bare skip. The README brownfield checklist in Phase 3 is the worked example; hold every other skipped file to the same read-and-report discipline. Existing workflows in particular: check they carry a least-privilege permissions: block, version-pinned actions that still resolve, and a concurrency group (Principle 4) — report deviations, don't rewrite silently.

Error handling

Phase 0 gates the hard blockers — auth, admin rights, archived, fork, dirty tree — and those abort the run. Once past Phase 0, a single failed settings call must never halt the run or pause to ask: log it, add it to the manual-steps summary, and continue. Specific cases:

Anything not listed: if it is a settings call, treat it like the rows above (log, summarize, continue); if it is a blocker that makes later phases meaningless — the scaffold failed to push, say — stop and report.

Phase 0 — Preflight

Run these checks; abort with a clear message if any fail:

Phase 1 — Ask the user (one batched round)

Ask only what cannot be decided automatically: