Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Auto-generate the Terraform module READMEs in CI, matching incubator

Đang mở
  • Có gì không ổn?
#208 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
52/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
github-actions
Lĩnh vực
ci-cd, devops, documentation, infrastructure

Hướng nghiên cứu

Start by comparing .github/workflows/terraform-plan.yaml with incubator’s workflow, then inspect the listed Terraform README and .terraform.docs.yml files. Search CONTRIBUTING.md and .github/ISSUE_TEMPLATE/pre-work-template-devops-security.md for the documented manual commands, and verify the repository squash-merge settings with the provided gh commands. Done means the workflow, documentation, cleanup, merge behavior, and later PR validation match the issue’s checks.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

complexity: medium feature: maintenance role: DevOps Engineer size: 3pt
Overview

We need devops-security to regenerate its Terraform module READMEs automatically on every pull request, the same way incubator already does, because today they are only updated when someone remembers to run terraform-docs by hand.

Action Items
  • Before anything merges, have a repo admin change devops-security's squash-merge message source. devops-security currently squashes with COMMIT_OR_PR_TITLE / COMMIT_MESSAGES, which copies every branch commit message into the squash commit on main. The docs job's commit message ends in [skip ci], and GitHub skips every workflow for a push whose commit message contains that string anywhere — so the merge would silently never run Apply Terraform changes on merge, with no failed run to notice. This exact failure happened on incubator (hackforla/incubator#179) and was fixed there by switching to the PR title and body. Run (needs admin on the repo):
    gh api -X PATCH repos/hackforla/devops-security -f squash_merge_commit_title='PR_TITLE' -f squash_merge_commit_message='PR_BODY'
    and confirm with gh api repos/hackforla/devops-security -q '[.squash_merge_commit_title,.squash_merge_commit_message]', which should print ["PR_TITLE","PR_BODY"].
  • Add a terraform-docs job to .github/workflows/terraform-plan.yaml, copied verbatim from the terraform-docs job in incubator's .github/workflows/terraform-plan.yaml — same action and version (terraform-docs/[email protected]), same find-dir: "terraform", output-file: README.md, output-method: inject, git-push: "true", same commit message including [skip ci] and its comment, same job-level permissions (contents: write, pull-requests: write), and the same actions/checkout step with ref: ${{ github.event.pull_request.head.ref }}. Keep the checkout version identical to incubator's too; bumping it is hackforla/devops#183's job for both repos.
  • Delete the five hand-run config files: terraform/.terraform.docs.yml and terraform/modules/{aws-groups,aws-policies,aws-roles,aws-users}/.terraform.docs.yml. Why: incubator's job runs with no config, so these would be ignored anyway (terraform-docs only auto-discovers a file named exactly .terraform-docs.yml, with a hyphen — these use a dot). Leaving them would tell contributors a config is in effect when it is not.
  • Move each README's hand-written prose above its <!-- BEGIN_TF_DOCS --> marker. Why: those configs used mode: replace with a custom content: template, so every README today starts with the marker and the hand-written parts — the # Overview / # Groups / # Users etc. headings, the one-line module descriptions, and the root README's "Directory Structure" list — sit inside the generated block. Inject mode overwrites everything between the markers, so without this step the first run deletes them. Text above the marker survives regeneration; this is how incubator's terraform/modules/legacy/README.md keeps its prose. Drop the "To automatically update this documentation, install terraform-docs…" paragraph rather than moving it — it will no longer be true.
  • Update CONTRIBUTING.md so it no longer tells contributors to run terraform-docs -c .terraform.docs.yml . by hand: the "Installing Terraform docs" section (around line 185) and the command around line 311. Say instead that CI regenerates the READMEs and pushes a commit to the PR branch, so contributors should git pull before pushing again.
  • Update .github/ISSUE_TEMPLATE/pre-work-template-devops-security.md to match: the "Install Terraform Docs locally" item (around line 42) and the terraform-docs -c .terraform.docs.yml . item (around line 84).
  • Open the PR. The new job will run on it and push a terraform-docs: automated updates… commit back to your branch — that commit is the job working, not something to revert. Read its diff: it should change only content between the markers. Expect terraform/modules/aws-gha-oidc-providers/, which has no README today, to get a new one.
  • After the PR merges, confirm the main squash commit message does not contain [skip ci] and that Apply Terraform changes on merge ran for it (gh run list -R hackforla/devops-security -w "Apply Terraform changes on merge" -L 3). If no run exists for the merge commit, the first action item did not take effect.
  • After the PR merges, open any later PR that touches a .tf file (or a throwaway one) and confirm the Generate Terraform Docs job runs and either pushes a docs commit or finishes with nothing to change.
Resources/Instructions
Ngôn ngữ chính
TypeScript
Star
1
Fork
14
Merge trung bình
3 giờ 36 phút
Pull request đã merge (30 ngày)
14

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của hackforla/devops-security

Tất cả issue của hackforla/devops-security

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.