GitHub publishing workflow (framework baseline)

Purpose: Follow a consistent, research-backed workflow to get a repo ready for public GitHub publication: documentation layout, licensing, scrub for sensitive or context-specific content, and a repeatable checklist.

Documentation and structure (best practice)

• README: Clear value proposition near the top; install instructions; layout of deployed content; optional contents table or TOC for navigation. Section headings that work as anchors. Consider light visual cues (e.g. section icons) for scanability; keep one H1 per doc.
• SECURITY.md: How to report vulnerabilities (private advisory or contact). Link from repo Security tab. State scope (this repo only; third-party tools out of scope).
• CONTRIBUTING.md: How to open Issues, Discussions, and PRs; repo layout; that contributions are licensed under the project license. Point to LICENSE.
• LICENSE: Chosen license (e.g. MIT) with correct copyright holder. Single source for "can use, modify, distribute" terms.
• Framework README: If the repo contains a framework subfolder, its README should describe the engine, tools, and docs and link to root README, SECURITY, CONTRIBUTING, and LICENSE.

Use relative links and consistent heading levels. Avoid PII and machine-specific paths in all of the above.

Licensing and copyright

• Copyright: Attribute to the intended owner (e.g. company or author). Use a single line in LICENSE and, if desired, a short "License and copyright" section in README.
• MIT: Allows use, copy, modify, merge, publish, distribute, sublicense, and sell copies/derivatives, with copyright and permission notice preserved. See LICENSE for full text.
• Display: README and framework README should state "Copyright (c) YEAR Owner" and "Released under the MIT License" (or chosen license) with a link to LICENSE.

Author and contact (without exposing personal email)

• Author: Name and link to profile (e.g. GitHub). Do not embed a personal email in the repo if the goal is to avoid scraping and spam.
• Contact: Direct users to GitHub Issues or Discussions in the repo so they can reach you without publishing an email. Optionally link to a company or contact page.
• Co-authored-by: If the tooling adds a "Co-authored-by" trailer (e.g. from an IDE) and the maintainer does not want it in history, the commit-msg hook can strip that trailer before the commit is finalized.

Scrub before publishing (no PII or context-specific artifacts)

• No personal data: No real email, physical address, or phone in committed files except where explicitly intended for public contact.
• No secrets: No API keys, tokens, passwords, or credentials. No committed .env or secret files.
• No machine-specific paths: No hardcoded /home/username, /Users/name, C:\Users\..., or internal hostnames. Use placeholders or environment variables for paths.
• Clone and repo URLs: Default clone URL in install (or equivalent) must point to the public repo. Overridable via environment variable for forks. Issue/Discussion links in README must use the correct repo owner.
• Deploy artifacts: Any directory or file that is generated by deploy (e.g. a copy of docs under a different path) must be in .gitignore and must not be tracked. Remove from tracking if it was ever committed.

Run a quick scrub command (e.g. grep for password, secret, api_key, token, /home/, /Users/) and review matches before publishing.

Version and release

• VERSION: Set to the intended release version. README and any "Version" display must match (see ls-version-bump-commits skill).
• Versioning docs: If the project uses automatic versioning, document it (e.g. docs/VERSIONING.md) and link from README.

Repository settings (on GitHub)

LocalSetup release-documentation gate

Prepare and review the structured release record and affected public prose in the source checkout, then render and check the owned sections before canonical version and generated-document sync. Optional protected QC authoring can propose and independently review the candidate; trusted tooling applies accepted edits under the configured signing identity. The ordinary hosted release validates already committed source and does not run a model, create an unsigned bot commit, or push source.

publish.yml supports explicit release, repair, and qualify dispatch modes. Successful validation of the exact candidate commit is reused when that commit reaches main and release preparation. Hosted publication requires completed framework, documentation, and QC results instead of running the full suite again. After the accepted source passes these checks, the maintainer creates and pushes a verified OpenPGP-signed annotated tag at that exact commit. release verifies the pre-existing tag and commit using the required public certificate, builds and checks artifacts, and creates a draft with --verify-tag. repair updates published notes from reviewed committed prose while preserving the published tag and assets. qualify prepares evidence without integration or release mutation. These modes do not grant authority to scheduled QC patrols.

