Orchestrating Terraform Workflows via GitHub Actions Independent of HCP Terraform

The architectural decision to automate infrastructure as code requires a strategic choice between purpose-built orchestration platforms and general-purpose continuous integration and continuous delivery (CI/CD) frameworks. While HashiCorp provides a tightly integrated ecosystem through HCP Terraform (formerly Terraform Cloud), a significant number of engineering teams opt to utilize GitHub Actions as their primary execution engine. This approach shifts the responsibility of state management, locking, and governance from a managed service to the user's own implementation. Transitioning to a GitHub Actions-centric model allows for tighter repository-level automation and increased flexibility, but it necessitates a deep understanding of the underlying components that HCP Terraform typically abstracts.

The core tension in this architectural shift lies in the distinction between the runner and the backend. GitHub Actions serves as the orchestrator or the runner—the compute environment where the Terraform binary is executed. However, Terraform is inherently stateful. Whether using a managed service or a generic CI/CD pipeline, Terraform requires a backend to store the state file and manage locks to prevent concurrent modifications. When moving away from HCP Terraform, the user must explicitly define and manage this backend, as GitHub Actions does not provide native state storage.

Architectural Divergence: HCP Terraform versus GitHub Actions

To understand the implications of removing HCP Terraform from the equation, one must analyze the fundamental differences in how these two systems handle infrastructure lifecycle management. HCP Terraform is a managed service specifically engineered for Terraform, providing a centralized hub for state, variable management, and policy enforcement. GitHub Actions, conversely, is a flexible automation tool integrated into the GitHub ecosystem, designed to trigger workflows based on repository events.

The following table delineates the functional capabilities and the operational burden associated with each approach:

The impact of this divergence is most felt in the "DIY surface area." By opting for GitHub Actions, a team removes the cost and vendor lock-in associated with HCP Terraform but inherits the responsibility of designing and maintaining the security model, the state locking mechanism, and the approval gates.

The Mechanics of State Management without HCP Terraform

The most critical requirement when running Terraform in GitHub Actions without HCP Terraform is the implementation of a remote backend. Because GitHub Actions runners are ephemeral—meaning they are destroyed after the job completes—any state stored locally on the runner would be lost immediately. This would lead to a catastrophic failure of the infrastructure lifecycle, as Terraform would attempt to recreate all resources on every single run.

A remote backend is mandatory. This is a storage mechanism that persists the terraform.tfstate file outside of the execution environment. Common choices for those avoiding HCP Terraform include:

• Google Cloud Storage (GCS)
• Amazon S3 (often paired with DynamoDB for locking)
• Azure Blob Storage
• HashiCorp Consul

The consequence of this requirement is that the user must configure the backend block within the Terraform configuration. For instance, a user employing GCS must ensure that the GitHub Action has the appropriate credentials to authenticate with Google Cloud to read and write the state file. Without this, the terraform init command will fail, as it cannot locate or initialize the remote state.

Implementing the hashicorp/setup-terraform Action

To execute Terraform commands within a GitHub workflow, the hashicorp/setup-terraform action is the primary tool. This is a JavaScript-based action designed to prepare the runner environment. Its operational logic involves several critical steps:

• Version Management: It downloads a specific version of the Terraform CLI and adds it to the system PATH, ensuring consistency across different workflow runs.
• Configuration: It can configure the Terraform CLI configuration file with an HCP Terraform/Terraform Enterprise hostname and API token. However, for users avoiding HCP Terraform, this specific functionality is optional.
• Wrapper Implementation: The action installs a wrapper script around the terraform binary. This wrapper is designed to capture STDOUT, STDERR, and the exit code of the command, exposing them as actionable outputs named stdout, stderr, and exitcode.

These outputs are essential for complex workflows where subsequent steps need to conditionally execute based on the result of a terraform plan or terraform apply. If a workflow does not require these outputs, the wrapper can be optionally skipped.

The action is compatible across multiple operating systems, supporting ubuntu-latest, windows-latest, and macos-latest. A specific technical requirement for windows-latest is that the shell must be explicitly set to Bash to ensure the wrapper scripts function correctly.

Overcoming the Token Requirement and Configuration Conflicts

A common point of confusion for practitioners is the perceived requirement for an HCP Terraform API token when using the hashicorp/setup-terraform action. Some users report contradictions where documentation suggests the token is optional, yet the job fails during execution, citing a missing token.

This failure typically occurs because the action may be attempting to default to an HCP Terraform configuration if certain environment variables are present or if the workflow is misconfigured to expect a managed backend. To run Terraform entirely independently of HCP Terraform, the user must ensure that:

• The Terraform configuration does not contain a cloud block pointing to HCP Terraform.
• The backend block is explicitly defined for a self-managed provider (like GCS).
• The GitHub Action is not configured to use HCP Terraform-specific wrappers that mandate a token.

