Skip to content

Add GitHub Actions CI page and link DevKit from Hello OpenVox - #465

Draft
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/module-ci
Draft

Add GitHub Actions CI page and link DevKit from Hello OpenVox#465
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/module-ci

Conversation

@miharp

@miharp miharp commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Closes #464

What this adds

New page: devkit/ci.md ("Module CI with GitHub Actions"), in the sidebar as "GitHub Actions CI" between "Consistent Style" and "Using VoxBox in CI".

  • What gha-puppet's basic.yml expects to find in the module before it can run: a Gemfile (test group with voxpupuli-test, puppet_metadata, and openvox reading OPENVOX_GEM_VERSION), a Rakefile, and a metadata.json with a requirements entry. jig new module produces all three; for any existing module with a metadata.json, jig convert regenerates the first two.
  • The ten-line ci.yml that calls the reusable workflow, a table of the three jobs it produces and which rake tasks each runs, and a table of the with: inputs (taken from basic.yml on the v4 tag rather than the README).
  • How to reproduce the same checks locally, and how to switch to beaker.yml for acceptance tests (links to the existing guide).
  • A lighter parser-validate-and-lint-only workflow for repositories that don't want the full toolchain, with a note on what it can't catch, and that neither workflow applies the manifest.
  • Troubleshooting entries for the failures a module without those files produces (Could not locate Gemfile, unit → skipped, metadata2gha errors).

Getting Started page: a third Next Steps bullet pointing to the Developer Tooling section and the new CI page. The Hello OpenVox walkthrough previously had no path to the DevKit docs at all, which is how the question in #464 came up.

Verification

  • markdownlint-cli2 clean on both touched files.
  • bundle exec jekyll build succeeds; the page renders under ecosystem/latest/devkit/ci.html, the sidebar entry appears, and every internal link and anchor on the new page resolves to an existing page.
  • The Gemfile and Rakefile examples mirror jig's current module template and puppet-nftables, so they match what the tooling generates today.

Assisted by Claude.

Add devkit/ci.md covering the voxpupuli/gha-puppet reusable workflow:
the prerequisite (voxpupuli-test wired in, via the setup page or
jig new module / jig convert), what the module needs first (Gemfile,
Rakefile, metadata.json with an openvox or puppet requirement), the
workflow file and its inputs, how the jobs map onto rake tasks, a
lighter parser-validate-only alternative, and the failure modes seen
when the prerequisites are missing.

Add a Next Steps bullet on the Getting Started page pointing at the
Developer Tooling section, which previously had no path there.

Closes OpenVoxProject#464

Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@fsteinel

fsteinel commented Aug 29, 2026

Copy link
Copy Markdown

maybe out of scope:
what is jig convert is there something to read for me as a ruby and openvox beginner
EDIT:
ah, found and usinǵ https://github.com/voxpupuli/jig/releases#release-v2.3.1

fsteinel added a commit to fsteinel/ffnord-puppet-gateway that referenced this pull request Aug 29, 2026
fsteinel added a commit to fsteinel/ffnord-puppet-gateway that referenced this pull request Aug 29, 2026
miharp added a commit to miharp/ffnord-puppet-gateway that referenced this pull request Aug 30, 2026
Minimal setup following the OpenVox "Module CI with GitHub Actions"
guide (OpenVoxProject/openvox-docs#465): metadata.json, Gemfile,
Rakefile, and a workflow calling voxpupuli/gha-puppet basic.yml.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@miharp
miharp marked this pull request as draft August 31, 2026 10:34
@miharp

miharp commented Aug 31, 2026

Copy link
Copy Markdown
Contributor Author

Converting this to a draft for now. voxpupuli/jig#92 makes jig convert create metadata.json when it's missing (pre-filled from a Modulefile if there is one) and repair an incomplete one, which removes the "write metadata.json first, then run jig convert" step this page currently documents. I'll wait for that to merge and land in a Jig release, then update the prerequisites section here to match before marking this ready again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document how to add CI to a module, and link the DevKit docs from Hello OpenVox

2 participants