Simplify CI by skipping terraform_docs - rely on local pre-commit

[lgallard]

Summary

Simplify the CI pipeline by skipping terraform_docs in GitHub Actions and relying on local pre-commit hooks for documentation generation.

Problem

The terraform_docs hook in CI causes frequent failures due to:

• Environment parity issues: macOS (local) vs Linux (CI) produce different outputs
• Version mismatches: Different terraform-docs versions between local and CI environments
• Unnecessary CI complexity: Installing and maintaining terraform-docs in CI adds overhead
• Blocking releases: Documentation generation differences block merges and releases

Proposed Solution

Implement the same approach successfully deployed in terraform-aws-ecrpublic:

CI Workflow Changes

1. Add SKIP: terraform_docs environment variable to pre-commit step
2. Remove terraform-docs installation from CI
3. Remove .md files from paths filter (docs changes don't need CI validation)
4. Update cache key to bust stale caches

Strategy

Layer	Checks
CI	terraform_fmt, terraform_validate, tflint, file formatting
Local	Full pre-commit including terraform_docs
AI Review	Documentation accuracy and quality gate

Benefits

• Faster CI: No terraform-docs installation or execution
• Fewer false failures: Eliminates environment parity issues
• Focus on shipping: Developers can focus on features and fixes
• Maintained quality: Local pre-commit ensures docs are updated before commit

Implementation

# In pre-commit workflow
- name: Run pre-commit checks
  env:
    SKIP: terraform_docs
  run: |
    pre-commit run --all-files

Reference

• Implementation PR: lgallard/terraform-aws-ecrpublic@5e1080a

[lgallard]

@claude address this issue

[claude]

Claude finished @lgallard's task —— View job • Create PR ➔

---

I've successfully implemented the CI simplification changes to skip terraform_docs in GitHub Actions. However, I encountered a GitHub App permission limitation when trying to push the workflow changes.

Todo List

• Analyze current GitHub Actions workflow files
• Identify terraform_docs installation and usage
• Add SKIP environment variable for terraform_docs
• Remove terraform-docs installation steps
• Update file paths filter to exclude .md files
• Update cache key configuration
• Commit changes locally
• Attempt to push changes (Permission denied)

Changes Made ✅

Simplified CI Configuration:

• ✅ Added SKIP: terraform_docs environment variable to both pre-commit steps
• ✅ Removed terraform-docs installation step entirely
• ✅ Removed .md files from paths filter (docs changes won't trigger CI)
• ✅ Updated cache key from v1 to v2 to bust stale caches
• ✅ Removed terraform-docs from cache paths
• ✅ Updated step summary to show terraform_docs is skipped in CI but runs locally

Permission Issue ⚠️

The GitHub App doesn't have workflows permission to modify .github/workflows/ files. The changes are ready and committed locally but need to be pushed manually.

Next Steps

To complete this implementation, you'll need to:

1. Pull the committed changes locally:

   git fetch origin claude/issue-51-20251228-0107
   git checkout claude/issue-51-20251228-0107

2. Push the changes (you have the necessary permissions):

   git push origin claude/issue-51-20251228-0107

3. Create the PR using the link below

The implementation follows the exact pattern from your terraform-aws-ecrpublic repo and will provide the same benefits: faster CI, fewer false failures, and maintained quality through local pre-commit hooks.

--- | Branch: claude/issue-51-20251228-0107