Summary
A user on IRC (#openvox on Libera) tried to add CI to an older Puppet module by copying the gha-puppet puppet-ci-basic.yml template, after working through the Hello OpenVox section. Every run failed with:
Could not locate Gemfile or .bundle/ directory
and the unit-test matrix was skipped, which the workflow's alls-green gate then reports as a failure.
The cause is that gha-puppet's basic.yml is a thin wrapper around bundle exec rake validate lint check plus a parallel_spec matrix derived from metadata.json. It assumes the module already has a Gemfile, a Rakefile that loads puppetlabs_spec_helper/rake_tasks, and a metadata.json. The user's module was Modulefile-based with none of those. Nothing in our docs explains those prerequisites, so the question "is this CI for modules like puppet/nftables, or is there another workflow I could use?" had no answer on the site.
Two gaps came out of this.
1. No page on adding CI to a module
gha-puppet is only mentioned in passing:
devkit/acceptance_testing.md links to it as the thing that "builds the platform matrix from your metadata.json automatically" and points at puppet-chrony's ci.yml as an example.devkit/voxbox.md mentions that Vox Pupuli modules run the shared reusable workflows.
There is no page that says: here is what a module needs before the reusable workflow will run (Gemfile, Rakefile, metadata.json, and what each of the validate, lint, check, rubocop, and parallel_spec tasks does), here is the minimal workflow file to drop into .github/workflows/, and here is what to reach for instead if you only want a syntax check (puppet parser validate + puppet-lint in a plain job) or if you want the manifest actually applied (beaker, see the acceptance testing page).
Proposed: a short "CI for your module" page in the Developer Tooling section, sitting between "Consistent Style" and "Using VoxBox in CI" in the nav. The gha-puppet README already has the minimal Gemfile and Rakefile; the page should reuse those rather than invent its own, and link to devkit/setup.html for the voxpupuli-test setup and to devkit/migrating.html for anyone converting a Modulefile-era module.
2. The Hello OpenVox page doesn't hand off to the DevKit docs
The Next Steps at the end of getting_started/index.md only offer two paths: set up a server, or read the language intro. A reader who has just written their first manifest and wants to know how to lint, test, or CI it has no pointer to the Developer Tooling section at all, which is likely how the user above ended up guessing from a Vox Pupuli template.
Proposed: add a third Next Steps bullet that links to devkit/index.html (and, once it exists, the CI page from point 1).
Evidence
Summary
A user on IRC (#openvox on Libera) tried to add CI to an older Puppet module by copying the
gha-puppetpuppet-ci-basic.ymltemplate, after working through the Hello OpenVox section. Every run failed with:and the unit-test matrix was skipped, which the workflow's
alls-greengate then reports as a failure.The cause is that
gha-puppet'sbasic.ymlis a thin wrapper aroundbundle exec rake validate lint checkplus aparallel_specmatrix derived frommetadata.json. It assumes the module already has aGemfile, aRakefilethat loadspuppetlabs_spec_helper/rake_tasks, and ametadata.json. The user's module wasModulefile-based with none of those. Nothing in our docs explains those prerequisites, so the question "is this CI for modules likepuppet/nftables, or is there another workflow I could use?" had no answer on the site.Two gaps came out of this.
1. No page on adding CI to a module
gha-puppetis only mentioned in passing:devkit/acceptance_testing.mdlinks to it as the thing that "builds the platform matrix from yourmetadata.jsonautomatically" and points at puppet-chrony'sci.ymlas an example.devkit/voxbox.mdmentions that Vox Pupuli modules run the shared reusable workflows.There is no page that says: here is what a module needs before the reusable workflow will run (
Gemfile,Rakefile,metadata.json, and what each of thevalidate,lint,check,rubocop, andparallel_spectasks does), here is the minimal workflow file to drop into.github/workflows/, and here is what to reach for instead if you only want a syntax check (puppet parser validate+puppet-lintin a plain job) or if you want the manifest actually applied (beaker, see the acceptance testing page).Proposed: a short "CI for your module" page in the Developer Tooling section, sitting between "Consistent Style" and "Using VoxBox in CI" in the nav. The
gha-puppetREADME already has the minimalGemfileandRakefile; the page should reuse those rather than invent its own, and link todevkit/setup.htmlfor thevoxpupuli-testsetup and todevkit/migrating.htmlfor anyone converting aModulefile-era module.2. The Hello OpenVox page doesn't hand off to the DevKit docs
The Next Steps at the end of
getting_started/index.mdonly offer two paths: set up a server, or read the language intro. A reader who has just written their first manifest and wants to know how to lint, test, or CI it has no pointer to the Developer Tooling section at all, which is likely how the user above ended up guessing from a Vox Pupuli template.Proposed: add a third Next Steps bullet that links to
devkit/index.html(and, once it exists, the CI page from point 1).Evidence
trixie-try3)gha-puppetREADME, "Gemfile integration examples" and "Rakefile integration example": https://github.com/voxpupuli/gha-puppet#gemfile-integration-examples