Merge branch 'ci-variables-forward' into 'main'

Document auto-forwarding of CI/CD variables

See merge request components/opentofu!132

.gitlab/README.md.template

@@ -220,6 +220,34 @@ beautifully renders the inputs for each templates - check it out!
 Have a look at the [`src/gitlab-tofu.sh`](src/gitlab-tofu.sh) script and how the `TF_`-prefixed
 variables are being used. You may set them according to your needs.
 
+### Auto-forwarded predefined CI variables
+
+The `gitlab-tofu` script auto-forwards some "popular"
+[predefined CI/CD variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
+as OpenTofu variables.
+
+The forwarded variables are:
+
+- `CI_JOB_ID`
+- `CI_COMMIT_SHA`
+- `CI_JOB_STAGE`
+- `CI_PROJECT_ID`
+- `CI_PROJECT_NAME`
+- `CI_PROJECT_NAMESPACE`
+- `CI_PROJECT_PATH`
+- `CI_PROJECT_URL`
+
+To use them in your OpenTofu configuration you can define a string variable with the same name
+but in *lower snake_case*. For example the `CI_PROJECT_NAME` CI/CD variable can be accessed in
+the OpenTofu configuration like this:
+
+```hcl
+variable "ci_project_name" {
+  type        = string
+  description = "The name of the directory for the project."
+}
+```
+
 ### Install additional tools
 
 The `gitlab-opentofu` container image deliberately comes with minimal tooling

README.md

@@ -237,6 +237,34 @@ The following OpenTofu versions are available with this component via the `opent
 Have a look at the [`src/gitlab-tofu.sh`](src/gitlab-tofu.sh) script and how the `TF_`-prefixed
 variables are being used. You may set them according to your needs.
 
+### Auto-forwarded predefined CI variables
+
+The `gitlab-tofu` script auto-forwards some "popular"
+[predefined CI/CD variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
+as OpenTofu variables.
+
+The forwarded variables are:
+
+- `CI_JOB_ID`
+- `CI_COMMIT_SHA`
+- `CI_JOB_STAGE`
+- `CI_PROJECT_ID`
+- `CI_PROJECT_NAME`
+- `CI_PROJECT_NAMESPACE`
+- `CI_PROJECT_PATH`
+- `CI_PROJECT_URL`
+
+To use them in your OpenTofu configuration you can define a string variable with the same name
+but in *lower snake_case*. For example the `CI_PROJECT_NAME` CI/CD variable can be accessed in
+the OpenTofu configuration like this:
+
+```hcl
+variable "ci_project_name" {
+  type        = string
+  description = "The name of the directory for the project."
+}
+```
+
 ### Install additional tools
 
 The `gitlab-opentofu` container image deliberately comes with minimal tooling

src/gitlab-tofu.sh

@@ -106,7 +106,8 @@ export TF_HTTP_PASSWORD="${TF_HTTP_PASSWORD:-${TF_PASSWORD}}"
 export TF_HTTP_RETRY_WAIT_MIN="${TF_HTTP_RETRY_WAIT_MIN:-5}"
 
 # Expose Gitlab specific variables to terraform since no -tf-var is available
-# Usable in the .tf file as variable "CI_JOB_ID" { type = string } etc
+# The following variables are deprecated because they do not conform to
+# HCL naming best practices. Use the lower snake_case variants below instead.
 export TF_VAR_CI_JOB_ID="${TF_VAR_CI_JOB_ID:-${CI_JOB_ID}}"
 export TF_VAR_CI_COMMIT_SHA="${TF_VAR_CI_COMMIT_SHA:-${CI_COMMIT_SHA}}"
 export TF_VAR_CI_JOB_STAGE="${TF_VAR_CI_JOB_STAGE:-${CI_JOB_STAGE}}"
@@ -116,6 +117,16 @@ export TF_VAR_CI_PROJECT_NAMESPACE="${TF_VAR_CI_PROJECT_NAMESPACE:-${CI_PROJECT_
 export TF_VAR_CI_PROJECT_PATH="${TF_VAR_CI_PROJECT_PATH:-${CI_PROJECT_PATH}}"
 export TF_VAR_CI_PROJECT_URL="${TF_VAR_CI_PROJECT_URL:-${CI_PROJECT_URL}}"
 
+
+export TF_VAR_ci_job_id="${TF_VAR_ci_job_id:-${CI_JOB_ID}}"
+export TF_VAR_ci_commit_sha="${TF_VAR_ci_commit_sha:-${CI_COMMIT_SHA}}"
+export TF_VAR_ci_job_stage="${TF_VAR_ci_job_stage:-${CI_JOB_STAGE}}"
+export TF_VAR_ci_project_id="${TF_VAR_ci_project_id:-${CI_PROJECT_ID}}"
+export TF_VAR_ci_project_name="${TF_VAR_ci_project_name:-${CI_PROJECT_NAME}}"
+export TF_VAR_ci_project_namespace="${TF_VAR_ci_project_namespace:-${CI_PROJECT_NAMESPACE}}"
+export TF_VAR_ci_project_path="${TF_VAR_ci_project_path:-${CI_PROJECT_PATH}}"
+export TF_VAR_ci_project_url="${TF_VAR_ci_project_url:-${CI_PROJECT_URL}}"
+
 # Use terraform automation mode (will remove some verbose unneeded messages)
 export TF_IN_AUTOMATION=true