From fe0b3b210762ef14ded52665adc69813d230d323 Mon Sep 17 00:00:00 2001 From: MrSphay Date: Fri, 15 May 2026 02:42:25 +0200 Subject: [PATCH] Exclude kit metadata from release artifacts --- README.md | 1 + agent-quickstart.md | 5 +++++ existing-project.md | 2 ++ files/AGENTS.md | 2 ++ files/project.md | 5 +++-- files/release-checklist.md | 2 +- new-repository.md | 2 ++ 7 files changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2fdf40f..84e379a 100644 --- a/README.md +++ b/README.md @@ -234,6 +234,7 @@ Actions artifacts and Gitea packages are separate storage paths. - Use `actions/upload-artifact@v3` for Gitea/Act compatibility unless the target runner is known to support newer artifact actions. - To publish a downloadable package, upload it separately to the generic package registry with `curl --upload-file` and a CI secret such as `REGISTRY_TOKEN`. - Do not place raw build artifact names directly into package URLs. Build tools often emit names with spaces, parentheses, or platform-specific punctuation. Copy artifacts to temporary package files with URL-safe names before uploading. +- Keep Codex kit files in source control when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`. - For user-facing downloads, publish both an immutable version such as `PROJECT_VERSION-SHORT_SHA` and a stable `latest` package when the repository owner wants a moving download link. - After publishing, verify the actual package URL with an authenticated `HEAD` or lightweight download check. A green build does not always prove the package is visible where users expect it. diff --git a/agent-quickstart.md b/agent-quickstart.md index 46ec1e2..73313c9 100644 --- a/agent-quickstart.md +++ b/agent-quickstart.md @@ -17,6 +17,7 @@ Preserve unrelated user changes. Replace all applicable placeholders and remove non-applicable placeholder sections. Keep AGENTS.md and .codex/project.md aligned with real commands and artifact paths. Update README.md whenever blueprint.md or blueprint.json changes. +Exclude Codex kit metadata from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested. Run git diff --check before finishing. Run the cheapest reliable verification command, or explain why it could not run. ``` @@ -117,6 +118,10 @@ Do package upload URLs include raw build filenames? yes -> copy artifacts to URL-safe filenames first, then upload those names no -> continue +Do user-facing release artifacts include Codex kit metadata such as AGENTS.md, .codex/, blueprint files, template workflows, or agent handoff notes? + yes -> exclude those files unless the user explicitly asked to ship repository-maintenance files + no -> continue + Is the work interrupted, risky, or multi-session? yes -> update docs/agent-handoff.md no -> no handoff file is required diff --git a/existing-project.md b/existing-project.md index 1e8065e..793f318 100644 --- a/existing-project.md +++ b/existing-project.md @@ -118,6 +118,8 @@ If CI already exists: Treat workflow-run artifacts and Package Registry packages as different outputs. If the project expects user-downloadable packages, confirm there is an explicit package publish step in addition to any `actions/upload-artifact` step. When adding or repairing package publishing, copy build outputs to URL-safe filenames before uploading and verify the final package URL after the workflow succeeds. +Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`. + If CI does not exist: - add `.gitea/workflows/build.yml` from the template, diff --git a/files/AGENTS.md b/files/AGENTS.md index b0e5291..f4e7e0a 100644 --- a/files/AGENTS.md +++ b/files/AGENTS.md @@ -27,6 +27,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION - Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval. - Dependency, compliance, and release dry-run automation must report findings only. Do not auto-update dependencies, auto-open PRs, create tags, publish packages, or create releases without explicit user approval. - Gitea Actions artifacts are not Gitea Package Registry packages. If the user expects a package/download entry, add an explicit registry publish step and verify the package URL after the workflow succeeds. +- Keep Codex kit files in source control when they are useful for agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly asks to ship repository-maintenance files. ## Commands @@ -69,6 +70,7 @@ ARTIFACT_NAME - Prefer local processing for user data. - Keep CI publishing secrets in repository or organization secrets, not in tracked files. `REGISTRY_TOKEN` is the default package publishing secret name for the Gitea workflow template. - Use URL-safe package filenames when publishing to a registry. Do not put raw artifact names with spaces or punctuation directly into upload URLs. +- Do not include Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, or agent handoff notes in downloadable release artifacts unless explicitly requested. - Ensure `.gitignore` covers local config, build outputs, logs, temporary files, and secret material for the detected stack. ## Finish Checklist diff --git a/files/project.md b/files/project.md index 763efe8..24650af 100644 --- a/files/project.md +++ b/files/project.md @@ -66,7 +66,8 @@ Before a release: 2. verify CI is green, 3. verify download links, 4. update README and changelog, -5. create a tag, -6. create the release. +5. verify release artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless the user explicitly wants those shipped, +6. create a tag, +7. create the release. Do not create releases unless the user explicitly asks for a release. diff --git a/files/release-checklist.md b/files/release-checklist.md index bf3fa73..55b5398 100644 --- a/files/release-checklist.md +++ b/files/release-checklist.md @@ -23,6 +23,7 @@ ## Artifacts - [ ] Artifacts are uploaded. +- [ ] User-facing artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless explicitly requested. - [ ] Download links work. - [ ] Package registry links work if used. - [ ] Installer/portable/archive naming is clear. @@ -33,4 +34,3 @@ - [ ] Release notes written. - [ ] Release published. - [ ] Post-release download smoke test completed. - diff --git a/new-repository.md b/new-repository.md index b27e422..b6c05c6 100644 --- a/new-repository.md +++ b/new-repository.md @@ -163,6 +163,8 @@ upload artifacts Only publish artifacts to a package registry when the artifact names and credentials are known. `actions/upload-artifact` creates a workflow-run artifact, not a Gitea Package Registry package. If users need a package/download entry, add a separate generic package upload step with `REGISTRY_TOKEN`, copy artifacts to URL-safe filenames before upload, and verify the final package URL after the workflow succeeds. +Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`. + For releasable projects, config tools, apps, or repositories that process user data, secrets, or deployment files, also add `.gitea/workflows/security-scan.yml`. Keep the scheduled workflow conservative and review false positives before silencing checks. For active repositories, also add `.gitea/workflows/repo-cleanup.yml`. It should report cleanup candidates only; it must not delete files, branches, packages, or releases automatically.