Provider compatibility

Dealing with provider shenanigans.

Heckle pins exact provider versions. Provider defaults, import behaviour and API semantics can differ even when the forge itself has not changed, so provider upgrades should be planned carefully.

Audited provider pins

ForgeProviderAudited version
GitHubintegrations/github6.13.0
GitLabgitlabhq/gitlab19.3.0
Giteago-gitea/gitea0.8.1
Forgejosvalabs/forgejo1.6.0
heckle compatibility
heckle compatibility github
heckle compatibility --json

Compatibility policy

Heckle does not resolve provider latest at runtime. A provider version is considered supported only after its import IDs, schema and relevant read/update behaviour have been reviewed for the resources Heckle manages.

--provider-version can override a pin for investigation, but an unaudited version also requires --allow-untested-provider. That opt-in means Heckle's compatibility knowledge may be incomplete.

Why pin so tightly? A provider can change defaults, import IDs, computed/optional semantics or update payloads without the forge API changing. Heckle treats those changes as compatibility work, not ordinary dependency updates.

What “known provider behaviour” means

Heckle records narrow, version-specific provider behaviours when it has evidence that a plan difference is associated with a particular parent-feature condition or provider limitation. Recognition is descriptive only. It is not a guarantee that applying the plan is safe or appropriate.

Create, delete and replacement actions are never accepted by a known-behaviour rule. Unrecognised updates remain adoption failures.

GitHub — integrations/github 6.13.0

Organization repository-creation settings are deliberately unmanaged

The provider can update GitHub's coupled repository-creation booleans independently even though GitHub treats them as a related set. Heckle therefore leaves these fields unmanaged:

  • members_can_create_repositories
  • members_can_create_public_repositories
  • members_can_create_private_repositories
  • members_can_create_internal_repositories

Upstream: terraform-provider-github #3429.

Explicit empty Actions pattern lists are not enforced

An explicit empty allowed_actions_config.patterns_allowed list is not reliably sent by this provider version. Heckle does not try to enforce an empty list.

Upstream: terraform-provider-github #3458.

GitLab — gitlabhq/gitlab 19.3.0

Default branch protection takeover

GitLab's provider documentation notes that taking management of an existing default branch protection can temporarily unprotect and re-protect it. Heckle relies on state adoption and plan classification rather than trying to recreate that protection.

Create/destroy controls are not imported remote state

Heckle excludes these project/group controls because they describe create/destroy behaviour rather than settings discovered from the existing remote object:

  • Projects: skip_wait_for_default_branch_protection, permanently_delete_on_destroy.
  • Groups: archive_on_destroy, permanently_remove_on_delete.

Dependent merge settings

Heckle can recognise specific subordinate plan differences only while their controlling feature remains disabled before and after the proposed update:

  • allow_merge_on_skipped_pipeline when only_allow_merge_if_pipeline_succeeds = false.
  • merge_trains_enabled and merge_trains_skip_train_allowed when merge_pipelines_enabled = false.

Recognition does not decide whether you should apply such a plan.

Gitea — go-gitea/gitea 0.8.1

No additional version-specific quirk is currently recorded in Heckle's compatibility registry. That does not mean the provider is perfect; it means Heckle has not encoded a specific exception for this audited version.

Gitea team membership is authoritative when Heckle manages that resource family. Review planned membership removals particularly carefully.

Forgejo — svalabs/forgejo 1.6.0

Pull-request settings when pull requests are disabled

This provider can round-trip subordinate merge settings to provider defaults while has_pull_requests = false. Heckle recognises the affected attributes only while that parent flag remains false before and after the proposed update.

The affected family includes merge/rebase/squash options, default merge/update styles, whitespace-conflict handling and related pull-request defaults.

Recognition is not a safety verdict. These differences may be reasonable to reconcile because the parent feature is disabled, but Heckle cannot decide whether that is appropriate in your environment. Review the actual plan.

Other disabled-feature relationships

  • Issue-tracker subordinate settings when has_issues = false.
  • Wiki subordinate settings when has_wiki = false.
  • Mirror subordinate settings when mirror = false.

Repository creation/migration fields

Heckle does not copy repository creation/migration options such as migration service/clone controls into ongoing configuration for an already-existing repository. Mirror settings the provider cannot faithfully reconstruct are also left out.

Organizations

Forgejo organizations are inventory-only in this adapter because the selected provider's organization resource does not provide the import contract Heckle needs for adoption.

How and when we adopt a new provider version as the default in Heckle

As part of developing Heckle, we:

  1. Read release notes and import/state-related upstream issues since the audited version.
  2. Compare provider schemas, especially Optional/Computed/default/ForceNew changes.
  3. Run the complete Heckle suite and provider-specific fixtures.
  4. Rehearse discovery/adoption against a disposable namespace.
  5. Review every compatibility entry: keep it, update its version scope, or remove it only when the upstream behaviour is demonstrated fixed.
  6. Update both the provider pin and Heckle's separate audited-version allowlist.

The release pin is the maintenance boundary. A new upstream provider release does not change an existing Heckle release until we deliberately adopt it into Heckle.