modules README.md is always overwritten

[rochana-atapattu]

tfaction version

1.2.1

Overview

when generating the terraform docs in module test READMe.md is always overwritten

How to reproduce

tfaction-root.yaml

---
plan_workflow_name: pull_request_target # Mandatory
label_prefixes:
  tfmigrate: "migrate:"
# skip_create_pr: true

# drift_detection:
#   # issue_repo_owner:
#   # issue_repo_name:
#   minimum_detection_interval: 5 # 5 days. By default 7 days.
#   num_of_issues: 3 # 3 working directories are checked per workflow run. By default 1 working directory is checked.

tflint:
  enabled: true
tfsec:
  enabled: false
trivy:
  enabled: true

# scaffold_working_directory:
#   skip_adding_aqua_packages: true

aqua:
  update_checksum:
    # Update aqua-checksums.json in `setup` action
    enabled: true # default is false
    skip_push: false # default is false
    prune: true # default is false

target_groups:
  - working_directory: configurations/state-buckets-state
    target: configurations/state-buckets-state
    gcs_bucket_name_tfmigrate_history: '<S3 Bucket Name for tfmigrate history files>' # CHANGEME
    template_dir: templates/gcp

  - working_directory: gcp/
    target: gcp/
    gcs_bucket_name_tfmigrate_history: '<GCS Bucket Name for tfmigrate history files>'
    template_dir: templates/gcp
    # terraform_plan_config:
    #   gcp_service_account: terraform-plan@example.iam.gserviceaccount.com
    #   gcp_workload_identity_provider: projects/000000000000/locations/global/workloadIdentityPools/github/providers/tfaction
    # tfmigrate_plan_config:
    #   gcp_service_account: terraform-plan@example.iam.gserviceaccount.com
    #   gcp_workload_identity_provider: projects/000000000000/locations/global/workloadIdentityPools/github/providers/tfaction
    # terraform_apply_config:
    #   gcp_service_account: terraform-apply@example.iam.gserviceaccount.com
    #   gcp_workload_identity_provider: projects/000000000000/locations/global/workloadIdentityPools/github/providers/tfaction
    # tfmigrate_apply_config:
    #   gcp_service_account: terraform-apply@example.iam.gserviceaccount.com
    #   gcp_workload_identit

tfaction.yaml

GitHub Actions Workflow

Other related code such as local Registry

GitHub Actions' log

Run ! test -f .terraform.lock.hcl || rm .terraform.lock.hcl
Run set -euo pipefail
time="2024-03-13T08:25:35Z" level=info msg="download and unarchive the package" aqua_version=2.24.0 env=linux/amd64 exe_name=terraform-docs package_name=terraform-docs/terraform-docs package_version=v0.16.0 program=aqua registry=standard
Error: Please generate Module's README.md with terraform-docs.
Error: Process completed with exit code 1.

Expected behaviour

inject terraform docs to README.md without overwriting the content

Actual behaviour

overwrites entire README.md

Important Factoids

No response

Note

we can do the following to inject docs anywhere in the README.md the user wants. this will give the user a choice where to add docs.
.terraform-docs.yml

formatter: markdown
header-from: docs/header.md
footer-from: docs/footer.md
output:
  file: README.md
  mode: inject

README.md

<!-- BEGIN_TF_DOCS -->
    {{ .Content }}
<!-- END_TF_DOCS -->
## Requirements

Before this module can be used on a project, you must ensure that the following pre-requisites are fulfilled:

1. Required APIs are activated

    ```
    "iam.googleapis.com",
    "cloudresourcemanager.googleapis.com",
    "iamcredentials.googleapis.com",
    "sts.googleapis.com",
    ```

1. Service Account used to deploy this module has the following roles

    ```
    roles/iam.workloadIdentityPoolAdmin
    roles/iam.serviceAccountAdmin

and remove the redirection to the README.md from the step

[rochana-atapattu]

also i think you need to add pull_request_targe here

[suzuki-shunsuke]

Thank you for your feedback.
I didn't know the output config.
But I think you can use header-from and footer-from instead of inject mode.

https://github.com/suzuki-shunsuke/tfaction-example/blob/main/templates/module-hello/.terraform-docs.yml

[suzuki-shunsuke]

also i think you need to add pull_request_targe here

Yeah, that's right. Thank you for pointing it out.

[rochana-atapattu]

Thank you for your feedback. I didn't know the output config. But I think you can use header-from and footer-from instead of inject mode.

https://github.com/suzuki-shunsuke/tfaction-example/blob/main/templates/module-hello/.terraform-docs.yml

yes but we can use headers and footers to add more general information to the README which will give more flexibilty to the user
we can also do

github-comment exec \
    -config "${GITHUB_ACTION_PATH}/github-comment.yaml" \
    -var "tfaction_target:${TFACTION_TARGET}" \
   -- terraform-docs --output-file README.md .

which will give us the same results without overwritting the README
--output-file README.md override the output.file option in .terraform-docs.yml
and default output mode is inject

[suzuki-shunsuke]

also i think you need to add pull_request_targe here

• fix(test-module): support pull_request_target #1583

[suzuki-shunsuke]

📝 --output-file was added at terraform-docs v0.12.0.

https://github.com/terraform-docs/terraform-docs/releases/tag/v0.12.0

The release date is Mar 23, 2021, so there is no problem.

[suzuki-shunsuke]

Now test-module runs terraform-docs as the following.

tfaction/test-module/action.yaml

Line 63 in 8e6060b

-- terraform-docs . > README.md

terraform-docs . > README.md

If output is set as the following, README.md becomes empty.

output:
  file: README.md
  mode: inject

$ terraform-docs . > README.md
$ cat README.md 
Error: file content is empty

On the other hand, terraform-docs --output-file README.md . works well.

$ terraform-docs --output-file README.md .

But if the comment <!-- BEGIN_TF_DOCS --> isn't set, the command fails.

$ terraform-docs --output-file README.md .
Error: begin comment is missing

So this is a breaking change.

We can check if the comment exists, and if they don't exist we can run terraform-docs . > README.md without --output-file option.
This keeps the compatibility, but I'm not sure if it's good.

[suzuki-shunsuke]

1. Check .terraform-docs.yml if output.file is set
2. If output.file is set, tfaction runs terraform-docs .
3. Otherwise tfaction runs terraform-docs . > README (Redirect the stdout to README.md)

[suzuki-shunsuke]

• fix(test-module): support terraform-docs's output.file #1584

[suzuki-shunsuke]

v1.2.3 is out 🎉
https://github.com/suzuki-shunsuke/tfaction/releases/tag/v1.2.3