### Concrete Example: Full Pipeline with Specific Version

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

A concrete example of including the full pipeline using OpenTofu CI/CD component version `0.10.0` and OpenTofu version `1.6.1`.

```yaml
# Using version `0.10.0`:
include:
  - component: $CI_SERVER_FQDN/components/opentofu/full-pipeline@0.10.0
    inputs:
      opentofu_version: 1.6.1

stages: [validate, test, build, deploy, cleanup]
```

--------------------------------

### Concrete Example: Using Latest Component Release

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Example for using the latest release of the OpenTofu CI/CD component. Note that `version` and `opentofu_version` must be explicitly specified as inputs. This approach may introduce breaking changes.

```yaml
# ... in case you absolutely know what you are doing and are
# aware that this may introduce breaking changes, you may use the latest release:
include:
  - component: $CI_SERVER_FQDN/components/opentofu/full-pipeline@~latest
    inputs:
      # The version must currently be specified explicitly as an input,
      # to find the correctly associated images. # This can be removed
      # once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
      version: latest # component version
      opentofu_version: 1.6.1

stages: [validate, test, build, deploy, cleanup]
```

--------------------------------

### Example Image Signature Verification

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

An example demonstrating how to verify the signature for a specific OpenTofu image reference and component version using cosign.

```shell
cosign verify "registry.gitlab.com/components/opentofu/gitlab-opentofu:0.34.0-opentofu1.6.0-alpine" \
    --certificate-identity "https://gitlab.com/components/opentofu//.gitlab-ci.yml@refs/tags/0.34.0" \
    --certificate-oidc-issuer "https://gitlab.com"
```

--------------------------------

### Example Provider Release Pipeline Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

An example pipeline definition for building and releasing an OpenTofu provider using the `provider-release` component. Ensure provider artifacts are included.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/provider-release@<VERSION>
    inputs:
      provider_namespace: my-org
      provider_name: terraform-provider-awesome
      provider_version: 1.0.0
      provider_artifacts_dir: dist/

