Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

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

Ouverte
  • Quelque chose ne va pas ?
#208 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
52/100
Type d'issue
Fonctionnalité
Clarté
Clairement spécifiée
Activité
Active
Stack technique
github-actions
Domaine
ci-cd, devops, documentation, infrastructure

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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
Langage dominant
TypeScript
Étoiles
1
Forks
14
Merge moyen
3 h 36 min
PR mergées (30 j)
14

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de hackforla/devops-security

Toutes les issues de hackforla/devops-security

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.