Before publishing a completed draft, fetch its tag and run localsetup release-docs check --draft-tag v<version> --expected-commit <sha> from that exact candidate. This compares rendered notes, tag identity, and the documented archive/checksum/SBOM asset names. It does not replace complete artifact, checksum, provenance, and license verification. Re-run if notes, source, or assets change. Direct administrative GitHub UI actions are outside workflow enforcement.

• Visibility: Keep visibility out of the ordinary repository-enhancement plan. Public/private visibility is supported only on github.com and only as the sole setting in its own reviewed plan with its own digest and exact operation authorization. Split or reject a policy that mixes visibility with other changes before apply. Visibility on other hosts stays report-only while the Enterprise Server API-version matrix is unverified. The CLI/REST handling of internal is unresolved; controls without supported typed operations remain report-only.
• Description and topics: Short description and topics for discoverability.
• Default branch: Align install/docs URLs with the default branch (e.g. main).
• Issues and Discussions: Enable if you want contact via GitHub.
• Security: Enable "Private vulnerability reporting" if desired; SECURITY.md should explain how to report.

CLI-first repository settings

Use GitHub repository enhancement for the remote settings audit, deterministic plan, selectively authorized apply, and final verification. Its seven groups expose one observation for every control in a fixed registry. The registry is the exact coverage contract for this workflow, not an exhaustive inventory of every possible GitHub control. Rows distinguish applicability, authority, capability, observation state, and evidence or a safe reason. Reason-backed unknown, unavailable, inherited, local, UI-only, or not-applicable outcomes are assessed evidence; they do not claim a requested policy is satisfied. Controls without a documented typed mutation remain report-only.

All remote write operations are enabled only on github.com while the GitHub Enterprise Server API-version matrix remains unverified. Audits and reads may run on other hosts, but requested drift there remains incomplete/report-only with a compatibility reason.

Each plan includes an exact coverage receipt with status, expected and observed counts, and missing, duplicate, invalid, and incomplete control IDs. A missing, duplicated, malformed, or incompletely observed control makes coverage incomplete. Plans bind local checkout root identity, HEAD, branch or detached state, staged/worktree/untracked counts, a digest of Git porcelain status bytes, configured upstream, normalized origin/upstream matches, and structural content evidence with SHA-256/size for only inspected files. The plan omits raw remote URLs, credentials, absolute checkout paths, raw status paths, and file contents. Structural evidence reports presence, not content quality. Plan and verification output also distinguishes inventory caveats, authorization findings about ambient token-permission visibility, and requested_policy gaps. Apply refuses incomplete coverage or checkout/content drift. Verify is incomplete when coverage is incomplete or local evidence drifts, even when no remote operation read-back failed.

Its fixed target syntax is localsetup github-repo --repository OWNER/REPO --hostname HOST --checkout PATH --mode MODE, where MODE is audit, plan, apply, or verify. The remote target is always selected with --repository and --hostname; the global --repo option retains its LocalSetup source-checkout meaning. --checkout PATH selects the local Git checkout used for evidence and defaults to .; use the same checkout for audit/plan and apply/verify. Review the exact plan JSON and its SHA-256 digest before applying. Plan mode requires --policy POLICY.json, and verify mode requires --plan PLAN.json. An apply invocation must supply --plan PLAN.json, --authorize-plan DIGEST, and one --operation OP_ID for each approved operation. Plan mode writes plan.json and plan.md; its JSON summary reports both paths, the digest, and operation IDs. By default, the files are under LocalSetup's per-user private state root at github-repository-operations/<target-key>/plans/<plan-digest>/. The target key binds normalized hostname and immutable repository ID. The default state root must be owned by the current user with mode 0700; an unsafe root or parent fails closed. Apply also requires that secure root for its target journal. --output-directory DIR optionally selects another directory, which must be user-owned with mode 0700 and is created with that mode if missing. Path components cannot be symlinks. Ancestors must be root- or user-owned and not group/world writable, except root-owned sticky directories such as /tmp. Plan files are created exclusively at mode 0600 without following symlinks; existing files must be user-owned mode-0600, single-link regular files. Use the reported plan.json path for apply and verify. The digest and selected IDs authorize only that subset from the exact plan. Destructive or access-changing changes are excluded from the ordinary plan and need a separate policy, reviewed plan, digest, and exact operation authorization. Public/private visibility is supported only on github.com, as the sole setting in its own plan; split or reject a policy that mixes it with other operations before apply. Visibility on other hosts stays report-only while Enterprise Server support is unknown. The documented CLI and REST surfaces do not agree about internal, so keep that case unresolved. Unsupported controls stay report-only. Reconcile an uncertain response with reads before considering any new invocation; never replay a write automatically. Keep tracked content, signed commits, releases, and tags on the local Git and release paths below.

