diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 1f821b10dd65e48ddedae5f87d6c2101776083cf..bdd5bbdb15782391e4f56fa192bd0ad84a91677b 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -64,6 +64,16 @@ gitlab-opentofu-image:build:
--push
.
+check-readme:
+ stage: test
+ needs: []
+ image: alpine:latest
+ before_script:
+ - apk add coreutils make git
+ script:
+ - make docs
+ - git diff --exit-code
+
container_scanning:
extends: .opentofu-versions
needs: ['gitlab-opentofu-image:build']
diff --git a/.gitlab/README.md b/.gitlab/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..ac12ae0e9fb2791dae1a91c611202edb02335b0f
--- /dev/null
+++ b/.gitlab/README.md
@@ -0,0 +1,112 @@
+# 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 |
+| ---- | ------- | ----------- |
+<INPUTS>
+
+## 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.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5d86df350132469864d5b6469d3913d712bb1ec7..45524e8fc7016c32d35f24c354d8d4860a999f37 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,11 @@
Please read about CI/CD components and best practices at: https://docs.gitlab.com/ee/ci/components
+## README
+
+The [`README.md`](README.md) file is generated using `make docs` (see [`Makefile`](Makefile))
+from [`.gitlab/README.md`](.gitlab/README.md).
+
## Upgrade OpenTofu versions
When adding new OpenTofu versions the following places need to be updated:
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..4c9c0c8dae450e093a00d0becc0babcb12fda90e
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,8 @@
+docs:
+ csplit -sf readme -n 1 .gitlab/README.md '/<INPUTS>/'
+ yq '.spec.inputs | .[] | "| `" + key + "` | `" + .default + "` | " + .description + " |"' templates/full-pipeline.yml > readme_inputs.md
+ echo '<!-- This document is generated by `make docs` from `.gitlab/README.md` -->\n' > README.md
+ cat readme0 >> README.md
+ cat readme_inputs.md >> README.md
+ tail -n+2 readme1 >> README.md
+ rm -f readme0 readme1 readme_inputs.md
diff --git a/README.md b/README.md
index d095123e3a6e2cf4493f591e2cea5bc54157eea7..842cdfa95c896664eceba84aa76d2dd1bdf5f645 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+<!-- This document is generated by `make docs` from `.gitlab/README.md` -->
+
# OpenTofu CI/CD component
> 🚨 🚧 **NOTE** 🚧 🚨
@@ -65,6 +67,23 @@ include:
stages: [validate, test, build, deploy, cleanup]
```
+### Inputs
+
+| Name | Default | Description |
+| ---- | ------- | ----------- |
+| `stage_validate` | `validate` | Defines the validate stage |
+| `stage_test` | `test` | Defines the test stage |
+| `stage_build` | `build` | Defines the build stage |
+| `stage_deploy` | `deploy` | Defines the deploy stage |
+| `stage_cleanup` | `cleanup` | Defines the cleanup stage |
+| `version` | `latest` | Version of this component |
+| `opentofu_version` | `1.6.0` | Released version of upstream OpenTofu |
+| `gitlab_opentofu_image` | `$CI_REGISTRY/components/opentofu/gitlab-opentofu:$[[ inputs.version ]]-opentofu$[[ inputs.opentofu_version ]]` | Image name of the gitlab-opentofu image |
+| `root_dir` | `${CI_PROJECT_DIR}` | Root directory for the OpenTofu project |
+| `state_name` | `default` | 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.