README.md

<!-- This document is generated by `make docs` from `.gitlab/README.md` -->

# OpenTofu CI/CD component

> 🚨 🚧 **NOTE** 🚧 🚨 
> 
> This component is **work in progress**, where inputs, template names and the entire interface in general may 
> change at any time until version 1.0.0 is reached. From where on this CI/CD component will be versioned using [semver 2.0](https://semver.org/).
> The progress of implementing such a version can be tracked in https://gitlab.com/groups/gitlab-org/-/epics/12401.
>
> The `src/gitlab-tofu.sh` script is still merely a copy from [`gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images).
> Therefore, lots of things in this script and in the templates are still Terraform-related and haven't
> been changed to their OpenTofu equivalents.

This project is home to the **OpenTofu CI/CD component** and it's related assets, 
like the `gitlab-tofu` wrapper script and OCI images containing that script
together with an OpenTofu version.

Read more:

- [CI/CD components](https://docs.gitlab.com/ee/ci/components)
- [Development guide for GitLab CI/CD components](https://docs.gitlab.com/ee/development/cicd/components)
- [CI/CD Catalog](https://docs.gitlab.com/ee/ci/components/index.html#cicd-catalog)

## Usage

```yaml
include:
  - component: gitlab.com/components/opentofu/full-pipeline@<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>
      opentofu_version: <OPENTOFU_VERSION>

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

A concrete example may look like this:

```yaml
# Using `latest`
include:
  - component: gitlab.com/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
      opentofu_version: 1.6.0

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

---

# ... or using `0.0.0-alpha1`:
include:
  - component: gitlab.com/components/opentofu/full-pipeline@0.0.0-alpha1
    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: 0.0.0-alpha1
      opentofu_version: 1.6.0

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

### Inputs

| Name | Default | Description |
| ---- | ------- | ----------- |
| `stage_validate` | `validate` | Defines the validate stage. This stage includes the `fmt` and `validate` jobs. |
| `stage_build` | `build` | Defines the build stage. This stage includes the `plan` job. |
| `stage_deploy` | `deploy` | Defines the deploy stage. This stage includes the `apply` job. |
| `stage_cleanup` | `cleanup` | Defines the cleanup stage. This stage includes the `destroy` and `delete-state` jobs. |
| `version` | `latest` | Version of this component. Has to be the same as the one in the component include entry. |
| `opentofu_version` | `1.6.0` | OpenTofu version that should be used. |
| `gitlab_opentofu_image` | `$CI_REGISTRY/components/opentofu/gitlab-opentofu:$[[ inputs.version ]]-opentofu$[[ inputs.opentofu_version ]]` | Tag of the gitlab-opentofu image. |
| `root_dir` | `${CI_PROJECT_DIR}` | Root directory for the OpenTofu project. |
| `state_name` | `default` | Remote OpenTofu state name. |
| `auto_apply` | `false` | Whether the apply job is manual or automatically run. |
| `auto_destroy` | `false` | Whether the destroy job is manual or automatically run. |

## Releases & Versioning

This project currently releases tagged commits. 
An overview of releases can be found on the [Releases page](https://gitlab.com/components/opentofu/-/releases).

Each release is accessible in the [CI/CD Catalog](https://gitlab.com/explore/catalog).

### Component Versions

The component release versions follow [Semantic Versioning 2.0.0](https://semver.org/).

### Image Versions

This project releases multiple OCI image variants that can be used with the component.
The intention is that the images used in a component have the same version and or not mixed.
Due to the limitations described in https://gitlab.com/gitlab-org/gitlab/-/issues/438275 
it's currently required to provide the component version in the `component` include field
and as the `version` input. Check out the [Usage](#Usage) section for examples.

Each component release deploys the following images:

- `registry.gitlab.com/components/opentofu/gitlab-opentofu:<VERSION>-opentofu<OPENTOFU_VERSION>`
- `registry.gitlab.com/components/opentofu/gitlab-opentofu:<VERSION>-opentofu`
  - Includes the latest stable OpenTofu version at the time of releasing the component
- `registry.gitlab.com/components/opentofu/gitlab-opentofu:<VERSION>`
  - Includes the latest stable OpenTofu version at the time of releasing the component

In the above examples `<VERSION>` references the component version and `<OPENTOFU_VERSION>` 
an OpenTofu release, from [here](https://github.com/opentofu/opentofu/releases).

*Note: unfortunately, these image versions are not SemVer compatible,
because `-` indicates a prerelease (which they are not in this case).
However, we cannot use the alternative `+` which would indicate build metadata
as we'd like.
See https://github.com/distribution/distribution/issues/1201*

## Contributing

See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.