Review Molecule component
Use this component when a Molecule scenario must keep its instances and shared
state between separate start and stop GitLab jobs. It uses the same
initialization and scenario discovery code as the ansible-molecule component.
Usage
include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/review-molecule@stable
inputs:
environment: review/$CI_COMMIT_REF_SLUG
The component creates review-molecule:start and review-molecule:stop. The
jobs run these Molecule commands:
- start:
molecule test --destroy=never - stop:
molecule destroy
The start job executes Molecule's complete test workflow and preserves the
instances for the review environment. The stop job destroys those instances.
Set molecule-glob and matching rules for a traditional
molecule/*/molecule.yml project layout. Use scenarios to select specific
scenarios; an empty array runs every discovered scenario.
The stop job uses the configured path and molecule-glob to add a
path-aware when: always cleanup rule, so callers can customize the start
rules without repeating the cleanup rule. Use stop-rules for exclusions or
overrides that must be evaluated before that fallback. Scheduled pipelines are
excluded by default.
If the start job itself fails, its after_script destroys resources while the
local Molecule state is still available. The stop job handles successful starts
and failures in later jobs listed through needs-stop.
Shared state and dependencies
Both jobs use the same pipeline-specific GitLab cache key. The cache keeps
the repository-local .ansible dependency directory and the selected project's
.molecule directory, including MOLECULE_EPHEMERAL_DIRECTORY. The start job
updates the cache; the stop job only reads it.
The start job also uploads the .molecule directory as a short-lived artifact,
and the stop job downloads it through needs:artifacts. This deterministic
handoff keeps cleanup working when a runner has no shared cache. Direct artifact
downloads are disabled because Molecule state can contain ephemeral SSH keys.
Before persistence, the start job removes the temporary Ansible Galaxy token and
makes generated state readable by the GitLab Runner helper. A needs chain
prevents destruction before the start job has persisted its state.
Each scenario stores its ephemeral state below a separate scenario-named directory. This prevents a multi-scenario lifecycle from reusing another scenario's inventory or instance state while keeping start and stop state paths stable.
When you set RESOURCE_NAMESPACE, the component appends the scenario name to
the value while each lifecycle action runs. For example, a base value of
ci-123-review becomes ci-123-review-default for the default scenario.
Underscores in the scenario name become hyphens in the resource namespace.
For example, podman_compose becomes ci-123-review-podman-compose.
Molecule still uses the original scenario name for its state directory and
commands. The start and stop jobs use the same namespace for each scenario.
Keep the base value short enough for the provider's hostname limit after the
scenario and platform names are appended.
The default image uses Podman with the VFS storage driver. The runner must allow
nested containers; use tags to select an appropriate runner. Do not store
credentials in Molecule state because GitLab caches are not secret stores.
Inputs
| Name | Description | Default | Type |
| --- | --- | --- | --- |
| args | Additional whitespace-separated arguments passed to every Molecule command. | string | |
| environment | GitLab review environment name. | int | string |
| environment-url | Optional URL exposed by the review environment. | $CI_ENVIRONMENT_URL | string |
| image | Ansible execution-environment image with Molecule and Podman. | ${CI_TOOLS_REPO}/ansible-ee:${CI_TOOLS_COMPONENT_VERSION} | string |
| molecule-glob | Scenario discovery glob relative to path. | extensions/molecule/**/molecule.yml | string |
| name | Name prefix for the start and stop jobs. | molecule | string |
| needs-start | Jobs that must complete before the start job. | [] | array |
| needs-stop | Additional jobs that must complete before the stop job. | [] | array |
| path | Ansible project or collection root. | . | string |
| rules | Rules controlling when the start and stop job runs. | [{"if":"$CI_PIPELINE_SOURCE == \"schedule\"","when":"never"}] | array |
| scenarios | Scenario names to run. An empty array runs every discovered scenario. | [] | array |
| stage | Pipeline stage for all review Molecule jobs. | test | string |
| tags | Runner tags required by the lifecycle jobs. | [] | array |
| timeout | Maximum duration of each lifecycle job. | 2h | string |