Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#208 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
52/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
github-actions
Área
ci-cd, devops, documentation, infrastructure

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
HCL
Estrellas
1
Forks
14
Merge medio
3 h 36 min
PR fusionados (30 d)
14

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de hackforla/devops-security

Todos los issues de hackforla/devops-security

Issues similares

Más issues de DevOps

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.