Ls Github Release Publishing

---
name: ls-github-release-publishing
description: "Use when publishing to GitHub, preparing a public release, or reviewing repo readiness. Covers public-doc structure, licensing, PII/secrets/path scrub, version checks, and repository settings."
metadata:
  version: "1.2"
---

# 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](../../workflows/ls-wf-github-repository-settings-audit/SKILL.md)
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](https://cli.github.com/manual/gh_repo_edit) 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](https://docs.github.com/en/rest/repos/repos#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.