Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#208 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
52/100
Tipo de issue
Funcionalidade
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
github-actions
Domínio
ci-cd, devops, documentation, infrastructure

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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
Linguagem predominante
HCL
Estrelas
1
Forks
14
Merge médio
3h 36min
PRs com merge (30d)
14

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de hackforla/devops-security

Todas as issues de hackforla/devops-security

Issues semelhantes

Mais issues de DevOps

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.