Generate README

.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']

.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 |
+| ---- | ------- | ----------- |
+<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.

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:

Makefile

+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

README.md

+<!-- 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.