GitHub Action for formatting HCL files

GitHub Action automatically formatting all HCL and TF files (.hcl, .tf, .tfvars).

📦 Available on

• Docker Hub: devopsinfra/action-format-hcl:latest
• GitHub Packages: ghcr.io/devops-infra/action-format-hcl:latest

✨ Features

• Container is a stripped down image of my other creation - devopsinfra/docker-terragrunt - framework for managing Infrastructure-as-a-Code.
• Main use will be everywhere where Terraform or Terragrunt is used.
• Using combination of my wrapper for cytopia's docker-terragrunt-fmt.

🔗 Related Actions

Useful in combination with my other action devops-infra/action-commit-push.

📊 Badges

🏷️ Version Tags: vX, vX.Y, vX.Y.Z

This action supports three tag levels for flexible versioning:

• vX: latest patch of the major version (e.g., v1).
• vX.Y: latest patch of the minor version (e.g., v1.2).
• vX.Y.Z: fixed to a specific release (e.g., v1.2.3).

📖 API Reference

    - name: Run the Action
      uses: devops-infra/action-format-hcl@v1.1.2
      with:
        list: false
        write: true
        ignore: config
        diff: false
        check: false
        recursive: true
        dir: modules

🔧 Input Parameters

Input Variable	Required	Default	Description
list	No	false	List files containing formatting inconsistencies.
write	No	true	Overwrite input files. Should be disabled if using check.
ignore	No	""	Comma separated list of paths to ignore. Only for .hcl files.
diff	No	false	Display diffs of formatting changes.
check	No	false	Check if files are malformatted.
recursive	No	true	Also process files in subdirectories.
dir	No	"."	Path to be checked. Current dir as default.

📤 Output Parameters

Output	Description
files_changed	List of changed files

💻 Usage Examples

📝 Basic Example

Action can fail if malformed files will be found.

name: Check HCL
on:
  push
jobs:
  format-hcl:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v6

    - name: Fail on malformatted files
      uses: devops-infra/action-format-hcl@v1.1.2
      with:
        check: true

🔀 Advanced Example

Action can automatically format all HCL files and commit updated files back to the repository using my other action action-commit-push.

name: Format HCL
on:
  push
jobs:
  format-hcl:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v6

    - name: Format HCL files
      uses: devops-infra/action-format-hcl@v1.1.2

    - name: Commit changes to repo
      uses: devops-infra/action-commit-push@v1
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        commit_prefix: "[AUTO-FORMAT-HCL]"

🎯 Use specific version

Pick the tag level based on your stability needs:

• vX.Y.Z: exact immutable release (most predictable)
• vX.Y: latest patch within one minor line
• vX: latest patch within one major line

name: Use pinned action version
on: [push]
jobs:
  format-hcl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: devops-infra/action-format-hcl@v1.1.2
        id: pin-patch

      - uses: devops-infra/action-format-hcl@v1.1
        id: pin-minor

      - uses: devops-infra/action-format-hcl@v1
        id: pin-major

🤝 Contributing

Contributions are welcome! See CONTRIBUTING. This project is licensed under the MIT License - see the LICENSE file for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

If you have any questions or need help, please:

• 📝 Create an issue
• 🌟 Star this repository if you find it useful!

🧪 End-to-End Validation

Use the manual workflow .github/workflows/manual-e2e-validate.yml to validate this action against the centralized E2E repository.

• mode=image validates a published image tag (recommended for -test and -rc release checks).
• mode=ref validates ref-oriented E2E paths against stable pinned action refs.

CI/CD automation also runs these E2E checks automatically:

• Pull requests: E2E validation runs through reusable org workflows.
• Release branch prepare: E2E validation runs against release candidate artifacts (-rc).
• Release create: E2E validation runs against production release artifacts.

Example trigger inputs:

mode=ref

mode=image
image_tag=v1.2.3-test

Forking

To publish images from a fork, set these variables so Task uses your registry identities: DOCKER_USERNAME, DOCKER_ORG_NAME, GITHUB_USERNAME, GITHUB_ORG_NAME.

Two supported options (environment variables take precedence over .env):

# .env (local only, not committed)
DOCKER_USERNAME=your-dockerhub-user
DOCKER_ORG_NAME=your-dockerhub-org
GITHUB_USERNAME=your-github-user
GITHUB_ORG_NAME=your-github-org

# Shell override
DOCKER_USERNAME=your-dockerhub-user \
DOCKER_ORG_NAME=your-dockerhub-org \
GITHUB_USERNAME=your-github-user \
GITHUB_ORG_NAME=your-github-org \
task docker:build

Recommended setup:

• Local development: use a .env file.
• GitHub Actions: set repo variables for the four values above, and secrets for DOCKER_TOKEN and GITHUB_TOKEN.

Publish images without a release:

• Run the (Manual) Release Create workflow with build_only: true to build and push images without tagging a release.