ansible-testing/docs/secrets.md

# Environment-Specific Secrets

GitLab CI/CD variables are the secret source of record. `assets.yml` contains
only non-secret project, host, and test-profile data.

## Environment Selection

Start a pipeline with `TARGET_ENVIRONMENT` set to the intended GitLab
environment scope, for example `test`, `acceptance`, or `production`. The value
must exactly match `all.vars.test_project.environment` in `assets.yml`.

Tool jobs declare:

```yaml
environment:
  name: "$TARGET_ENVIRONMENT"
  action: verify
```

GitLab therefore injects variables matching that environment scope only into
tool jobs. Validation and report jobs do not declare an environment and should
not receive these credentials.

Configure each secret under **Settings > CI/CD > Variables** with:

- an exact environment scope such as `test` or `production`;
- **Protected** enabled for protected environments;
- **Masked** or **Masked and hidden** where the value format permits it;
- **File** type for keys, certificates, and structured variable files.

Do not enable `CI_DEBUG_TRACE` in pipelines that receive secrets.

## Ansible Variables

Define credentials as individual environment-scoped **Variable** entries (not a
single File variable), under **Settings > CI/CD > Variables**:

| GitLab variable | Ansible variable | Purpose |
| --- | --- | --- |
| `ANSIBLE_USER` | `ansible_user` | Login account |
| `ANSIBLE_PASSWORD` | `ansible_password` | Login password |
| `ANSIBLE_BECOME_PASSWORD` | `ansible_become_password` | Sudo / enable password |
| `VCENTER_HOSTNAME` | `vcenter_hostname` | vCenter appliance address |
| `VCENTER_USERNAME` | `vcenter_username` | vCenter account |
| `VCENTER_PASSWORD` | `vcenter_password` | vCenter password |

Set only those required by the target types declared in `assets.yml`. Values
containing spaces or special characters (for example a Windows `DOMAIN\user`
password) must use **Masked and hidden** (GitLab 15.10+); standard **Masked**
rejects such formats.

The `test:ansible` job runs `methodologies/ansible/scripts/build-secrets.py`,
which maps these variables to their Ansible names and writes a temporary YAML
vars file. `run.sh` passes that file with `--extra-vars @<file>` without
printing the contents or putting values in the process command line. The
temporary files live under `$CI_PROJECT_DIR/.run/secrets/` and are removed when
the job pod ends; they are never stored in artifacts.

For SSH key authentication, add `ANSIBLE_PRIVATE_KEY` as a separate
environment-scoped **File** variable. The job writes its contents to a `0600`
temporary key file and passes that path through `--private-key` when present.

The current job assumes one credential set per test environment. Environments
with distinct Windows, Linux, network, or hypervisor credentials should be split
into separate tool jobs, each referencing its own environment-scoped variables.

## ZAP Variables

ZAP authentication will use individually masked variables referenced by its
Automation Framework plan, such as `ZAP_USERNAME`, `ZAP_PASSWORD`, or
`ZAP_AUTH_HEADER_VALUE`. Define only those required by the selected application.
The ZAP adapter and authentication plan are intentionally not enabled yet.

## Rotation

Rotate a secret by replacing the value in each GitLab environment scope. No
repository change is required. Existing artifacts contain normalized findings,
not the GitLab variable files, and the pipeline never uploads secret paths.