Optional release verification is policy-scoped. Policy schema v2 may select verification.signatures.{commit_oid,tag_name,expected_primary_fingerprints} and verification.release.{release_id,tag_name,source_ref,source_commit,signer_workflow,predicate_type,artifacts}; each artifact binds asset_id, name, checkout-relative path, and expected_sha256. Verify binds these requirements to the exact repository, release, tag, source identities, selected local bytes, and declared signer workflow and predicate. Supply trust keys only with repeatable verify-only --trusted-public-key FILE; never save or print key material, absolute paths, or raw CLI output. Missing or old gh installations without gh release verify-asset or gh attestation verify leave proof unavailable or incomplete; do not upgrade the CLI automatically. When policy declares no verification requirements, release readiness is not_assessed. apply completion describes only the selected settings operations and does not establish release readiness. Saved plans now use schema v4 while policy stays schema v2; regenerate schema-v2 or schema-v3 saved plans from their reviewed policy.

Each typed operation displays a canonical interface descriptor in plan JSON and Markdown. It identifies transport, fixed command or HTTP method/endpoint template, binding to plan.target, required flags, and the reason an API interface was selected; this descriptor is bound into the operation identity and plan digest. Prefer gh repo edit when its exact supported command and flags express the complete operation. Before dispatch, bounded command help must confirm every required flag; if the command, flag, or feature is unavailable, fail closed. Do not silently switch transports or replay after a command failure. Ruleset mutations use REST through gh api, because the documented gh ruleset interface supports list/check/view but no writes.

For collaboration web commit signoff, policy schema v2 supports the desired Boolean repository.web_commit_signoff_required; it controls the registered collaboration.web_commit_signoff setting. The official gh repo edit options do not document an exact native flag for it. The typed operation therefore selects PATCH /repos/{owner}/{repo} through gh api, includes web_commit_signoff_required in the request body, and records why REST was selected. GitHub documents the Boolean in Update a repository.

Schema-v2 policy distinguishes no requested social-preview action from explicit removal. For upload, specify repository_content.social_preview: {"action":"present","asset_path":"assets/social-preview.png"}. The checkout-relative asset must resolve to a contained regular non-symlink file under 1 MB with PNG, JPEG, or GIF magic. Its relative path, SHA-256, size, and detected format bind into the plan and are rechecked before apply/verify. For removal, specify {"action":"absent"} and omit asset_path. GitHub's documented upload and removal are Settings UI actions. The user selects the exact bound file at Social preview → Edit → Upload an image or removes the image, then runs verification. A fresh custom-image Boolean that matches the requested presence or absence state can satisfy that selected setting when a selected local asset remains valid and hash-bound. The Boolean does not verify pixels or exact local-file identity. Keep the UI handoff as a requested-policy finding while the remote Boolean is mismatched or unavailable; even when the setting is complete, report that remote pixels remain unverified.

Publishing Checklist Baseline

• Treat this section as the source checklist for the skill. If the target repo maintains a publishing checklist, create or update its repo-local docs/PUBLISHING_CHECKLIST.md from these same categories: documentation and structure, scrub (PII/secrets/paths/URLs/artifacts), version and release, and repository settings.
• Before going public, work through the checklist and optionally run the scrub command. When all items are checked, the repo is ready for public publishing; checklist completion does not authorize a repository visibility change. Public/private visibility needs its own separately reviewed plan and exact operation authorization.

Rule ownership

This skill owns GitHub publication readiness. Public docs can summarize publishing behavior, but release-prep agents should load this skill for the scrub checklist, repository settings, and documentation/public-boundary decisions.

• Use ls-version-bump-commits for version bump and sync behavior.
• Use ls-public-repo-identity for public identity and contact fields.
• Do not publish private maintenance state, generated local indexes, credentials, or machine paths.

Reference

• Checklist source: use Publishing Checklist Baseline in this skill unless the target repo has its own tracked checklist.
• Versioning: load ls-version-bump-commits when changing or explaining version behavior.