repo-setup

Recipe card from the charly-internals plugin (Development — contributor internals).

repo-setup — the opencharly org, dotgithub config, and new-repo setup

This skill is the companion to /charly-internals:git-workflow: git-workflow owns the AUTHOR’s branch/PR discipline; repo-setup owns the ORG-LEVEL configuration that discipline relies on and the checklist for standing up a NEW repository.

The org model (verified against the live settings)

• The opencharly org is on GitHub Team, so org rulesets and the workflows rule (“Require workflows to pass”) are available.
• ONE organization branch ruleset named org-wide required workflow & main protection is the single source of main protection and the required workflow. It targets ~ALL repositories MINUS an explicit exclude set, on refs/heads/main, and carries:
  • workflows — requires opencharly/.github/.github/workflows/org-wide-pr-validator-required.yml@refs/heads/main (read from the .github repo at the pinned ref);
  • required_status_checks — strict: true, exactly ONE context validate / validate;
  • non_fast_forward, deletion, creation. The ONLY bypass actor is the charly-auto-merge GitHub App (its protected-main CHANGELOG writes must land). There is NO human bypass and NO pull_request review rule — the validator IS the gate.
• Owner script: opencharly/.github/scripts/org-ruleset.sh (apply / verify). It creates/updates the ruleset, deletes redundant per-repo rulesets and any surviving legacy branch protection, and enforces the two settings that have NO org-level default: allow_auto_merge=true and delete_branch_on_merge=true.
• The target set is discover_repos in scripts/lib-org.sh: active, non-fork, default branch main. Everything else is discover_excludes (forks, archived, non-main defaults) and receives NEITHER the org workflow NOR CalVer tags — by design, not by omission.

What happens automatically on every PR (the landing chain)

1. A PR is opened/updated → the org ruleset runs org-wide-pr-validator-required.yml in the TARGET repo’s context (definition from opencharly/.github at the pinned ref) → it calls the reusable pr-validator.yml → the single required check validate / validate.
2. On a PASS verdict the validator enables GitHub native auto-merge (squash) inline — there is NO separate auto-merge workflow. main is squash-only.
3. After the merge, the PER-REPO caller .github/workflows/tag-on-merge.yml fires (on workflow_run of charly/pr-validator + push to main) → calls the org reusable tag-on-merge.yml, which mints the CalVer tag v<YYYY>.<DDD>.<HHMM> at the merge commit and writes CHANGELOG/<CalVer>.md from the merged PR body (the body IS the changelog). Proxy-consumed root modules (sdk, spec, plugin-gh) get the Go-module v0.<YYYYDDD>.<HHMM> form instead.
4. A body-only fix after the head was pushed needs NO empty commit: re-run the failed run MANUALLY with gh run rerun <run-id> (a re-run updates the same check run in place). The org-wide rerun label sweep was RETIRED.

Setting up a NEW repository (checklist)

1. Create opencharly/<name> (non-fork; it must end up on default branch main). The org ruleset then covers it automatically — no per-repo branch rules.
2. Add the per-repo .github/workflows/tag-on-merge.yml caller — REQUIRED for CalVer tags and the CHANGELOG — plus the appropriate deploy.yml. The org-required validator needs NO per-repo file (the old pr-validator.yml dispatcher is retired by retire-per-repo-dispatchers.yml).
3. The org owner applies the ONE org ruleset (the org-ruleset.sh owner script in opencharly/.github, apply mode — an operator/CI action, not a charly user command) so allow_auto_merge and delete_branch_on_merge are enforced for the new repo.
4. Land the first commit via a PR — never a direct push to main.
5. Add it to the umbrella as a submodule and advance the pin via charly task sync + PR (see /charly-internals:git-workflow B8).

The measured gap this checklist prevents

A repo created WITHOUT the tag-on-merge.yml caller still MERGES (the org workflow validates it) but NEVER gets a CalVer tag: measured on layer-nerdctl and plugin-nerdctl (no .github directory at all; their two v2026.266.* tags were minted manually). Excluded BY DESIGN (no tag expected): gst-wayland-display (a fork), pixelflux (a vendored upstream on non-main default av1), omarchy-eval-artifacts (a runs-branch artifact sink), and the archived pi-review-action.

Cross-References

• /charly-internals:git-workflow — the author’s branch/PR/landing discipline and the after-merge close-out checklist (B8).
• opencharly/.github — scripts/org-ruleset.sh, scripts/lib-org.sh, scripts/retire-per-repo-dispatchers.sh, and the workflows org-wide-pr-validator-required.yml, pr-validator.yml, tag-on-merge.yml, tag-on-merge-dispatcher.yml, bootstrap-repo-main.yml.

When to Use This Skill

Invoke when creating or onboarding a repository in the opencharly org, when adding or changing CI/landing workflows, or when explaining what the org ruleset and dotgithub workflows do automatically versus what each repo must configure.