ci(lychee): exclude percona.com from links check

variables:

  GITLAB_CI_FILES: "templates/gitlab-ci-terraform.yml"

  LYCHEE_EXTRA_OPTS: "--exclude www.percona.com"

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **GitLab CI/CD reusable template** for Terraform/OpenTofu infrastructure-as-code pipelines. It is part of the [to-be-continuous](https://to-be-continuous.gitlab.io/doc/) ecosystem. The template provides multi-environment deployment (review, integration, staging, production) with integrated security scanning, linting, cost estimation, and cloud provider authentication (AWS, GCP, Vault).

**License:** LGPL-3.0. **Current version:** 9.0.0.

## Repository Structure

- `templates/gitlab-ci-terraform.yml` — **The main template** (~1,900 lines). This is the core of the project: a GitLab CI spec-based template defining all pipeline jobs, variables, and embedded shell scripts.

- `templates/gitlab-ci-terraform-aws.yml` — AWS OIDC variant

- `templates/gitlab-ci-terraform-gcp.yml` — GCP Workload Identity Federation variant

- `templates/gitlab-ci-terraform-vault.yml` — Vault secrets variant

- `test/` — BATS tests for shell logic extracted from the main template

- `kicker.json` — Component manifest for kicker-based validation

- `bumpversion.sh` / `post-release.sh` — Release automation scripts

## Commands

### Running Tests

Tests use [BATS](https://github.com/bats-core/bats-core) (Bash Automated Testing System). In CI, they run via the `to-be-continuous/bash` component. Locally, with BATS installed:

```bash

bats test/

```

The test helper (`test/terraform-scripts.bash`) extracts shell functions from `templates/gitlab-ci-terraform.yml` (between `BEGSCRIPT`/`ENDSCRIPT` markers) and mocks the `terraform` CLI.

### Linting

Shell scripts are linted with **shellcheck** (via the bash CI component). The CI also validates the template YAML structure using `to-be-continuous/tools/gitlab-ci` and `to-be-continuous/kicker` validation templates.

### Local CI Testing

A `.devcontainer` setup is available with `gitlab-ci-local` for running the pipeline locally. Configuration is in `.gitlab-ci-local/`.

## Architecture

### Template Design

The main template uses GitLab's **spec/inputs system** with 150+ configurable inputs.

### Jobs Hierarchy

**Stages (in order):** `build` → `test` → `package-build` → `package-test` → `infra` → `deploy` → `acceptance` → `publish` → `infra-prod` → `production`

**Extension chains:**

```

.tf-base

├── .tf-workspace  (adds init + workspace selection)

│   ├── .tf-plan  (stage: build)

│   │   ├── tf-plan-review

│   │   ├── tf-plan-integration

│   │   ├── tf-plan-staging

│   │   └── tf-plan-production

│   ├── .tf-create  (stage: infra)

│   │   ├── tf-review

│   │   ├── tf-integration

│   │   ├── tf-staging

│   │   └── tf-production  (stage: infra-prod)

│   ├── .tf-test  (stage: test)

│   │   ├── tf-test-review

│   │   ├── tf-test-integration

│   │   ├── tf-test-staging

│   │   └── tf-test-production

│   └── .tf-destroy  (stage: infra)

│       ├── tf-destroy-review

│       ├── tf-destroy-integration

│       └── tf-destroy-staging

├── tf-tfsec           (stage: test, needs: [])

├── tf-trivy           (stage: test, needs: [])

├── tf-tflint          (stage: build, needs: [])

├── tf-checkov         (stage: test, needs: [])

├── tf-infracost       (stage: test, needs: [])

├── tf-fmt             (stage: test, needs: [])

├── tf-validate        (stage: test, needs: [])

├── tf-docs            (stage: build)

└── tf-publish-module  (stage: publish)

```

**Per-environment pipeline flow:**

```

tf-plan-{env}  →  tf-test-{env}  →  tf-{env} (apply)

   (build)           (test)           (infra / infra-prod)

                                      tf-destroy-{env}  (manual, infra)

```

**Environment → branch mapping:**

| Environment | Branch           | Apply stage |

|-------------|------------------|-------------|

| review      | feature branches | infra       |

| integration | develop/integ    | infra       |

| staging     | main/master      | infra       |

| production  | main/master      | infra-prod  |

**Key behaviors:**

- Standalone validation jobs (`tf-trivy`, `tf-tflint`, `tf-fmt`, etc.) have `needs: []` — they run immediately with no dependencies

- `.tf-destroy` jobs set `dependencies: []` — they never consume artifacts from other jobs

- `.tf-create` (apply) jobs can consume plan artifacts from the corresponding `tf-plan-{env}`

- Production apply runs in its own later stage (`infra-prod`) to sequence after staging

- Validation jobs follow the `.test-policy` rules (adaptive pipeline: auto on ready MRs, manual on draft/early dev)

### Embedded Shell Scripts

The template embeds significant bash logic between `BEGSCRIPT`/`ENDSCRIPT` markers. Key functions include:

- **`unscope_variables`** — Resolves scoped variable overrides (pattern: `scoped__VAR__if__CONDITION__equals__value`) to enable per-environment variable customization

- Hook script execution (`tf-pre-init.sh`, `tf-pre-apply.sh`, `tf-post-apply.sh`, etc.)

- Backend configuration and workspace management

### Variant Templates

Cloud provider variants (AWS, GCP, Vault) are thin wrappers that add provider-specific authentication setup (OIDC, Workload Identity Federation, etc.) and include the main template.

## Git Conventions

- **Branch:** `main` (default), was previously `master`

- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) format, required for semantic-release

- **DCO:** All commits must be signed off (`git commit -s`)

- **Versioning:** Automated via semantic-release (`.releaserc.yml`)