# Example job for how the provider is built. Most likely a goreleaser job.
build:provider:
  image:
    name: goreleaser/goreleaser
    entrypoint: [""]
  script:
    # Goreleaser would place the built provider zips in dist/
    - goreleaser release ...
  # Artifacts are crucial so that the provider-release can package them!
  artifacts:
    paths:
      - dist/*.zip
```

--------------------------------

### Full Pipeline Template Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Includes a comprehensive OpenTofu pipeline with validation, planning, applying, and destroying infrastructure. Use when a complete workflow is desired.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/full-pipeline@4.7.0
    inputs:
      opentofu_version: 1.12.1

stages: [validate, test, build, deploy, cleanup]
```

--------------------------------

### Image URI Construction Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/configuration.md

Illustrates how the container image URI is constructed based on various configuration inputs. This example shows a typical resulting URI.

```plaintext
registry.gitlab.com/components/opentofu/gitlab-opentofu:4.7.0-opentofu1.12.1-alpine
```

--------------------------------

### Example Output Message

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

This is an example of the status message that the `gitlab-tofu-ctl` command outputs when it is automatically defining the HTTP backend in the `__gitlab-opentofu-backend.tf` file.

```text
gitlab-tofu: automatically defining the HTTP backend in __gitlab-opentofu-backend.tf
```

--------------------------------

### Validate and Plan Pipeline Template Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

A minimal pipeline for formatting, validating, and planning OpenTofu configurations, suitable for read-only operations. Use when only validation and planning are required.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan@4.7.0
    inputs:
      opentofu_version: 1.12.1

stages: [validate, build]
```

--------------------------------

### Setup Script for Assuming AWS IAM Role with ID Tokens

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

This shell script installs AWS CLI, assumes an IAM role using GitLab CI's OIDC token, and sets AWS credentials. It's intended to be used with the `.gitlab-tofu:id_tokens` job.

```shell
apk add --no-cache aws-cli
export $(printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s" \
    $(aws sts assume-role-with-web-identity \
        --role-arn ${GITLAB_CI_ROLE_ARN} \
        --role-session-name "GitLabRunner-${CI_PROJECT_ID}-${CI_PIPELINE_ID}" \
        --web-identity-token ${GITLAB_OIDC_TOKEN} \
        --duration-seconds 3600 \
        --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
        --output text))
aws sts get-caller-identity
```

--------------------------------

### Installing Additional Tools with apk

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Install extra tools like 'jq' within a CI/CD job by overriding the 'before_script' section. This uses the 'apk' package manager available in the gitlab-opentofu container image.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan@<VERSION>
    inputs:
      version: <VERSION>
      opentofu_version: 1.6.1

plan:
  before_script:
    - apk add jq
```

--------------------------------

### Validate, Plan, and Destroy Pipeline Template Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Offers a pipeline for formatting, validating, planning, and destroying infrastructure. Use when both apply and destroy capabilities are needed with full validation.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-destroy@4.7.0
    inputs:
      opentofu_version: 1.12.1

stages: [validate, build, deploy, cleanup]
```

--------------------------------

### Compose Custom OpenTofu Pipeline with Job Templates

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

This example demonstrates how to extend predefined OpenTofu job templates to create a custom CI/CD pipeline. It specifies the OpenTofu version and extends hidden jobs for validation and planning, including parallel planning for different environments.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/job-templates@4.7.0
    inputs:
      opentofu_version: 1.12.1

validate:
  extends: [.opentofu:validate]

plan:
  extends: [.opentofu:plan]
  parallel:
    matrix:
      - GITLAB_TOFU_ROOT_DIR: terraform/staging
      - GITLAB_TOFU_ROOT_DIR: terraform/production
```

--------------------------------

### GitLab CI/CD Job Configuration with OpenTofu Component

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/configuration.md

Example of how to include and configure the OpenTofu CI/CD component within a `.gitlab-ci.yml` file. This demonstrates setting various input parameters for job customization.

```yaml
include:
  - component: "gitlab.com/gitlab-org/gitlab-opentofu:v4.7.0"

fmt:
  <<: "${CI_PROJECT_DIR}/.gitlab/ci/common.yml"::fmt"
  inputs:
    as: "fmt"
    stage: "validate"
    root_dir: "${CI_PROJECT_DIR}/terraform"
    version: "4.7.0"
    opentofu_version: "1.12.1"
    base_os: "alpine"
    image_registry_base: "registry.example.com/my-registry"
    image_name: "my-custom-opentofu"
    image_digest: "@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    enable_id_tokens: true
    id_tokens_setup_script: ".gitlab/ci/setup-custom-id-tokens.sh"
    state_name: "production"
    environment_name: "production"
    resource_group_name: "production"
    auto_define_backend: true

plan:
  <<: "${CI_PROJECT_DIR}/.gitlab/ci/common.yml"::plan"
  inputs:
    as: "plan"
    stage: "validate"
    root_dir: "${CI_PROJECT_DIR}/terraform"
    version: "4.7.0"
    opentofu_version: "1.12.1"
    base_os: "debian"
    use_rootless_image: true
    needs: ["fmt"]
    rules: ["when: manual"]
    cache_policy: "pull"
    enable_id_tokens: true
    id_tokens_base_job_name: ".my-custom-tofu:id_tokens"
    state_name: "production"
    environment_name: "production"
    resource_group_name: "production"

apply:
  <<: "${CI_PROJECT_DIR}/.gitlab/ci/common.yml"::apply"
  inputs:
    as: "apply"
    stage: "deploy"
    root_dir: "${CI_PROJECT_DIR}/terraform"
    version: "4.7.0"
    opentofu_version: "1.12.1"
    base_os: "alpine"
    use_rootless_image: true
    needs: ["plan"]
    rules: ["when: on_success"]
    cache_policy: "pull-push"
    enable_id_tokens: true
    state_name: "production"
    environment_name: "production"
    resource_group_name: "production"
    auto_define_backend: true

```

--------------------------------

### Common Documentation Navigation Tasks

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/README.md

Provides a quick guide to accessing specific sections of the documentation for common user tasks.

```markdown
### Common Tasks
- **Start**: INDEX.md → quick-reference.md
- **Configure**: configuration.md + component-templates.md
- **Troubleshoot**: environment-and-errors.md
- **Deep dive**: gitlab-tofu-script-reference.md or gitlab-tofu-ctl-reference.md
```

--------------------------------

### Syntax and Configuration Validation Job Template Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Validates HCL syntax and configuration semantics without initializing the backend. Use for checking configuration correctness. Supports variable files for OpenTofu versions >= 1.8.0.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate@4.7.0
    inputs:
      opentofu_version: 1.12.1
      var_files: ['vars.tfvars']
```

--------------------------------

### OpenTofu Provider Installation Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Configure OpenTofu to use a provider from the GitLab OCI Registry using the `provider_installation` block in `~/.terraformrc` or a specified config file.

```hcl
provider_installation {
  oci_mirror {
    repository_template = "$CI_REGISTRY/<path-to-project>/terraform-provider-awesome"
    include             = ["opentofu-providers.gitlab.com.local/my-org/terraform-provider-awesome"]
  }
}
```

--------------------------------

### Renovate Configuration for OpenTofu Component

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Use this configuration in your Renovate setup to extend the OpenTofu component presets. This helps in automatically updating the OpenTofu version.

```json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["local>components/opentofu"],
  ...
}
```

--------------------------------

### GitLab CI Include with OpenTofu Version Input

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Example of how to include the OpenTofu component in your `.gitlab-ci.yml` file, specifying the version input. Ensure the `version` input has a `# component version` comment suffix for Renovate to correctly identify it.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@<VERSION>
    inputs:
      # The version must currently be specified explicitly as an input,
      # to find the correctly associated images. # This can be removed
      # once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
      version: <VERSION> # component version
      opentofu_version: <OPENTOFU_VERSION>

stages: [validate, test, build, deploy, cleanup]
```

--------------------------------

### Example HCL Backend Structure

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

This HCL structure represents how a backend configuration is defined within OpenTofu projects. The `auto-define-backend` command looks for blocks like this to determine if a backend is already configured.

```hcl
terraform {
  backend "TYPE" { ... }
}
```

--------------------------------

### Run OpenTofu Apply

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Applies a previously planned configuration. Uses the cached plan file by default.

```bash
gitlab-tofu apply [additional-args]
```

--------------------------------

### View OpenTofu State List and Show

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Use the `gitlab-tofu -- state list` command to view all resources in the current state, and `gitlab-tofu -- state show '<resource>'` to inspect a specific resource.

```bash
# In a custom job
gitlab-tofu -- state list
gitlab-tofu -- state show 'aws_instance.example'
```

--------------------------------

### Minimal OpenTofu Plan and Apply

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/configuration.md

Use this configuration for a basic OpenTofu plan and apply workflow. It requires specifying the OpenTofu version.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1

stages: [validate, build, deploy]
```

--------------------------------

### Configure MR Plan Fetching

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Set up MR plan fetching by extending the `.opentofu:plan` and `.opentofu:apply` templates. This requires a project access token with `read_api` scope and can be configured to use a specific token for fetching MR plans.

```yaml
plan:
  extends: [.opentofu:plan]
  artifacts:
    access: developer

apply:
  extends: [.opentofu:apply]
  variables:
    GITLAB_TOFU_MR_PLAN_TOKEN: $PROJECT_ACCESS_TOKEN
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

--------------------------------

### Initialize OpenTofu Working Directory

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Initializes the OpenTofu working directory with GitLab-specific configuration.

```bash
gitlab-tofu init [additional-args]
```

--------------------------------

### Authenticate OCI Registry

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Authenticates with the GitLab Container Registry (OCI) for provider installations. Uses the oras CLI if available, otherwise configures credentials in TF_CLI_CONFIG_FILE.

```shell
tofu_authenticate_oci
```

--------------------------------

### Accessing CI/CD Variables in OpenTofu Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Define string variables in your OpenTofu configuration to access predefined GitLab CI/CD variables. For example, 'ci_project_name' can access 'CI_PROJECT_NAME'.

```hcl
variable "ci_project_name" {
  type        = string
  description = "The name of the directory for the project."
}
```

--------------------------------

### Display OpenTofu Plan in JSON Format

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Displays the current plan in JSON format. Requires a cached plan file to be present.

```bash
gitlab-tofu plan-json
```

--------------------------------

### Initialize OpenTofu with GitLab CI/CD Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Runs `tofu init` with automatic flags for GitLab CI/CD environments. Use this to set up your OpenTofu project within a CI/CD pipeline.

```shell
tofu_init [-backend=false]
```

```bash
tofu_init -backend=false
```

--------------------------------

### OCI Provider/Module Registry Authentication

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Configure Terraform to use OCI-based providers and modules. This example shows how to specify a custom provider source and version. It uses the CI_JOB_TOKEN for authentication.

```hcl
terraform {
  required_providers {
    mycloud = {
      source  = "registry.gitlab.com/my-org/terraform-provider-mycloud"
      version = "1.0.0"
    }
  }
}
```

--------------------------------

### Validate, Plan, and Apply Pipeline

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

This is the recommended pipeline for most use cases, handling formatting, validation, planning, and applying OpenTofu configurations.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1
```

--------------------------------

### Source gitlab-tofu script in shell pipeline

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Source the script to access helper functions and variables. This setup prepares the environment for Tofu operations without executing commands directly.

```bash
. $(which gitlab-tofu)
configure_variables_for_tofu
tofu_authenticate_oci
tofu_init
tofu plan -out=custom.plan
```

--------------------------------

### OpenTofu OIDC Cloud Authentication

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Configure the OpenTofu component to use OpenID Connect (OIDC) for cloud authentication by setting `enable_id_tokens` to `true`. This example shows how to configure OIDC for AWS STS.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1
      enable_id_tokens: true

stages: [validate, build, deploy]

.gitlab-tofu:id_tokens:id_tokens:
  GITLAB_OIDC_TOKEN:
    aud: https://sts.amazonaws.com
```

--------------------------------

### Plan OpenTofu Infrastructure Changes

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Plans infrastructure changes and saves the plan to a cache file, optionally in JSON format.

```bash
gitlab-tofu plan [additional-args]
```

--------------------------------

### Format Validation Job Template Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Validates HCL formatting with recursive checks and diff output. Use for ensuring consistent code formatting. The job can be configured with a custom name and stage.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/fmt@4.7.0
    inputs:
      opentofu_version: 1.12.1
      stage: validate

fmt:
  stage: validate
```

--------------------------------

### Include Full Pipeline

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Include the full OpenTofu CI/CD pipeline. Replace `<VERSION>` with the desired component version.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/full-pipeline@<VERSION>

stages: [validate, test, build, deploy, cleanup]
```

--------------------------------

### runAutoDefineBackend Function Signature

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

This Go function executes the core logic for auto-defining the backend. It handles opening the project directory, checking for existing configurations, and creating the backend file if necessary. It outputs status messages to stderr.

```go
func runAutoDefineBackend(stderr io.Writer, args []string) error
```

--------------------------------

### Include Validate, Plan, Apply Pipeline

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Include a pipeline that focuses on validation, planning, and applying OpenTofu configurations. This excludes destroy jobs. Replace `<VERSION>` and `<OPENTOFU_VERSION>` with your desired values.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@<VERSION>
    inputs:
      opentofu_version: <OPENTOFU_VERSION>

stages: [validate, build, deploy]
```

--------------------------------

### Customize OpenTofu Job Name and Stage

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Customize the job name and stage for OpenTofu components using the `as` and `stage` inputs. This example shows how to rename the `fmt` component to `check-formatting` and assign it to the `lint` stage.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/fmt@4.7.0
    inputs:
      as: check-formatting
      stage: lint
```

--------------------------------

### OpenTofu MR Plan Review Integration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Integrate OpenTofu plan reviews into your merge requests. This setup uses a separate component for plan generation and comments on MRs, then applies changes on the default branch.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan@4.7.0
    inputs:
      opentofu_version: 1.12.1
      artifacts_access: developer
      post_mr_plan_comment: true
    rules:
      - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1
      use_mr_plan: true
    rules:
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

stages: [validate, build, deploy]
```

--------------------------------

### Import Resources into OpenTofu State

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Use the `gitlab-tofu -- import <resource> <id>` command to import existing infrastructure resources into the OpenTofu state.

```bash
# In a custom job
gitlab-tofu -- import aws_instance.example i-1234567890abcdef0
```

--------------------------------

### Variable Override Precedence Example

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/environment-and-errors.md

Demonstrates how CI/CD variables defined in `.gitlab-ci.yml` override component input defaults. Variables set at the job level have the highest precedence, followed by project-level variables, then component defaults.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/plan@4.7.0
    inputs:
      opentofu_version: 1.12.1
      root_dir: terraform/prod

variables:
  GITLAB_TOFU_STATE_NAME: production  # Overrides component default

my_plan:
  variables:
    GITLAB_TOFU_DEBUG: "true"  # Enable debug for this job only
  script:
    - gitlab-tofu plan
```

--------------------------------

### Include Job Templates

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Import all OpenTofu CI/CD jobs as hidden templates that can be extended. Replace `<VERSION>` and `<OPENTOFU_VERSION>` with your desired values.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/job-templates@<VERSION>
    inputs:
      opentofu_version: <OPENTOFU_VERSION>

stages: [...] 

fmt:
  extends: [.opentofu:fmt]

...
```

--------------------------------

### Auto-Define Backend Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

Automatically creates an HTTP backend configuration for a project. Can be run with an explicit path or implicitly by changing the directory.

```bash
# Automatically create HTTP backend configuration in /path/to/project
gitlab-tofu-ctl auto-define-backend /path/to/project

# With implicit chdir
cd /path/to/project && gitlab-tofu-ctl auto-define-backend .
```

--------------------------------

### Import Custom CA Certificates for OpenTofu

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Imports custom CA certificates. This command is intended for use with rootless initialization.

```bash
gitlab-tofu import-custom-ca-certs
```

--------------------------------

### Conditional Variable Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/environment-and-errors.md

Configure variables based on pipeline conditions using `rules`. This example sets different state names and debug flags depending on whether the pipeline is running on the default branch or a staging branch.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/plan@4.7.0
    inputs:
      opentofu_version: 1.12.1

plan:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        GITLAB_TOFU_STATE_NAME: production
        GITLAB_TOFU_USE_DETAILED_EXITCODE: "true"
    - if: $CI_COMMIT_BRANCH =~ /^staging/
      variables:
        GITLAB_TOFU_STATE_NAME: staging
```

--------------------------------

### Documentation Structure Overview

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/README.md

Illustrates the hierarchical structure of the OpenTofu documentation, showing the main entry points and their relationships.

```markdown
INDEX.md (navigation hub)
  ├→ quick-reference.md (getting started)
  ├→ configuration.md (all inputs)
  ├→ component-templates.md (all templates)
  ├→ environment-and-errors.md (variables & troubleshooting)
  ├→ gitlab-tofu-script-reference.md (shell API)
  └→ gitlab-tofu-ctl-reference.md (Go CLI API)
```

--------------------------------

### Detect Infrastructure Drift

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Runs a plan to detect infrastructure drift. Use this to identify discrepancies between your configuration and the actual infrastructure state.

```shell
detect_drift refresh-only
```

```bash
detect_drift refresh-only
if [ $? -eq 2 ]; then
  echo "Drift detected in infrastructure"
fi
```

--------------------------------

### Format OpenTofu Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Validates and formats HCL configuration files, checking formatting and showing diffs recursively.

```bash
gitlab-tofu fmt
```

--------------------------------

### Run OpenTofu Tests

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Includes the OpenTofu test component to execute test files. Specify the OpenTofu version and the directory containing test files.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/test@4.7.0
    inputs:
      opentofu_version: 1.12.1
      test_directory: ./tests
```

--------------------------------

### NewAutoDefineBackendCmd Function Signature

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

This Go function creates and returns a Cobra command for the `auto-define-backend` functionality. It configures the command's usage, short description, argument handling, and execution logic.

```go
func NewAutoDefineBackendCmd() *cobra.Command
```

--------------------------------

### Define HTTP Backend

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Automatically creates an HTTP backend configuration file if no backend is manually configured and GITLAB_TOFU_AUTO_DEFINE_BACKEND is true. Scans for existing backend blocks before creating a new one.

```shell
define_http_backend
```

```shell
export GITLAB_TOFU_AUTO_DEFINE_BACKEND=true
define_http_backend
```

--------------------------------

### Multiple Environments Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Set up the OpenTofu component to manage multiple environments (e.g., staging, production) by specifying different root directories and state names for each.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1
      root_dir: terraform/staging
      state_name: staging

  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1
      root_dir: terraform/production
      state_name: production

stages: [validate, build, deploy]
```

--------------------------------

### GitLab Tofu CTL auto-define-backend Usage

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

Use this command to automatically define HTTP backend configurations for your OpenTofu project. It requires the path to the project's root directory.

```bash
gitlab-tofu-ctl auto-define-backend <root_directory>
```

--------------------------------

### GitLab Tofu CLI Tool Usage

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

Basic usage pattern for the gitlab-tofu-ctl command-line tool. This shows how to invoke commands and pass arguments.

```bash
gitlab-tofu-ctl <command> [arguments]
```

--------------------------------

### Run OpenTofu Destroy

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Destroys managed infrastructure with automatic approval. Use with caution.

```bash
gitlab-tofu destroy [additional-args]
```

--------------------------------

### Extend OpenTofu Plan Job Template with Matrix Parallelism

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Include the 'job-templates' component to access all OpenTofu jobs as hidden templates. Extend the '.opentofu:plan' job to run with matrix parallelism across different root directories.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/job-templates@<VERSION>
    inputs:
      opentofu_version: 1.6.1

plan:
  extends: [.opentofu:plan]
  parallel:
    matrix:
      - GITLAB_TOFU_ROOT_DIR: test/
      - GITLAB_TOFU_ROOT_DIR: prod/
```

--------------------------------

### gitlab-tofu-ctl Go CLI Tool API

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/GENERATION_SUMMARY.txt

Documentation for the complete gitlab-tofu-ctl Go CLI tool API, including exported functions and commands.

```APIDOC
## Go CLI Tool (gitlab-tofu-ctl)

### Description
Provides documentation for the gitlab-tofu-ctl Go CLI tool, including its commands and exported functions.

### Commands
- **auto-define-backend**
- **mr-commenter**

### Exported Go Functions
- **main()**
- **NewAutoDefineBackendCmd()**
- **isHTTPBackendConfigured()**
- **runAutoDefineBackend()**
- **NewMRCommenterCmd()**
- **runMRCommenter()**
- **updateExistingComment()**
- **createNewComment()**
```

--------------------------------

### Fetch Merge Request Plan

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Retrieves and displays the OpenTofu plan associated with the current merge request.

```bash
gitlab-tofu fetch-mr-plan
```

--------------------------------

### Run Custom OpenTofu Commands

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Includes the OpenTofu custom-command component to execute arbitrary OpenTofu commands. Specify the OpenTofu version and provide the custom script to run.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/custom-command@4.7.0
    inputs:
      opentofu_version: 1.12.1

my-custom:
  extends: [.opentofu:custom-command]
  script:
    - gitlab-tofu state list
    - gitlab-tofu state show 'aws_instance.example'
```

--------------------------------

### Include Full Pipeline with Specific OpenTofu Version

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Include the full OpenTofu CI/CD pipeline and specify a particular OpenTofu version using the `opentofu_version` input. Replace `<VERSION>` and `<OPENTOFU_VERSION>` with your desired values.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/full-pipeline@<VERSION>
    inputs:
      opentofu_version: <OPENTOFU_VERSION>

stages: [validate, test, build, deploy, cleanup]
```

--------------------------------

### Automatic OpenTofu Backend Configuration with GitLab CI/CD Component

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/quick-reference.md

Use the `validate-plan-apply` component to automatically define an OpenTofu backend configuration. This creates a `__gitlab-opentofu-backend.tf` file.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@4.7.0
    inputs:
      opentofu_version: 1.12.1
      auto_define_backend: true
```

```hcl
terraform {
  backend "http" {}
}
```

--------------------------------

### HTTP Backend Block Creation

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-ctl-reference.md

When no backend is configured, the `runAutoDefineBackend` function creates this HTTP backend block in the `__gitlab-opentofu-backend.tf` file. This ensures a default HTTP backend is set up for the project.

```hcl
terraform {
  backend "http" {}
}
```

--------------------------------

### Include OpenTofu fmt Job Template

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Include the 'fmt' job component to check the formatting of your OpenTofu configuration files. Specify the OpenTofu version and root directory.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/fmt@<VERSION>
    inputs:
      opentofu_version: 1.6.1
      root_dir: tofu/
```

--------------------------------

### Generate OpenTofu Resource Graph

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Generates a dependency graph of the OpenTofu resources.

```bash
gitlab-tofu graph [additional-args]
```

--------------------------------

### Include Validate, Plan, Apply in Child Pipeline

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Include the validate, plan, and apply pipeline and trigger it within a child pipeline. Replace `<VERSION>` and `<OPENTOFU_VERSION>` with your desired values.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/validate-plan-apply@<VERSION>
    inputs:
      opentofu_version: <OPENTOFU_VERSION>
      trigger_in_child_pipeline: true
```

--------------------------------

### gitlab-tofu.sh Wrapper API

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/GENERATION_SUMMARY.txt

Documentation for the complete gitlab-tofu.sh wrapper API, including exported functions and supported commands.

```APIDOC
## Shell Functions (gitlab-tofu.sh)

### Description
Provides documentation for shell functions exported by the gitlab-tofu.sh script.

### Functions
- **is_tofu_at_least()**
- **define_http_backend()**
- **configure_variables_for_tofu()**
- **tofu_authenticate_private_registry()**
- **tofu_authenticate_oci()**
- **tofu_init()**
- **configure_encryption_for_tofu()**
- **fetch_mr_plan()**
- **detect_drift()**
- **import_custom_ca_certs()**

### Commands
- **apply, destroy, fmt, init, plan, plan-json**
- **validate, test, graph, delete-state**
- **fetch-mr-plan, detect-drift, import-custom-ca-certs**
- **Passthrough mode (--) for custom commands**
```

--------------------------------

### Verify Image Signature with Cosign

Source: https://gitlab.com/components/opentofu/-/blob/main/README.md

Use this command to verify the signature of a released OpenTofu component image using cosign. Ensure you replace `X.Y.Z` with the component version and `IMAGE_REF` with the full image reference.

```shell
VERSION=X.Y.Z # put a released components/opentofu version here
IMAGE_REF=... # put a released components/opentofu image reference here
cosign verify "${IMAGE_REF}" --certificate-identity="https://gitlab.com/components/opentofu//.gitlab-ci.yml@refs/tags/${VERSION}" --certificate-oidc-issuer="https://gitlab.com"
```

--------------------------------

### Validate OpenTofu Configuration

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Validates HCL syntax and configuration. This command skips backend initialization.

```bash
gitlab-tofu validate [additional-args]
```

--------------------------------

### Error Cases and Solutions

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/GENERATION_SUMMARY.txt

Documentation on common error cases encountered, including missing dependencies, encryption issues, and backend connectivity problems, with provided solutions.

```APIDOC
## Error Handling

### Description
Details common error cases and their corresponding solutions for the OpenTofu CI/CD component.

### Error Cases
- Missing dependencies
- Encryption configuration issues
- MR plan fetch failures
- Drift detection errors
- Backend connectivity problems
- And 10+ other specific error cases with solutions.
```

--------------------------------

### Run OpenTofu Tests

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/gitlab-tofu-script-reference.md

Runs OpenTofu test files. Supports optional filters and specified test directories.

```bash
gitlab-tofu test [additional-args]
```

--------------------------------

### Plan OpenTofu Infrastructure Changes

Source: https://gitlab.com/components/opentofu/-/blob/main/_autodocs/component-templates.md

Includes the OpenTofu plan component to generate an infrastructure plan. Specify the OpenTofu version, root directory, and optionally enable MR comments for plan reviews.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/opentofu/plan@4.7.0
    inputs:
      opentofu_version: 1.12.1
      root_dir: terraform/prod
      post_mr_plan_comment: true
```