ethos-gemkit 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5445351e6ccbd6c2155a603d7c7fcf5d57e3e6a2e275cafa307431c4f4ae63fb
-  data.tar.gz: 8b2a74b858376f970c096b2599e5607eb88ca8b78e2ba53f11485d4a2b4d8059
+  metadata.gz: ea8ac801fd96cef32c35240e93271d04792235c4121c95f8261918f87795b2b1
+  data.tar.gz: 87a5464f90175cd5cf5f088f573ab2d47886ea2a702f5cb183f722081eb8bb47
 SHA512:
-  metadata.gz: 9cdf0c22ba2d534f270e02904ddc018ebad5448b68bf656ecdd3fceea8f8408b241f108da2f6024a253c67d291d63dbae7e13e3a3fd14c628d8bdcaeab2a5138
-  data.tar.gz: d9464b72094dafe244db34ac048e8dda59154784df181db4005c674b217fe946f8d873ecb323617531543b5faa13ffde4f22af1d44b352f40f5576209ed41033
+  metadata.gz: eb7aef3f0ccab2964c6a318649f72fbdc0f9fe9615814828c4161c386463794f10bcffc2383f001bfe9d7ba12bb46ff53a3e2280dc18481508df6b768ac1d62c
+  data.tar.gz: 74ba19f731bbbcfaa9a113e5d138929636fab47e2c35120ba410ed40019f04a797546d43911e18ef5b1bc5cac37f2953e6df277c974300f9554df1a5a64134c3

data/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-11-05
+
+
+### Documentation
+
+- clarify current setup
+
+- document checksums for frozen installs
+
+- distinguish source fixes from workflow retries
+
+
+
+
+### Fixed
+
+- preserve checksums during preparation
+
+
+
+## [0.2.0] - 2026-11-04
+
+
+### Added
+
+- support native private publishing and project setup
+
+
+
+
+### Documentation
+
+- document the published Gemkit release
+
+- clarify per-gem publishers and safe retries
+
+
+
+
+### Fixed
+
+- show preparation progress and live command output
+
+
+
 ## [0.1.0] - 2026-11-04
 
 

data/README.md

@@ -4,9 +4,21 @@ Shared development defaults for Ethos Link gems: Ruby 4, Standard, optional Rail
 8 linting, hooks, package checks and one shared release workflow. The toolkit
 belongs in the development/test Gemfile, never a consumer's runtime gemspec.
 