For those using the Community Edition (TF CE) or OpenTofu, the path to independence involves utilizing self-hosted runners. By building a custom runner with the Terraform binary pre-installed and managing state via a remote provider, the dependency on HashiCorp's cloud tokens is completely eliminated.

Security Modeling in a DIY Automation Framework

While HCP Terraform centralizes secrets and workspaces to reduce the attack surface, GitHub Actions can be equally secure if designed with a least-privileged model. The shift from a managed service to a generic CI/CD tool moves the security burden to the DevOps engineer.

To achieve a high security posture without HCP Terraform, the following strategies should be employed:

• OpenID Connect (OIDC): Instead of storing long-lived cloud credentials as GitHub Secrets, use OIDC to allow GitHub Actions to request short-lived tokens from cloud providers (AWS, Azure, GCP). This eliminates the risk of leaked static credentials.
• Environment Protections: Utilize GitHub Environments to implement manual approval gates. This replicates the "plan and apply" approval workflow found in HCP Terraform, ensuring that a human must review the terraform plan output before the terraform apply step is executed.
• Least-Privileged Roles: Assign the OIDC provider a role with the minimum permissions necessary to manage the specific infrastructure components, rather than using a broad administrator account.

The Trade-offs of Generic CI/CD for Infrastructure

Choosing GitHub Actions over a specialized tool like HCP Terraform involves a trade-off between flexibility and "guardrails." HCP Terraform provides built-in ergonomics specifically for infrastructure, such as:

• Sentinel and Open Policy Agent (OPA): These allow for policy-as-code to be enforced before any infrastructure is provisioned.
• Drift Detection: Managed services can automatically detect when the actual state of the cloud differs from the defined state in code.
• Workspace Management: Centralized handling of variable sets across different environments (Dev, Staging, Prod).

When using a generic runner like GitHub Actions, these features are lost unless the user rebuilds them. For example, drift detection would require a scheduled GitHub Action (via schedule triggers) that runs a terraform plan and alerts the team if changes are detected. Policy enforcement would require integrating a separate step in the YAML workflow to run a tool like terrascan or checkov against the plan output.

Alternatives and the Spacelift Ecosystem

For organizations that find GitHub Actions too manual but HCP Terraform too restrictive or expensive, alternatives like Spacelift exist. Spacelift positions itself as a cost-effective alternative that bridges the gap between a generic CI/CD tool and a managed Terraform service.

Spacelift supports a wide array of tools beyond Terraform, including OpenTofu, Terragrunt, CloudFormation, Pulumi, Ansible, and Kubernetes. Its primary value proposition in the context of the "GitHub Actions vs. HCP Terraform" debate is its support for:

• Self-hosted and on-premises workers: Providing more control over the execution environment than GitHub-hosted runners.
• Native Drift Detection: Removing the need to manually script drift checks in YAML.
• Workflow Customization: Offering a more structured approach to pipeline orchestration than raw GitHub Action files.

Detailed Analysis of the Transition Path

The transition from a managed Terraform environment to a GitHub Actions-driven environment is not merely a change of tools, but a change in operational philosophy. The user moves from being a consumer of a platform to being the architect of a platform.

The impact of this shift is most evident in the lifecycle of a pull request. In a managed environment, the VCS integration automatically triggers a plan and presents it in a dedicated UI. In the GitHub Actions model, the engineer must define the on: pull_request trigger, configure the hashicorp/setup-terraform action, execute terraform plan, and then use a mechanism (such as stefanproctor/terraform-pr-comment or similar) to post the plan results back to the pull request for review.

Furthermore, the lack of a managed state means the engineer must handle the "state lock" failure. If a GitHub Action job is cancelled mid-apply, the state lock may remain active. In HCP Terraform, this is handled by the platform. In GitHub Actions, the engineer must manually intervene using terraform force-unlock or implement sophisticated error-handling scripts within the workflow to ensure the environment is cleaned up.

Conclusion

The ability to operate Terraform via GitHub Actions without the requirement of HCP Terraform is entirely feasible and provides a high degree of flexibility and integration. However, this autonomy comes at the cost of increased operational complexity. The removal of the managed service means that the responsibility for state persistence, concurrency locking, secret rotation, and policy enforcement shifts entirely to the user.

The success of this model depends on the rigorous implementation of a remote backend (such as GCS or S3) and the adoption of modern security practices like OIDC. While the hashicorp/setup-terraform action simplifies the installation and execution of the CLI, it does not replace the governance features of a dedicated infrastructure orchestration platform. Ultimately, the choice depends on the maturity of the team: those who prioritize rapid, repo-centric automation and have the expertise to build their own guardrails will find GitHub Actions superior, while those requiring centralized governance and reduced operational overhead will continue to rely on managed solutions.

Sources

1. HashiCorp Discuss - Use Terraform GitHub Actions without TFC
2. Spacelift Blog - Terraform Cloud vs GitHub Actions
3. HashiCorp Developer - Automating Terraform with GitHub Actions
4. GitHub Marketplace - hashicorp/setup-terraform