From eb63512607710de116bebe092d9e56548ff15475 Mon Sep 17 00:00:00 2001 From: crazyracer98 <8631139+crazyracer98@users.noreply.github.com> Date: Thu, 29 Oct 2026 06:32:18 +0000 Subject: [PATCH 1/2] docs: record close-out decisions (DF16) - ADR 0005 Consequences: a package first pushed by GITHUB_TOKEN inherits the repo's public visibility (verified at v1.0.0); replaces the "made public by hand" consequence of ADRs 0001 and 0004 - ADRs 0001 and 0004: Status pointer to 0005 for that consequence - README: GHCR visibility next to "Manage Actions access"; collection deliberately not listed on containers.dev (issue #21) and how to list it - README: features.yml actions are SHA-pinned with a version comment; the docs PR opened with GITHUB_TOKEN needs its checks started by hand - README: a missing license file in an artifact warns, doesn't fail --- README.md | 24 +++++++++++++++---- ...repo-released-with-devcontainers-action.md | 5 +++- docs/adrs/0004-collection-github-releases.md | 4 +++- .../0005-publish-to-ghcr-with-github-token.md | 6 +++++ 4 files changed, 33 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cbdc116..5911412 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,9 @@ Every feature also takes a `pins_file` option (see below). A download feature also installs upstream's license notice, from the same verified artifact, under `/usr/local/share/doc//` when the artifact -ships one; each NOTES.md has a License section. +ships one; each NOTES.md has a License section. If a pinned artifact +doesn't contain the expected license file, the install warns and +continues without the notice; it doesn't fail. ### Pin channels @@ -253,7 +255,12 @@ library and [`test/README.md`](test/README.md) the scenario tests. plus the `_global` scenarios (see [`test/README.md`](test/README.md)). Merging to `main` only tests; nothing is published. After a full release (below), its `docs` job opens a PR with the regenerated - `src//README.md` files. + `src//README.md` files. That PR is opened with `GITHUB_TOKEN`, + which doesn't trigger workflows, so start its checks by hand (close and + reopen it, or push to its branch) before merging. Its actions are + pinned by full commit SHA with a `# vX.Y.Z` comment (GitHub's + security-hardening guide calls that the only immutable pin), stricter + than base's exact-tag rule; keep that form when bumping them. - **Checks.** `prek run --all-files --hook-stage manual` runs shellcheck and the hooks in `scripts/` (install-lib drift, feature options, version bump). @@ -300,8 +307,17 @@ required), and are needed for any registry other than `ghcr.io`; to move `ghcr.io` from them to `GITHUB_TOKEN`, delete both. A feature package that already exists on GHCR and wasn't first pushed by this repository's workflow needs, once, this repository given the Write role under the -package's "Manage Actions access" settings, or GHCR denies the push. Without -`OCI_REGISTRY`, a full release publishes nothing and warns. +package's "Manage Actions access" settings, or GHCR denies the push. A +new package first pushed by `GITHUB_TOKEN` inherits this repository's +public visibility, so there's no manual "make public" step; a package +created any other way starts private. Without `OCI_REGISTRY`, a full +release publishes nothing and warns. + +The collection is public on GHCR but deliberately not listed in the +containers.dev / VS Code feature index (see issue #21). Listing it later +is a PR adding one entry to `_data/collection-index.yml` on +`devcontainers/devcontainers.github.io`'s `gh-pages` branch, after which +outside users may depend on feature ids and options. To try the targets locally: `make build release-assets release-check`; `RELEASE_TAG=v1.0.0-rc.1 make publish` shows the pre-release skip. diff --git a/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md b/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md index 9fdeef5..4600af4 100644 --- a/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md +++ b/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md @@ -7,7 +7,10 @@ collection is released through base's `release.yml` and `Makefile` contract under a repo-wide `v` tag, and a full release publishes the features with the Dev Container CLI; `features.yml` no longer publishes on `main`. `devcontainers/action` still validates the features -and generates their READMEs. +and generates their READMEs. Partly superseded by +[0005](0005-publish-to-ghcr-with-github-token.md): a package first pushed +by the release job's `GITHUB_TOKEN` is public at once, so the "made public +by hand" consequence below no longer applies to it. ## Context diff --git a/docs/adrs/0004-collection-github-releases.md b/docs/adrs/0004-collection-github-releases.md index a17b928..d810588 100644 --- a/docs/adrs/0004-collection-github-releases.md +++ b/docs/adrs/0004-collection-github-releases.md @@ -8,7 +8,9 @@ contract, on a full collection release, not by `devcontainers/action` on every push to `main`. Partly superseded by [0005](0005-publish-to-ghcr-with-github-token.md): on `ghcr.io`, `publish` authenticates with the job's `GITHUB_TOKEN` when the registry secrets are -empty, so the secrets are no longer required there. +empty, so the secrets are no longer required there, and a package it +first pushes inherits this repository's public visibility, so the "made +public by hand" consequence below no longer applies to it. ## Context diff --git a/docs/adrs/0005-publish-to-ghcr-with-github-token.md b/docs/adrs/0005-publish-to-ghcr-with-github-token.md index b566c99..bee15e2 100644 --- a/docs/adrs/0005-publish-to-ghcr-with-github-token.md +++ b/docs/adrs/0005-publish-to-ghcr-with-github-token.md @@ -53,4 +53,10 @@ other craftainer repo's. repository's workflow needs, once, this repository given the Write role under the package's "Manage Actions access" settings, or GHCR denies the push. +- A package first pushed by the release job's `GITHUB_TOKEN` inherits + this repository's visibility and access, so in this public repository a + new feature package is public at once; there's no manual "make public" + step (verified at v1.0.0: all 10 packages pull anonymously). This + replaces the "made public by hand" consequence of ADRs 0001 and 0004. A + package created any other way still starts private. - Any other registry still needs both secrets. From 82724ab7c9788f6aa72cdf10b59ddd77cfb049c4 Mon Sep 17 00:00:00 2001 From: crazyracer98 <8631139+crazyracer98@users.noreply.github.com> Date: Thu, 29 Oct 2026 06:37:31 +0000 Subject: [PATCH 2/2] docs: address DF16 review findings (DF16) --- README.md | 23 +++++++++---------- ...repo-released-with-devcontainers-action.md | 7 +++--- docs/adrs/0004-collection-github-releases.md | 6 +++-- .../0005-publish-to-ghcr-with-github-token.md | 10 +++++--- 4 files changed, 26 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5911412..f33e2ab 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,11 @@ Each feature's NOTES.md has the full usage; after each full release, Every feature also takes a `pins_file` option (see below). A download feature also installs upstream's license notice, from the same -verified artifact, under `/usr/local/share/doc//` when the artifact -ships one; each NOTES.md has a License section. If a pinned artifact -doesn't contain the expected license file, the install warns and -continues without the notice; it doesn't fail. +verified artifact, under `/usr/local/share/doc/` when the artifact +ships one; each NOTES.md has a License section and names the directory. +If a feature that installs a notice doesn't find the expected license +file in its pinned artifact, the install warns and continues without the +notice; it doesn't fail. ### Pin channels @@ -257,10 +258,10 @@ library and [`test/README.md`](test/README.md) the scenario tests. release (below), its `docs` job opens a PR with the regenerated `src//README.md` files. That PR is opened with `GITHUB_TOKEN`, which doesn't trigger workflows, so start its checks by hand (close and - reopen it, or push to its branch) before merging. Its actions are - pinned by full commit SHA with a `# vX.Y.Z` comment (GitHub's - security-hardening guide calls that the only immutable pin), stricter - than base's exact-tag rule; keep that form when bumping them. + reopen it, or push to its branch) before merging. `features.yml`'s + actions are pinned by full commit SHA with a `# vX.Y.Z` comment (as + GitHub's secure-use reference recommends), stricter than base's + exact-tag rule; keep that form when bumping them. - **Checks.** `prek run --all-files --hook-stage manual` runs shellcheck and the hooks in `scripts/` (install-lib drift, feature options, version bump). @@ -295,10 +296,8 @@ collection tag. Publishing needs, once, in the repository's Actions settings, only the `OCI_REGISTRY` variable set to `ghcr.io`; no secrets. `make publish` then -pushes with the release job's `GITHUB_TOKEN` (as `GITHUB_ACTOR`), which -works once template-sync has brought in a base `release.yml` whose `build` -job grants `packages: write`; until then GHCR denies the push and -`make publish` fails +pushes with the release job's `GITHUB_TOKEN` (as `GITHUB_ACTOR`); the +synced `release.yml`'s `build` job grants it `packages: write` ([ADR 0005](docs/adrs/0005-publish-to-ghcr-with-github-token.md)). `OCI_IMAGE_NAME` is optional and defaults to `craftainer/devcontainer-features`. The `OCI_REGISTRY_USERNAME` and diff --git a/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md b/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md index 4600af4..fe2e082 100644 --- a/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md +++ b/docs/adrs/0001-one-collection-repo-released-with-devcontainers-action.md @@ -7,10 +7,11 @@ collection is released through base's `release.yml` and `Makefile` contract under a repo-wide `v` tag, and a full release publishes the features with the Dev Container CLI; `features.yml` no longer publishes on `main`. `devcontainers/action` still validates the features -and generates their READMEs. Partly superseded by +and generates their READMEs. Corrected by [0005](0005-publish-to-ghcr-with-github-token.md): a package first pushed -by the release job's `GITHUB_TOKEN` is public at once, so the "made public -by hand" consequence below no longer applies to it. +by a workflow's `GITHUB_TOKEN` (as this ADR's `features.yml` publish job +also did) inherits this repository's public visibility, so the "made +public by hand" consequence below was never needed for such a package. ## Context diff --git a/docs/adrs/0004-collection-github-releases.md b/docs/adrs/0004-collection-github-releases.md index d810588..06771eb 100644 --- a/docs/adrs/0004-collection-github-releases.md +++ b/docs/adrs/0004-collection-github-releases.md @@ -9,8 +9,10 @@ every push to `main`. Partly superseded by [0005](0005-publish-to-ghcr-with-github-token.md): on `ghcr.io`, `publish` authenticates with the job's `GITHUB_TOKEN` when the registry secrets are empty, so the secrets are no longer required there, and a package it -first pushes inherits this repository's public visibility, so the "made -public by hand" consequence below no longer applies to it. +first pushes with `GITHUB_TOKEN` inherits this repository's public +visibility, so the "made public by hand" consequence below no longer +applies to it (a package first pushed with the secrets still starts +private). ## Context diff --git a/docs/adrs/0005-publish-to-ghcr-with-github-token.md b/docs/adrs/0005-publish-to-ghcr-with-github-token.md index bee15e2..37045af 100644 --- a/docs/adrs/0005-publish-to-ghcr-with-github-token.md +++ b/docs/adrs/0005-publish-to-ghcr-with-github-token.md @@ -3,7 +3,10 @@ ## Status Accepted. Partly supersedes -[0004](0004-collection-github-releases.md). +[0004](0004-collection-github-releases.md), and corrects the "made public +by hand" consequence of +[0001](0001-one-collection-repo-released-with-devcontainers-action.md) and +0004 (see Consequences). ## Context @@ -45,7 +48,8 @@ other craftainer repo's. - On GHCR, publishing needs only the `OCI_REGISTRY` variable, once this repo's synced `release.yml` carries `packages: write`. Until template-sync brings it in, GHCR denies a full release's push when the - secrets are empty, and `publish` fails naming that cause. + secrets are empty, and `publish` fails naming that cause. (Template-sync + v1.11.6 brought it in before v1.0.0.) - Moving an existing setup from the secrets to `GITHUB_TOKEN` means deleting both secrets; leaving one fails, and leaving both keeps using them. @@ -57,6 +61,6 @@ other craftainer repo's. this repository's visibility and access, so in this public repository a new feature package is public at once; there's no manual "make public" step (verified at v1.0.0: all 10 packages pull anonymously). This - replaces the "made public by hand" consequence of ADRs 0001 and 0004. A + corrects the "made public by hand" consequence of ADRs 0001 and 0004. A package created any other way still starts private. - Any other registry still needs both secrets.