Generate documentation for environment variables

.gitlab/README.md.template

@@ -238,13 +238,6 @@ beautifully renders the inputs for each templates - check it out!
 
 <RENDER>
 
-### Variables
-
-(🚧 *This section is work in progress*)
-
-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"

.gitlab/scripts/generate-readme.sh

@@ -3,6 +3,7 @@
 set -o errexit
 
 script_dir=$(dirname "$0")
+project_root_dir="$(dirname "$0")/../.."
 
 csplit -sf readme -n 1 "${script_dir}/../README.md.template" '/<RENDER>/'
 
@@ -17,6 +18,13 @@ csplit -sf readme -n 1 "${script_dir}/../README.md.template" '/<RENDER>/'
   echo 'The following OpenTofu versions are available with this component via the `opentofu_version` input:'
   echo
   yq '.".data".supported_versions | .[] | "- [`" + . + "`](https://github.com/opentofu/opentofu/releases/tag/v" + . + ")"' "${script_dir}/../../opentofu_versions.yaml"
+  echo
+  echo '### Environment Variables'
+  echo
+  echo 'The following environment variables are respected by the `gitlab-tofu` script:'
+  echo
+  awk '/^# %%%%/{i++} i==1 && NR>1' "${project_root_dir}/src/gitlab-tofu.sh" | tail -n+3 | cut -d'#' -f2- | cut -d' ' -f2-
+  echo
   tail -n+2 readme1
 } > "${script_dir}/../../README.md"
 

README.md

@@ -253,12 +253,65 @@ The following OpenTofu versions are available with this component via the `opent
 - [`1.7.3`](https://github.com/opentofu/opentofu/releases/tag/v1.7.3)
 - [`1.6.2`](https://github.com/opentofu/opentofu/releases/tag/v1.6.2)
 
-### Variables
+### Environment Variables
+
+The following environment variables are respected by the `gitlab-tofu` script:
+
+#### Respected Environment Variables
+
+- `GITLAB_TOFU_DEBUG`: if set to true will enable xtrace.
+- `GITLAB_TOFU_SOURCE`: forces this script in source-mode. Required when source auto-detection fails.
+- `GITLAB_TOFU_APPLY_NO_PLAN`: if set to true, the apply command does not use a plan cache file.
+- `GITLAB_TOFU_PLAN_NAME`: the name of the plan cache and json files. Defaults to `plan`.
+- `GITLAB_TOFU_PLAN_CACHE`: if set to the full path of the plan cache file. Defaults to `<root>/$GITLAB_TOFU_PLAN_NAME.cache`
+- `GITLAB_TOFU_PLAN_JSON`: if set to the full path of the plan json file. Defaults to `<root>/$GITLAB_TOFU_PLAN_NAME.json`
+- `GITLAB_TOFU_IMPLICIT_INIT`: if set to true will perform an implicit `tofu init` before any command that require it. Defaults to `true`.
+- `GITLAB_TOFU_IGNORE_INIT_ERRORS`: if set to true will ignore errors in the `tofu init` command.
+- `GITLAB_TOFU_INIT_NO_RECONFIGURE`: if set to true will not pass `-reconfigure` to the `tofu init` command. Defaults to `false`.
+- `GITLAB_TOFU_STATE_NAME`: the name of the GitLab-managed Terraform state backend endpoint.
+- `GITLAB_TOFU_STATE_ADDRESS`: the address of the GitLab-managed Terraform state backend. Defaults to `$CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/$GITLAB_TOFU_STATE_NAME`.
+- `GITLAB_TOFU_USE_DETAILED_EXITCODE`: if set to true, `-detailed-exitcode` is supplied to `tofu plan`. Defaults to `false`.
+- `GITLAB_TOFU_PLAN_WITH_JSON`: if set to true, will directly generate a JSON plan file when running `gitlab-tofu plan`. Defaults to `false`.
+- `GITLAB_TOFU_VAR_FILE`: if set to a path it will pass `-var-file` to all `tofu` commands that support it.
+
+#### Respected OpenTofu Environment Variables
+
+> these are variables that are
+> respected if set and avoid using
+> the gitlab-tofu values for them.
+
+- `TF_HTTP_USERNAME`: username for the HTTP backend. Defaults to `gitlab-ci-token`.
+- `TF_HTTP_PASSWORD`: password for the HTTP backend. Defaults to `$CI_JOB_TOKEN`.
+- `TF_HTTP_ADDRESS`: address for the HTTP backend. Defaults to `$CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/<urlencode($GITLAB_TOFU_STATE_NAME)>`.
+- `TF_HTTP_LOCK_ADDRESS`: lock address for the HTTP backend. Defaults to `$TF_HTTP_ADDRESS/lock`.
+- `TF_HTTP_LOCK_METHOD`: lock method for the HTTP backend. Defaults to `POST`.
+- `TF_HTTP_UNLOCK_ADDRESS`: unlock address for the HTTP backend. Defaults to `lock`.
+- `TF_HTTP_UNLOCK_METHOD`: unlock address for the HTTP backend. Defaults to `unlock`.
+- `TF_HTTP_RETRY_WAIT_MIN`: retry minimum waiting time in seconds. Defaults to `5`.
+- `TF_CLI_CONFIG_FILE`: config file path. Defaults to `$HOME/.terraformrc` if it exists.
+
+#### Respected GitLab CI/CD Variables
+
+> these are variables exposed by
+> GitLab CI/CD and respected by
+> the gitlab-tofu script for
+> certain configurations.
+
+- `CI_JOB_TOKEN`:
+  - used as default value for `TF_HTTP_PASSWORD`.
+  - used as value for `TF_TOKEN_<host>` variable.
+- `CI_PROJECT_DIR`:
+  - used as default value for root directory.
+- `CI_PROJECT_ID`:
+  - used as default value in constructing the `GITLAB_TOFU_STATE_ADDRESS`.
+- `CI_API_V4_URL`:
+  - used as default value in constructing the `GITLAB_TOFU_STATE_ADDRESS`.
+- `CI_SERVER_HOST`:
+  - used to construct for `TF_TOKEN_<host>` variable.
+- `CI_SERVER_PROTOCOL`:
+  - used to construct for `TF_TOKEN_<host>` variable.
 
-(🚧 *This section is work in progress*)
 
-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
 

src/gitlab-tofu.sh

@@ -9,6 +9,8 @@
 # Detailed information about it is in the README:
 # https://gitlab.com/components/opentofu
 #
+# %%%%
+#
 # #### Respected Environment Variables
 #
 # - `GITLAB_TOFU_DEBUG`: if set to true will enable xtrace.
@@ -62,6 +64,8 @@
 #   - used to construct for `TF_TOKEN_<host>` variable.
 # - `CI_SERVER_PROTOCOL`:
 #   - used to construct for `TF_TOKEN_<host>` variable.
+#
+# %%%%
 
 # set some shell options
 set -o errexit