Heckle — existing forges into maintainable HCL

Quickstart

One forge in. Ordinary HCL out.

Install Heckle, provide the forge token through your environment, and generate HCL into a new directory for use with OpenTofu or Terraform.

Full installation and credential setup →

$ pipx install heckle
$ export GITHUB_TOKEN='...'
$ heckle generate github --org myorg

# Terraform and Forgejo instead of Github and the default OpenTofu:
$ export FORGEJO_API_TOKEN='...'
$ heckle generate forgejo --me --url https://code.example.org --tf terraform

Mental model

A migration tool, not a permanent operator.

Heckle gets an existing forge under Infrastructure as Code. Once adoption is complete, you should maintain the generated HCL directly.

Discover

Read the namespace, repositories, memberships and supported forge settings.

Generate

Compile discovered state into normal .tf files and local modules.

Adopt

Rehearse imports, classify known provider behaviour and stop on unrecognised changes.

Manage

Edit and run the resulting Terraform/OpenTofu project normally. Heckle is no longer required.

The important bit

Providers are not perfectly transparent.

Different provider versions have import quirks, create-only settings, defaults and API edge cases. Heckle pins audited provider versions and records the behaviours it knows about instead of hiding them.

Audited pins

Heckle does not chase provider latest. Each release targets exact provider versions that have been reviewed.

See the current pins →

Known provider behaviour

Version-specific quirks are documented centrally, including which fields Heckle deliberately leaves unmanaged. Many providers do not let you import existing secrets - managing those is up to you.

Read the compatibility notes →

Operator decides

Heckle can identify known behaviour and unrecognised changes, but it does not decide whether a plan is appropriate for your environment.

Understand adoption →

CLI

Five subcommands to step your way into well-maintained IAC.

Command	Purpose
generate	Discover a forge and produce a standalone Terraform/OpenTofu project.
inventory	Save discovery results and coverage without generating HCL.
coverage	Read a saved report without network access.
validate	Run init with no backend and validate the generated project.
compatibility	Show the audited provider pins and known upstream behaviours for this Heckle release.

All commands and options →

Heckle helps you understand a plan; it does not guarantee one is safe. Provider behaviour, forge APIs, defaults and upstream bugs can produce unintended changes. Review every Terraform/OpenTofu plan yourself. The decision to apply a plan, and responsibility for its effects, remains in your hands.