Test Execution Instructions

This guide walks a tester through configuring a test environment, defining its secrets, and running the compliance pipeline in GitLab CI. Secrets are supplied as individual GitLab CI/CD variables; no secrets file is committed to the repository.

1. Define the project and targets in `assets.yml`

assets.yml is the single source of non-secret project and target data. It is both an Ansible inventory and the input GitLab CI validates.

Project metadata

Under all.vars.test_project, set:

all:
  vars:
    test_project:
      id: "baggage-handling"          # unique project identifier
      name: "Baggage Handling HLC"    # display name for reports
      environment: "test"             # must match TARGET_ENVIRONMENT
      customer: "Customer X"
      location: "testserv"

The environment value is the GitLab environment scope that selects the matching secrets. test, acceptance, and production are typical values.

Targets

Add each host under the matching group in all.children, for example:

    linux_vms:
      hosts:
        linux-app-01:
          ansible_host: 192.0.2.10
          asset_type: linux_vm
          test_profiles: [iec62443, sbom]

Supported groups and their required connection settings are already defined in assets.yml:

Group	Connection	Example secret variables needed
`linux_vms`	SSH	`ANSIBLE_USER`, `ANSIBLE_PASSWORD`, `ANSIBLE_BECOME_PASSWORD`
`windows_servers` / `windows_clients` / `mssql_servers` / `hyperv_hosts`	WinRM	`ANSIBLE_USER`, `ANSIBLE_PASSWORD`
`vmware_esxi`	vCenter API	`VCENTER_HOSTNAME`, `VCENTER_USERNAME`, `VCENTER_PASSWORD`
`cisco_switches` / `cisco_firewalls`	network_cli	`ANSIBLE_USER`, `ANSIBLE_PASSWORD`, `ANSIBLE_BECOME_PASSWORD`

Keep credentials out of this file.

2. Define secrets as GitLab CI/CD variables

Open the project in GitLab: Settings → CI/CD → Variables → Add variable.

Add one variable per secret. Set the Environment scope to the exact value of all.vars.test_project.environment (for example test), so secrets are only injected into tool jobs that declare that environment.

Key	Type	Protected	Masking	Notes
`ANSIBLE_USER`	Variable	recommended	Masked	Login account, e.g. `DOMAIN\automation-user`
`ANSIBLE_PASSWORD`	Variable	yes	Masked and hidden	Login password
`ANSIBLE_BECOME_PASSWORD`	Variable	yes	Masked and hidden	Sudo/enable password (Linux, Cisco)
`VCENTER_HOSTNAME`	Variable	recommended	Masked	vCenter appliance, e.g. `vcenter.example.com`
`VCENTER_USERNAME`	Variable	recommended	Masked	e.g. `automation@vsphere.local`
`VCENTER_PASSWORD`	Variable	yes	Masked and hidden	vCenter password
`ANSIBLE_PRIVATE_KEY`	File	yes	—	Optional: SSH private key for key auth

Rules:

Define only the variables required by the targets in assets.yml.
Use Masked and hidden (GitLab 15.10+) for values containing spaces or special characters; standard Masked rejects those formats.
Do not enable CI_DEBUG_TRACE on pipelines that receive secrets.

The test:ansible job runs methodologies/ansible/scripts/build-secrets.py, which assembles these variables into a temporary vars file and passes it to Ansible via --extra-vars @<file>. Values never appear in the job log or on the process command line.

3. Run the pipeline

Push your assets.yml changes (and any repository changes) to the branch you want to test.
In GitLab, open CI/CD → Pipelines → Run pipeline (or New pipeline).
Set the pipeline variables:

Variable	Value	Purpose
`TARGET_ENVIRONMENT`	`test` (or your environment)	Selects the environment scope; must match `assets.yml`
`RUN_ANSIBLE`	`true`	Enables the infrastructure tests
`RUN_ZAP`	`true`	Enables web tests (only once the ZAP methodology is enabled)
`ANSIBLE_LIMIT`	e.g. `linux_vms` or `linux-app-01`	Optional: restrict the run to a host or group (defaults to `all`)

Start the pipeline.

The pipeline validates that TARGET_ENVIRONMENT matches assets.yml before any testing begins. A mismatch stops the run in the validate stage.

4. Check the results

Pipeline stages: validate → build → platform → test → normalize → report.

test:ansible runs the compliance checks against the selected assets.
normalize converts the tool output into the common schema.
report produces Markdown, HTML, and PDF.

Download artifacts from the pipeline page (Download artifacts on the job, or the pipeline's Artifacts menu):

artifacts/
├── raw/ansible/        native Ansible output
├── normalized/         common JSON schema
└── rendered/           Markdown, HTML, and PDF reports

5. Rotating a secret

Replace the value of the GitLab CI/CD variable under the matching environment scope. No repository change is required. Existing artifacts contain only normalized findings, never the secret values.

5.1 KiB Raw Permalink Blame History