|
| 1 | +# Terraform Module Releaser |
| 2 | + |
| 3 | +A GitHub Action written in TypeScript that automates versioning, releases, and documentation for Terraform modules in |
| 4 | +GitHub monorepos. The action creates module-specific Git tags, GitHub releases, pull request comments, and generates |
| 5 | +comprehensive wiki documentation. |
| 6 | + |
| 7 | +**Always reference these instructions first and fallback to search or Bash commands only when you encounter unexpected |
| 8 | +information that does not match the info here.** |
| 9 | + |
| 10 | +## Working Effectively |
| 11 | + |
| 12 | +### Bootstrap and Build the Repository |
| 13 | + |
| 14 | +- Install Node.js dependencies: `npm ci --no-fund` |
| 15 | +- Run TypeScript type checking: `npm run typecheck` |
| 16 | +- Lint and format code: `npm run check` |
| 17 | + |
| 18 | +### Testing |
| 19 | + |
| 20 | +- Run full test suite: `npm run test` (requires GITHUB_TOKEN for some tests) |
| 21 | +- Run tests in watch mode during development: `npm run test:watch` |
| 22 | + |
| 23 | +## Validation |
| 24 | + |
| 25 | +### Required Environment Variables for Full Testing |
| 26 | + |
| 27 | +- `GITHUB_TOKEN` - Required for tests that interact with GitHub API. Without this, some tests will be skipped with clear |
| 28 | + error messages. |
| 29 | + |
| 30 | +### External Dependencies |
| 31 | + |
| 32 | +External dependencies like terraform-docs are automatically installed and handled during `npm run test` - no manual |
| 33 | +prerequisite downloads needed. Note that firewall restrictions may block some operations in certain environments. |
| 34 | + |
| 35 | +### Manual Validation Scenarios |
| 36 | + |
| 37 | +- **Always validate TypeScript compilation**: Run `npm run typecheck` to catch type errors. |
| 38 | +- **Always test functionality**: Run `npm run test` to verify operation and functionality. |
| 39 | +- **Validate linting compliance**: Run `npm run check` to ensure code meets style requirements. |
| 40 | + |
| 41 | +## Common Tasks |
| 42 | + |
| 43 | +### Build and Test Workflow |
| 44 | + |
| 45 | +- `npm ci --no-fund` -- Install dependencies |
| 46 | +- `npm run typecheck` -- Type checking |
| 47 | +- `npm run check` -- Lint/formatting code |
| 48 | +- `npm run test` -- Run full test suite |
| 49 | + |
| 50 | +### Development |
| 51 | + |
| 52 | +- Use `npm run test:watch` for continuous testing during development |
| 53 | +- Use `npm run check` to check linting without fixing |
| 54 | +- Always run `npm run check:fix` before committing or the CI (.github/workflows/lint.yml) will fail |
| 55 | + |
| 56 | +### Working with the Action Locally |
| 57 | + |
| 58 | +- The action can be tested locally using the CI workflow configuration in `.github/workflows/ci.yml` |
| 59 | +- Test terraform modules are located in `tf-modules/` directory |
| 60 | +- Use GitHub Codespaces or Dev Containers for a consistent development environment (configuration in `.devcontainer/`) |
| 61 | + |
| 62 | +## Key Repository Structure |
| 63 | + |
| 64 | +```shell |
| 65 | +/home/runner/work/terraform-module-releaser/terraform-module-releaser/ |
| 66 | +├── .devcontainer/ # Dev container configuration |
| 67 | +├── .github/workflows/ # CI/CD workflows (ci.yml, test.yml, lint.yml) |
| 68 | +├── __mocks__/ # Test mocks |
| 69 | +├── __tests__/ # Test files (mirror src/ structure) |
| 70 | +├── action.yml # GitHub Action metadata and inputs |
| 71 | +├── dist/ # Compiled action bundle (generated) |
| 72 | +├── package.json # Dependencies and scripts |
| 73 | +├── scripts/ # Utility scripts (changelog.js, parse-modules-test.ts) |
| 74 | +├── src/ # TypeScript source code |
| 75 | +│ ├── index.ts # Action entry point |
| 76 | +│ ├── main.ts # Main action logic |
| 77 | +│ ├── config.ts # Configuration handling |
| 78 | +│ ├── context.ts # GitHub Actions context |
| 79 | +│ ├── parser.ts # Terraform module discovery |
| 80 | +│ ├── terraform-module.ts # Module representation |
| 81 | +│ ├── wiki.ts # Wiki generation |
| 82 | +│ ├── terraform-docs.ts # Terraform documentation |
| 83 | +│ ├── releases.ts # GitHub releases |
| 84 | +│ ├── tags.ts # Git tags |
| 85 | +│ ├── pull-request.ts # PR comments |
| 86 | +│ └── types/ # TypeScript type definitions |
| 87 | +├── tf-modules/ # Example Terraform modules for testing |
| 88 | +├── biome.json # Biome linter/formatter configuration |
| 89 | +├── tsconfig.json # TypeScript configuration |
| 90 | +└── vitest.config.ts # Test configuration |
| 91 | +``` |
| 92 | + |
| 93 | +## Linting and Formatting |
| 94 | + |
| 95 | +- Uses **Biome** (not Prettier or ESLint) for TypeScript linting and formatting |
| 96 | +- Configuration in `biome.json` |
| 97 | +- Super Linter runs in CI but defers TypeScript formatting to Biome |
| 98 | + |
| 99 | +## Testing Framework |
| 100 | + |
| 101 | +- Uses **Vitest** for testing with TypeScript support |
| 102 | +- Configuration in `vitest.config.ts` |
| 103 | +- Tests include both unit tests and integration tests with real GitHub API calls |
| 104 | +- Coverage reporting with V8 provider |
| 105 | +- Path aliases configured: `@/` points to `src/`, `@/tests/` to `__tests__/` |
| 106 | + |
| 107 | +## Known Limitations |
| 108 | + |
| 109 | +- Some tests require `GITHUB_TOKEN` environment variable - they will be skipped with clear messages if not provided |
| 110 | +- Some tests require internet access to download terraform-docs binary |
| 111 | +- The action is designed to run in GitHub Actions environment with appropriate permissions |
| 112 | + |
| 113 | +### Troubleshooting |
| 114 | + |
| 115 | +- If API tests fail with "GITHUB_TOKEN environment variable must be set": Provide a valid GitHub token or skip |
| 116 | + integration tests |
| 117 | +- If build fails: Ensure Node.js 22 is installed (specified in `.node-version`) |
| 118 | +- If linting fails: Run `npm run check:fix` to autofix formatting issues |
0 commit comments