-During bootstrap, pin the Git dependency and workflow callers to the same reviewed
-commit; the toolkit has not been published. See the working
-[Cloudflare Tunnel Gemfile](https://github.com/ethos-link/cloudflare-tunnel/blob/feat/ethos-gemkit/Gemfile).
+Install the published gem in the development/test Gemfile:
+
+```ruby
+gem "ethos-gemkit", "0.2.1", group: [:development, :test], require: false
+```
+
+Pin workflow callers to the full commit behind the installed Gemkit release tag.
+Resolve that commit with:
+
+```sh
+git ls-remote https://github.com/ethos-link/ethos-gemkit.git 'refs/tags/v0.2.1^{}'
+```
+
+Upgrade the gem version and workflow pins together. Consumer READMEs should cover
+their own APIs and checks, then link here for shared setup and release details.
 
 A standard gem needs this Rakefile:
 
@@ -41,6 +53,21 @@ release tasks while a repository is adopting the toolkit.
 `bundle exec rake verify` runs lint, registered checks, a disposable native gem
 build, and git-cliff validation.
 
+## Private gem access
+
+To install private gems locally, use a GitHub personal access token (classic)
+with `read:packages` and access to the package. Configure Bundler once, replacing
+`USERNAME` and `TOKEN` with your credentials:
+
+```sh
+bundle config set --global https://rubygems.pkg.github.com/ethos-link USERNAME:TOKEN
+```
+
+Keep credentials out of Gemfiles. Each gem documents its scoped source block.
+Actions publishing uses `GITHUB_TOKEN`; installing another private repository's
+package requires that repository to grant the workflow access or an explicit
+token. See [GitHub's registry guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry).
+
 ## Releasing a gem
 
 **Run `release:prepare` from clean, up-to-date `main`.** It creates the conventional
@@ -50,31 +77,65 @@ Ordinary feature/fix PRs run verification; only a release PR starts publication.
 
 ### One-time prerequisites
 
+- Commit `Gemfile.lock`. Before its first commit, run
+  `bundle lock --add-checksums`; frozen CI installs reject empty registry
+  checksum entries, even when the gems are already installed locally.
 - Ignore `/.bundle/`, `/vendor/bundle/` and `/pkg/` in `.gitignore`. The shared
   workflows use Ruby setup's native `vendor/bundle` cache; generated files must
   leave the release checkout clean.
 - Install the bundle, Git, git-cliff and GitHub CLI. Configure your Git identity,
   authenticate with `gh auth login`, and install hooks with
   `bundle exec lefthook install`. You need permission to push branches and open PRs.
-- Public gems: configure RubyGems trusted publishing for the gem. Use environment
-  `rubygems`, workflow filename `release.yml`, and the consumer owner/repository.
-  For a consumer such as Tunnel, set workflow repository owner `ethos-link` and
-  workflow repository `ethos-gemkit`. For Gemkit's own publisher, leave those
-  optional workflow-repository fields blank because it is the same repository.
+- Public gems: configure a matching RubyGems trusted publisher for **each gem**
+  before merging its first release PR. Use the exact settings below. Gemkit's
+  publisher does not authorize consumer gems.
 - A new gem also needs a pending trusted publisher. Supply its numeric RubyGems
   owner through the caller's `rubygems-owner` input or the repository/organization
-  variable `RUBYGEMS_OWNER` (the Ethos account used by Tunnel is `27209`).
-- Private gems: set the GitHub Packages registry profile and pass a scoped
-  `PACKAGES_TOKEN` secret to the release workflow. The two profiles use the same
-  native `gem push` with their respective host and credentials.
-- Configure the `rubygems` GitHub environment to allow releases from `main` and
-  `v*` tags. Grant the release workflow contents-write and id-token-write
-  permissions; repository rules must permit its release tags.
+  variable `RUBYGEMS_OWNER` (the publisher account used by Tunnel is `27209`).
+- Private gems: set `registry: github_packages`. Publishing uses the workflow's
+  short-lived `GITHUB_TOKEN`; the package must grant its repository Actions access.
+  Pass `PACKAGES_TOKEN` only when an explicit token override is needed. Local
+  installation from other private repositories still needs `read:packages` access.
+- Configure the `rubygems` GitHub environment to allow `main` and `v*` tags.
+  Release callers grant `contents: write`, `id-token: write` and `packages: write`.
+  Repository rules must permit the workflow's annotated release tags.
 
 The SDK release workflow listens directly for merged release PRs and version-tag
 pushes. Consumer callers must listen for both `pull_request: types: [closed]`
-against `main` and `push: tags: ["v*"]`, and pin the same SDK commit as the Gemfile.
-See the [Tunnel caller](https://github.com/ethos-link/cloudflare-tunnel/blob/feat/ethos-gemkit/.github/workflows/release.yml).
+against `main` and `push: tags: ["v*"]`, and pin the commit matching the installed
+Gemkit release.
+See the [Tunnel caller](https://github.com/ethos-link/cloudflare-tunnel/blob/main/.github/workflows/release.yml).
+
+Projects keep their own checks. Engines can register `checks: [ci:local]` in
+`.ethos-gemkit.yml` and have that task run `bin/ci`. Set the release caller's
+optional `build-setup` input to provision those checks' dependencies, such as
+PostgreSQL or browser packages. Setup runs only in the read-only build job;
+publishing credentials remain in the separate publish job.
+
+### RubyGems trusted-publisher settings
+
+On RubyGems, open the **consumer gem's** page, then **Trusted publishers**. For
+Cloudflare Tunnel, create or update the publisher with these exact values:
+
+| RubyGems field | Value |
+|---|---|
+| Repository owner | `ethos-link` |
+| Repository name | `cloudflare-tunnel` |
+| Workflow filename | `release.yml` |
+| Environment | `rubygems` |
+| Workflow Repository Owner | `ethos-link` |
+| Workflow Repository Name | `ethos-gemkit` |
+
+The repository identifies the consumer; the Workflow Repository fields identify
+the repository containing the shared workflow file. Those last two fields are
+required for consumers,
+even though RubyGems labels them optional. For another consumer, substitute its
+repository name. For Gemkit itself, use repository name `ethos-gemkit` and leave
+both Workflow Repository fields blank because the workflow is in the same repo.
+
+The numeric `rubygems-owner` input identifies the account for pending publishers;
+it does not register a publisher or grant access to a consumer gem. See the
+[upstream reusable-workflow instructions](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows).
 
 ### Prepare and review
 
@@ -96,13 +157,15 @@ bundle exec rake 'release:prepare[1.2.0]'
 ```
 
 For an initial, unpublished version that is already in the gemspec and has no
-tag, an explicit current version is supported. Gemkit's initial release can use
-`bundle exec rake 'release:prepare[0.1.0]'` after pending-publisher setup.
-
-The task checks the working tree, canonical origin, current main, installed hooks
-and target tag. It creates `chore/release-vX.Y.Z`, updates the version and
-changelog, runs `bundle lock --local` and the full `rake verify`, then commits the
-three metadata files with hooks enabled, pushes the branch, and opens a
+tag, an explicit current version is supported. For example, a new gem starting
+at 0.1.0 can use `bundle exec rake 'release:prepare[0.1.0]'` after pending-publisher
+setup.
+
+The task prints each step and streams command output as it runs. It checks the
+working tree, canonical origin, current main, installed hooks and target tag.
+It creates `chore/release-vX.Y.Z`, updates the version and
+changelog, runs `bundle lock --add-checksums` and the full `rake verify`, then
+commits the three metadata files with hooks enabled, pushes the branch, and opens a
 `chore(release): prepare vX.Y.Z` PR. Main stays unchanged. You can also start on
 that exact pre-created release branch if its HEAD still equals `origin/main`.
 When starting from main, a leftover local release branch is recreated only if
@@ -131,8 +194,9 @@ start another workflow. Existing manually pushed annotated version tags remain a
 supported trigger and receive full canonical-tag verification.
 
 Publish and notes jobs never check out or evaluate consumer code. Public gems
-use short-lived OIDC credentials; private gems use the supplied scoped token.
-No registry fallback exists. Live private publication still needs a private pilot.
+use short-lived OIDC credentials; private gems use the workflow token or an
+explicit override. Both profiles push the same verified artifact to their
+configured host; no registry fallback exists.
 
 ### Failures and retries
 
@@ -143,7 +207,25 @@ If the commit/push succeeded but opening the PR failed, use
 `gh pr create --base main --head chore/release-vX.Y.Z --fill` after fixing access.
 There is no journal or automatic reset of your working tree.
 
-For CI failures, retry **failed jobs in the original run** within GitHub's 30-day
+If credential setup fails with `No trusted publisher configured for this workflow`,
+check the consumer's RubyGems settings against the table above. A successful
+build and tag do not mean the gem was published. When `gem push` was skipped,
+correct the publisher settings, then rerun **failed jobs only** in the original
+workflow run. This reuses its verified artifact and existing tag; do not run
+`release:prepare` again, bump the version or replace the tag for this failure.
+
+```sh
+gh run rerun RUN_ID --repo OWNER/REPOSITORY --failed
+```
+
+If a failed build needs a source fix and no tag or upload exists, keep the
+prepared version and notes. Update its `chore/release-vX.Y.Z` branch from main,
+commit the fix, run verification and open a replacement release PR. Merge that
+PR to run the corrected source. The original run stays pinned to its original
+commit; rerunning it cannot pick up a source fix. Do not replace an existing tag
+or reuse a version that was already published.
+
+For transient CI failures, retry **failed jobs in the original run** within GitHub's 30-day
 retry window. Artifacts are retained for 90 days. A failed tag step can reuse an
 existing annotated tag only when it points to the same verified commit. A failed
 notes job reuses the original artifact without uploading again. Ambiguous uploads,
@@ -166,3 +248,16 @@ divergence; live SSH credentials and host keys still require target validation.
 Develop with `bundle install` and `bundle exec rake verify`. Release and registry
 fixtures live in tests, using real Git and native gem builds with fake network
 publishers. No production rehearsal command or registry client is required.
+
+## Built by Ethos Link
+
+[Ethos Link](https://www.ethos-link.com) builds business software and integrations
+that replace manual handoffs with connected workflows. We help teams automate
+routine work, use their data and improve the processes their business runs on.
+
+- [Reviato](https://www.reviato.com): Read public review trends and collect
+  private customer feedback, so your team can decide what to improve.
+- [EthosPlaces](https://www.ethos.place): Give customers the details they need to
+  choose and visit your business, from opening hours to directions.
+- [Nuntio](https://www.nuntiohq.com): Draft, review and schedule social posts in
+  one workspace, then track each publishing result.

data/UPGRADE.md

@@ -0,0 +1,27 @@
+# Upgrading Gemkit
+
+## 0.2.1
+
+Release preparation now fetches registry checksums with Bundler instead of
+using local-only resolution. Network access to configured gem sources is
+required. Existing compatible dependency versions stay locked; complete
+checksums prevent frozen CI installs from rejecting local cache metadata.
+
+## 0.2.0
+
+Update the gem version and pin each workflow caller to the commit behind the
+matching release tag. Release callers must grant `contents: write`,
+`id-token: write` and `packages: write`, including public-gem callers: the shared
+publisher supports both registries.
+
+GitHub Packages publication now defaults to the workflow's `GITHUB_TOKEN`.
+Grant the repository Actions access to its package. Existing `PACKAGES_TOKEN`
+overrides remain supported; no new personal access token is required.
+
+Release preparation prints each phase and streams verification, hook and push
+output. Versioning, review and publication remain the same: prepare from clean,
+current main, review the release PR, then merge to publish through Actions.
+
+Projects with system-dependent checks can pass `build-setup` to the release
+workflow. Keep those checks in the project's existing command; setup only
+provisions dependencies before the read-only build job runs verification.

data/lib/ethos/gemkit/release.rb

@@ -18,8 +18,10 @@ module Ethos
 
       # Release metadata uses an ordinary branch and PR; main is never committed.
       def prepare(target = "patch")
+        progress "Checking working tree and repository"
         clean
         canonical_origin
+        progress "Fetching origin/main"
         git("fetch", "--no-tags", "origin", "refs/heads/main:refs/remotes/origin/main")
         unless git("rev-parse", "HEAD") == git("rev-parse", "origin/main")
           raise Error, "Start from clean main at origin/main; fetch and fast-forward before preparing a release"
@@ -43,13 +45,16 @@ module Ethos
         end
         literal = %(VERSION = "#{current}")
         raise Error, "Expected a literal #{literal} in version_file" unless text.include?(literal)
+        progress "Checking release tag v#{target}"
         raise Error, "Release tag already exists" unless git("tag", "--list", "v#{target}").empty? && git("ls-remote", "--tags", "origin", "refs/tags/v#{target}").empty?
         branch = "chore/release-v#{target}"
         current_branch = git("branch", "--show-current")
         unless ["main", branch].include?(current_branch)
           raise Error, "Start from main or #{branch} at origin/main"
         end
+        progress "Checking GitHub authentication"
         run("gh", "auth", "status", "--hostname", "github.com")
+        progress "Preparing #{branch}"
         if current_branch == "main"
           unless git("branch", "--list", branch).empty?
             unless git("rev-list", "--count", "origin/main..#{branch}") == "0"
@@ -60,20 +65,26 @@ module Ethos
           git("switch", "-c", branch)
         end
         Branch.check(@config.root)
+        progress "Updating version and changelog to #{target}"
         File.write(file, text.sub(literal, %(VERSION = "#{target}")))
-        run("git-cliff", "--config", "cliff.toml", "--unreleased", "--tag", "v#{target}", "--prepend", "CHANGELOG.md")
-        run("bundle", "lock", "--local")
-        run("bundle", "exec", "rake", "verify")
+        run("git-cliff", "--config", "cliff.toml", "--unreleased", "--tag", "v#{target}", "--prepend", "CHANGELOG.md", live: true)
+        progress "Updating Gemfile.lock"
+        run("bundle", "lock", "--add-checksums", live: true)
+        progress "Running verification (lint, tests, package, changelog)"
+        run("bundle", "exec", "rake", "verify", live: true)
         files = [@config.data.fetch("version_file"), "CHANGELOG.md", "Gemfile.lock"]
         unless (git("diff", "--name-only").lines.map(&:strip) - files).empty? && git("ls-files", "--others", "--exclude-standard").empty?
           raise Error, "Verification changed unrelated files; review git diff before committing"
         end
         title = "chore(release): prepare v#{target}"
         body = "Prepare #{spec.name} #{target} for publication.\n\nRecord the version, generated notes and lockfile after verification."
+        progress "Committing release metadata with hooks enabled"
         git("add", "--", *files)
-        git("commit", "-m", title, "-m", body)
+        run("git", "commit", "-m", title, "-m", body, live: true)
         clean
-        git("push", "--no-follow-tags", "--set-upstream", "origin", branch)
+        progress "Pushing #{branch}"
+        run("git", "push", "--no-follow-tags", "--set-upstream", "origin", branch, live: true)
+        progress "Opening release PR"
         url = run("gh", "pr", "create", "--repo", @config.data.fetch("repository"),
           "--base", "main", "--head", branch, "--title", title,
           "--body", "#{body}\n\nMerging this PR creates annotated tag v#{target} and publishes the verified gem.").strip
@@ -122,9 +133,19 @@ module Ethos
         run("git", *arguments).strip
       end
 
-      def run(*arguments)
+      def progress(message)
+        $stdout.puts "[release:prepare] #{message}..."
+        $stdout.flush
+      end
+
+      def run(*arguments, live: false)
         environment = {"BUNDLE_GEMFILE" => File.join(@config.root, "Gemfile"),
                        "GEM_PATH" => [*Gem.path, *Gem.loaded_specs.values.map(&:base_dir)].uniq.join(File::PATH_SEPARATOR)}
+        if live
+          success = Bundler.with_unbundled_env { system(environment, *arguments, chdir: @config.root) }
+          raise Error, "#{arguments.first(3).join(" ")} failed; see output above" unless success
+          return ""
+        end
         output, error, status = Bundler.with_unbundled_env { Open3.capture3(environment, *arguments, chdir: @config.root) }
         raise Error, "#{arguments.first(3).join(" ")} failed: #{output}#{error}" unless status.success?
         output

data/lib/ethos/gemkit/version.rb

@@ -2,6 +2,6 @@
 
 module Ethos
   module Gemkit
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ethos-gemkit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ethos Link
@@ -91,6 +91,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- UPGRADE.md
 - exe/ethos-gemkit
 - lib/ethos-gemkit.rb
 - lib/ethos/gemkit.rb