Use the common commit process for commit messages, PR titles and dependency updates.
Follow the Hoverkraft Makefile
and workflow layout.
Use annotated Make targets for generated help and a shared run_linter helper
for lint and lint-fix. The container uses Linux amd64, the caller's UID/GID,
and the checkout's absolute path for its workspace. A failed image build stops
the command before linting.
make help lists commands. make lint-fix applies supported automatic fixes;
make lint docs/ limits linting to matching paths. Positional filters are accepted
only for lint commands; unknown standalone targets still fail. make ci runs
lint-fix and unit tests locally. VM integration tests run in hosted action-test workflows.
Internal __main-ci.yml and __pull-request-ci.yml call __shared-ci.yml.
Main supports branch and tag pushes and manual runs; PR CI also supports merge queues. Both
cancel superseded runs for the same workflow and ref. Each public action has a
dedicated test workflow, with backend and scenario variants inside it. Other actions
provide fixture setup or cleanup; assertions verify the action named by the workflow.
Consumers compose the same actions in their VM jobs.
Use test-action- caller IDs in __shared-ci.yml, following ci-github-common.
Keep additional JavaScript unit checks in the owning action's workflow through
ci-github-nodejs/actions/test, using the action's directory as working-directory,
alongside its integration scenarios. Shared CI
composes those workflows; make test is a local convenience.
Name test steps Arrange - ...,
Act - ... and Assert - ...; place assertions next to the behavior they verify.
Use explicit Cleanup - ... steps with always() for fixture teardown, even when
an action or assertion fails. Repeat Act/Assert pairs for independent cases sharing
the same fixture; repeated calls may form one Act phase when testing report isolation.
Workflows start with permissions: {} and grant only the permissions required by
each job. Keep Actions pinned and step names descriptive.
Keep the five Hoverkraft maintenance workflows alongside the CI entrypoints:
__greetings.ymlwelcomes first-time contributors on new issues and PRs.__need-fix-to-issue.ymlturns fix markers into issues after main pushes, or for a manually selected commit range.__semantic-pull-request.ymlvalidates Conventional Commit PR titles.__renovate.ymlruns dependency updates weekly and on manual dispatch.__stale.ymlmanages inactive issues and PRs daily using shared defaults.
The four collaboration workflows reuse the pinned ci-github-common workflows.
Renovate uses the organization's CI_BOT_APP_CLIENT_ID Actions variable and
CI_BOT_APP_PRIVATE_KEY Actions secret. Its GitHub App must be installed on this
repository with the permissions requested by the token-generation step.
The internal tests/fixture/prepare-vm action prepares synthetic VM configurations
without starting guests or asserting action behavior. Keep its Ubuntu image URL and
checksum aligned with tests/fixture/lima.yml.
The Lima version is maintained in actions/vm/create/action.yml.
Keep the token scoped to this repository and the repository configuration in
.github/renovate.json. Dependabot owns Actions, Dockerfile, Python and action
test-package updates. Its npm directory glob /actions/*/* matches the action
package layout used by make test;
Renovate owns Lima, Goss, the documentation image and the action .node-version
files, grouping Node.js runtime updates in one pull request.
It also maintains the Ansible fixture's .python-version and sanity image tag/digest
within the selected Ansible Core series. Review the image series when upgrading Core.
Use Node.js 24.8 or later locally; hosted unit jobs use each action's .node-version.
Run make test with Node.js's built-in test runner for focused validation and
failure cases, make lint for the Hoverkraft containerized linter, and the hosted
action-test workflows for actual
VM behavior. PR CI verifies action outcomes across successful assertions, failed
assertions and failed startup, without a consumer Makefile. It repeats tests on
the same guest to verify independent reports, collects native Goss JUnit
after assertion failures, and verifies action-owned parsing, summaries and
artifact uploads. PR comments reuse stable titles; fork and Dependabot runs skip
comments. Tests inspect native report files and GitHub artifacts directly, and
check published summaries through PR comments when comments are enabled.
Consumer workflows grant comment permissions and always schedule cleanup.
Hosted scenarios are the primary checks for public action behavior. Unit tests
call action modules directly where they add distinct coverage:
input boundaries, process ownership, failed rollback or deletion, corrupted
downloads, incomplete report transfers and report isolation after write failures.
Keep native-format preservation and private-data checks. Avoid repeating successful
or ordinary failed workflows with mocks, and assert outcomes instead of internal
calls unless ordering or deadlines are part of the contract. A unit suite is
justified by these additional cases, not by requiring one for every action.
Group JavaScript cases in named suite() blocks from node:test, with test()
for each case. Mark phases with // Arrange, // Act and // Assert. Prepare
fixtures and mocks before execution, then check results. For expected exceptions,
define the deferred call in Act and evaluate it with assert.throws or
await assert.rejects in Assert.
Repeat labeled phases when a case verifies a sequence such as failure and recovery.
Each action owns a private package.json, lockfile, .node-version and tests/
directory. Development dependencies supply the same Toolkit helpers injected by
the pinned GitHub Script action; production scripts receive them from the caller.
For example, run npm --prefix actions/vm/create ci followed by
npm --prefix actions/vm/create test for creation tests. Hosted unit jobs run
npm run test:ci: the pretest:ci hook creates the
coverage directory, then Node.js writes console results and coverage/lcov.info.
Generated coverage files are gitignored. make test discovers the action packages,
installs their locked test dependencies and runs each suite, stopping on failure.
Keep reusable test helpers in tests/helpers/ and synthetic inputs in
tests/fixture/. Keep single-use setup beside its tests; avoid adding test harnesses
that parse action YAML or emulate the GitHub Script runtime. The public actions require no npm installation
in consumer workflows.
__shared-ci.yml runs the dedicated workflows:
Workflow in .github/workflows/ |
Action | Coverage |
|---|---|---|
__test-actions-ansible-test.yml |
ansible/test |
Playbook and collection sanity success/failure, native reports |
__test-actions-ansible-test-molecule.yml |
ansible/test-molecule |
Local success/failure/timeout cleanup; VM deployment, idempotence and reboot |
__test-actions-vm-create.yml |
vm/create |
Lima and QEMU startup, usable SSH outputs, startup rollback before fallback cleanup |
__test-actions-vm-test.yml |
vm/test |
Lima and QEMU Goss success, failure, empty suites, timeout and independent reports |
__test-actions-vm-destroy.yml |
vm/destroy |
Lima and QEMU deletion, repeated deletion and unmanaged-data preservation |
__test-actions-ansible-test.yml exercises playbook tests and collection sanity success/failure
scenarios through maintained playbook execution and Ansible community testing actions.
The role-only sanity fixture uses a pinned upstream container and explicit Python
runtime; it contains no Python modules requiring a multi-version target matrix.
It verifies native report publication after failures. Adjacent JavaScript only
validates inputs and collects reports; upstream actions own test execution,
collection Python setup and containers. Playbook tests use a temporary virtual
environment and the built-in JUnit callback. Both Ansible playbook and Molecule
actions own controller setup through actions/setup-python; python-version-file
reuses the consumer's maintained pin. The hosted fixtures assert the interpreter
actually executing the native playbook. Collection sanity owns its own runtime. Consumers supply their Ansible Core pin,
Galaxy requirements and selected targets. Dependabot maintains upstream action
pins and the fixture's requirements file. Linting remains in the separate linter workflow.
Use Conventional Commits and a reviewed pull request. Publish semantic versions only after CI and consumer validation pass: major for incompatible contracts, minor for compatible features, patch for fixes. Consumers pin full commit SHAs; do not move release tags.
__prepare-release.yml applies the shared Conventional Commit release labels on
pull requests.
__release.yml runs every Monday at 08:25 UTC and supports manual dispatch.
It runs the complete shared CI on the default branch, then plans and publishes a
release for that run's exact commit using ci-github-publish. Runs from other
branches or tags are skipped. No relevant changes means no publication; the manual
force input bypasses only that no-changes guard, not CI or existing-tag checks.
To release on demand, run Internal - Release from the Actions tab with main
selected, or use:
gh workflow run __release.yml --ref mainThe release job authenticates with CI_BOT_APP_CLIENT_ID and
CI_BOT_APP_PRIVATE_KEY; OPENAI_API_KEY supplies release-summary generation.
These values can be provided through organization variables and secrets. The app needs repository
contents write and pull request read permissions for publication. Its token allows
the resulting tag push to trigger main CI.
Main CI runs on main and tag pushes, manual dispatch, and the weekly schedule.
The weekly run validates the repository without updating documentation.
After successful push or manual main CI, the shared release-actions workflow regenerates action
documentation and opens or updates its documentation PR, using squash merging.
Tag pushes and manual main CI runs refresh all action references. Internal __
workflows are excluded from generation. Documentation automation uses the same app,
with contents, pull request and workflow write permissions. Successful main-branch
documentation generation sends its artifact to the public documentation portal
through public-docs/sync-docs-dispatcher.yml.
Renovate updates the Goss version and archive SHA-256 together using the
github-release-attachments datasource. Review the Ubuntu image URL and SHA-256
together against the official release index when refreshing the fixture; boot the new image before
merging. A dependency proposal is not evidence of compatibility.
Action and public workflow reference docs are generated by make docs using the stable
CI Dokumentor Docker image pinned in the Makefile and maintained by Renovate.
Install Docker and authenticate the GitHub CLI with gh auth login first.
The container runs with your UID/GID and receives the token from gh auth token
through GITHUB_TOKEN. Quoted patterns discover actions/**/action.{yml,yaml}
and .github/workflows/!(__*).{yml,yaml} automatically, excluding internal workflows
whose filenames start with __. Change metadata and regenerate;
never hand-edit the generated reference. Keep usage guidance in the leading comments and input
descriptions of each action.yml, so the generated action readme is self-contained.
Use the pinned actions/github-script runtime and pass its injected helpers into
adjacent modules: core for outputs and status, exec for subprocesses, io for
ordinary copies, directory creation and cleanup, and glob for local report discovery.
Await helper calls so failures reach the action before it publishes outputs.
Keep Node filesystem APIs for private temporary directories, permissions, ownership,
exclusive writes/copies and atomic report publication. io.cp with force: false
silently skips existing files; it cannot replace a copy that must fail on collision.
VM report collection selects only the native goss.xml regular file.
VM commands use GNU timeout through exec.exec, with silent, bounded output
capture and literal stdin. The deadline also bounds child processes; output beyond
1 MiB is discarded and fails the command when it exits or times out.
Pass inputs through step environment variables. Keep short, straightforward scripts
inline in action.yml; retain adjacent modules for substantial code with complex
validation, execution or cleanup behavior. Avoid wrapper files and phase dispatchers
for simple step calls. This is a readability decision, not a fixed line-count rule.
Resolve external imports from github.action_path, never the consumer checkout.
Hosted workflows exercise inline action steps; unit tests call action modules
directly with Toolkit helpers. Each action owns its operation:
actions/vm/create/validates configuration, allocates private runtime directories, starts guests and rolls back failed startup.actions/vm/test/owns guest commands and file transfer inguest.cjs, executes Goss, collects native JUnit and publishes results.actions/vm/_internal/runtime.cjsvalidates owned runtimes, identifies running guests and verifies deletion for Lima and QEMU.VmReferenceprovides identity, ownership checks and presence detection. Testing uses that interface;VirtualMachineadds cleanup for creation rollback and explicit destruction. It contains no allocation or guest transport.actions/vm/_internal/command.cjsbounds subprocess execution;workspace.cjsvalidates checkout paths.
Keep code shared only when multiple actions enforce the same safety contract: runtime ownership and verified cleanup, bounded and redacted command execution, or checkout-path containment. These rules stay consistent across their callers. Action-specific behavior stays with its owner, and test transport must not inherit cleanup. Startup rollback and explicit destruction use the same verified cleanup. The internal modules are not a public API. Keep modules executable with Node.js 24; no package installation or build is required. Dependencies point from action code to shared helpers. Shared helpers do not import action code; creation and destruction use the same teardown implementation.
Expose inputs and outputs for concrete consumer needs. Test actions publish reports
and communicate success through their step outcome; they expose no report outputs.
Only vm/create exports vm, name and ssh-config for subsequent operations.
Use github.token for comments and native Ansible configuration for inventory and
collection search paths. Integration tests must verify these effects without adding
public options solely for testing.
The project logo and social preview use Hoverkraft's project template. Preserve its square geometry, wave and colors. The white icon combines connected infrastructure nodes with code brackets. The preview uses outlined Inter lettering so rendering does not depend on installed fonts. Keep the 1280 × 640 PNG export aligned with the SVG source. The preview embeds the logo geometry to remain self-contained; it is excluded from code duplication checks.
vm/test owns Goss installation, checksum verification, rendering, guest execution
and native reporting. Renovate maintains the release and archive checksum together
in actions/vm/test/goss.json; review both against the upstream release.
Its hosted fixtures cover Lima success and QEMU success, failed assertions and
empty suites. Goss state checks should be read-only.
ansible/test-molecule owns the pinned runtime, bounded execution and report
publication. Consumers own native inventory, playbook locations, resource lifecycle
and test sequence. The action supplies no base configuration or VM dependency.
__test-actions-ansible-test-molecule.yml tests a local scenario with custom playbook names,
including native failure cleanup and bounded cleanup after timeout. The fixture
creates only synthetic temporary files on the runner.
Its QEMU job additionally exercises deployment, idempotence, reboot and native failure reports against a VM created by the workflow. That scenario consumes SSH outputs and owns its reboot policy; the workflow always destroys the VM. Dependabot updates Molecule's requirements; validate both native and VM scenarios before accepting an update.
opentofu/test composes the official setup Action with native init -backend=false
and test. Consumers own module/test files, variable environment and disposable
infrastructure. No formatting, provider setup, state bootstrap or arbitrary command
is part of this action. Its dedicated workflow tests success, failed assertions,
empty suites and initialization failure, including published artifacts.
OpenTofu currently has JSON test events but no JUnit output. The adjacent reporting adapter validates complete results and emits only filenames, run names and fixed outcome messages. It discards raw diagnostic/state content. Focused unit tests protect incomplete reports, escaping and cleanup failure after passing assertions. The upstream dflook test action was considered; its container does not expose the native events or a host runtime for the consumer's following recovery scenario. Reuse official setup and native execution, keeping only this reporting gap here.
Renovate maintains the fixture's .opentofu-version and the adapter's Node version;
Dependabot maintains the upstream setup Action. Generate its reference with make docs.