HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Well-Architected Framework

GitOps workflow

GitOps is a deployment methodology that uses Git repositories as the single source of truth for both application code and infrastructure configuration. When developers want to make changes, they submit pull requests to update the Git repository. Once merged, the GitOps tooling automatically applies those changes to the target environment. The GitOps development cycle creates a fully auditable, version-controlled deployment process, where Git serves as the control plane for your entire infrastructure and application lifecycle.

Why implement GitOps

Implementing GitOps workflows addresses the following operational and security challenges:

  • Eliminate deployment inconsistencies and configuration drift: Manual deployments and ad-hoc infrastructure changes create configuration drift where production environments diverge from their intended state. Teams lack confidence in what is actually deployed versus what should be deployed. GitOps ensures your Git repository always reflects the true state of your infrastructure, eliminating drift and providing a reliable foundation for automation.

  • Improve audit trails and compliance: Traditional deployment processes lack comprehensive audit trails, making compliance verification difficult and incident investigation time-consuming. Teams struggle to answer "who changed what, when, and why" during audits or outages. GitOps provides complete traceability through Git history, with every change recorded, reviewed, and attributed to specific commits and pull requests.

  • Accelerate deployment velocity and reduce bottlenecks: Manual approval processes and ticket-based deployments create coordination bottlenecks that slow release cycles. Teams wait for operations approvals, environment availability, and deployment windows. GitOps enables self-service deployments through merge permissions, allowing developers to deploy changes as soon as pull requests are approved, removing operational bottlenecks.

  • Reduce deployment errors and improve reliability: Manual deployments involve running commands directly against production, creating risk of typos, wrong environments, and forgotten steps. A single incorrect command can cause outages or data loss. GitOps eliminates manual execution by automating all deployments from Git, ensuring every deployment executes identically and reducing human error.

GitOps principles and workflow

GitOps follows four core principles that create a reliable, automated deployment process:

Declarative infrastructure: Your entire system state is described declaratively in Git using infrastructure as code. Terraform configurations, Kubernetes manifests, and application configurations live in version control, defining the desired state of your infrastructure and applications.

Git as single source of truth: Git repositories serve as the authoritative source for system state. Any change to infrastructure or applications must go through Git. Changes made outside Git create drift that GitOps tooling automatically corrects by reconciling actual state with Git state.

Automated deployment from Git: GitOps tools continuously monitor Git repositories and automatically apply changes when new commits are merged. When you merge a pull request updating Terraform configurations, HCP Terraform automatically plans and applies the changes, deploying infrastructure without manual intervention.

Continuous reconciliation: GitOps systems continuously compare actual system state against desired state in Git and automatically correct any drift. If someone manually modifies infrastructure, GitOps detects the difference and reverts the change to match Git, maintaining consistency.

When you implement GitOps, you gain the following benefits:

  • Version control: All changes to infrastructure and applications are tracked in Git, providing a complete history of changes with the ability to rollback to any previous state.
  • Auditability: Since Git records all changes, you can easily audit who made changes, when they were made, and what the changes were through Git commit history and pull request reviews.
  • Collaboration: Teams can collaborate on infrastructure and application changes using pull requests, which creates a place for code reviews, discussions, and approval workflows before changes reach production.
  • Automation: GitOps workflows automate the deployment process, reducing manual intervention and the risk of human error by eliminating manual command execution against production systems.
  • Consistency: By using Git as the source of truth, you ensure GitOps deploys your infrastructure and applications consistently across environments, with development, staging, and production all managed through the same GitOps workflow.

GitOps workflow sequence

When you implement GitOps with HashiCorp tools, deployments follow the following automated sequence:

  1. Developer commits infrastructure changes: A developer modifies Terraform configurations or Packer templates in their local environment and commits the changes to a feature branch in Git. These changes might include new resources, configuration updates, or infrastructure modifications.

  2. Developer creates pull request: The developer opens a pull request to merge their feature branch into the main branch. This pull request triggers automated checks and provides a place for team collaboration and code review.

  3. HCP Terraform runs speculative plan: When you connect your HCP Terraform workspace to your VCS repository, HCP Terraform automatically runs a speculative plan when it detects the pull request. This plan shows what infrastructure changes will occur without actually applying them, allowing reviewers to understand the impact before merging.

  4. Sentinel validates against policies: If you have Sentinel policies configured, HCP Terraform evaluates the plan against your policy-as-code rules. Sentinel checks for security requirements, compliance standards, cost limits, and naming conventions. If policies fail, the plan cannot proceed until you address the violations.

  5. Team reviews and approves: Team members review the pull request, examining both the code changes and the Terraform plan output. They discuss the changes, request modifications if needed, and approve the pull request once satisfied.

  6. Developer merges pull request: After receiving approvals and passing all checks, the developer merges the pull request into the main branch. This merge event triggers the automated deployment process.

  7. HCP Terraform applies changes automatically: HCP Terraform detects the merge to the main branch and automatically runs a new plan followed by an apply operation. The infrastructure changes deploy without manual intervention, using the exact code from the Git repository.

  8. System reconciles to desired state: After the apply completes, your infrastructure matches the desired state defined in Git. If someone manually modifies infrastructure outside of Git, HCP Terraform detects the drift during the next run and reconciles the actual state back to match Git.

This workflow ensures that every infrastructure change goes through version control, code review, automated validation, and policy enforcement before deployment. Git maintains a complete audit trail of who made changes, when they were made, and why they were necessary.

Implement GitOps with HashiCorp tools

HashiCorp provides several tools that enable GitOps workflows for infrastructure and application deployments:

HCP Terraform with VCS integration: HCP Terraform integrates directly with GitHub, GitLab, Bitbucket, and Azure DevOps to implement GitOps for infrastructure. When you connect your Terraform configurations to a VCS repository, HCP Terraform automatically triggers plan and apply operations when you merge pull requests. This provides automated infrastructure deployment with policy enforcement through Sentinel, cost estimation, and collaborative workflows.

Terraform for infrastructure as code: Terraform's declarative configuration language lets you define infrastructure state in Git repositories. Changes to Terraform configurations trigger automated deployments through HCP Terraform or CI/CD pipelines, ensuring infrastructure always matches the desired state defined in Git.

Packer for immutable image builds: GitOps workflows use Packer to build immutable machine images and container images from version-controlled templates. When Packer templates change in Git, CI/CD pipelines automatically build new images, maintaining consistency between infrastructure code and deployment artifacts. After Packer builds an AMI or container image, you reference the artifact in Terraform using data sources or image tags, connecting your image building workflow to your infrastructure deployment workflow.

Vault for secrets management: GitOps workflows require secrets without storing them in Git repositories. Vault provides dynamic secrets and centralized secret management, allowing your GitOps deployments to retrieve credentials at runtime without committing secrets to version control. When HCP Terraform applies your configuration during automated deployments, it retrieves database passwords, API keys, and cloud credentials from Vault dynamically, ensuring secrets never appear in Git history or Terraform state files.

Sentinel for policy as code: Sentinel enforces organizational policies on infrastructure changes before they deploy. Policy files stored in Git define security requirements, compliance standards, and cost controls that automatically validate infrastructure changes during the GitOps workflow. During the pull request workflow, Sentinel evaluates the Terraform plan and blocks the apply if policies fail, preventing non-compliant infrastructure from deploying and requiring developers to fix violations before merging changes.

Example: Terraform configuration in a GitOps workflow

The following Terraform configuration demonstrates a GitOps workflow where infrastructure code lives in a Git repository connected to HCP Terraform:

terraform {
  # HCP Terraform backend stores state remotely
  cloud {
    organization = "example-org"
    workspaces {
      name = "production-infrastructure"
    }
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-west-2"
}

# Query the latest AMI built by Packer
data "aws_ami" "app" {
  most_recent = true
  owners      = ["self"]

  filter {
    name   = "tag:Application"
    values = ["web-app"]
  }

  filter {
    name   = "tag:Built-By"
    values = ["packer"]
  }
}

# Deploy application instances using Packer-built AMI
resource "aws_instance" "app" {
  count         = 3
  ami           = data.aws_ami.app.id
  instance_type = "t3.medium"

  tags = {
    Name        = "web-app-${count.index}"
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

# Create load balancer for the application
resource "aws_lb" "app" {
  name               = "web-app-lb"
  load_balancer_type = "application"

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

When you commit this configuration to your Git repository and merge a pull request, HCP Terraform automatically applies the changes. The configuration uses a data source to query the latest AMI that Packer built and tagged, demonstrating how GitOps workflows connect multiple HashiCorp tools. The HCP Terraform cloud backend stores state remotely, enabling team collaboration and maintaining a single source of truth for infrastructure state alongside your code in Git.

Example: Sentinel policy for GitOps validation

The following Sentinel policy enforces tagging requirements on all AWS resources, ensuring every infrastructure change includes proper metadata for tracking and cost allocation:

import "tfplan/v2" as tfplan

# Find all AWS resources in the plan
all_resources = filter tfplan.resource_changes as _, rc {
  rc.provider_name is "registry.terraform.io/hashicorp/aws" and
    rc.mode is "managed" and
    (rc.change.actions contains "create" or rc.change.actions contains "update")
}

# Require tags on all resources
required_tags = ["Environment", "ManagedBy"]

# Check each resource has required tags
resource_tags_valid = rule {
  all all_resources as _, resource {
    all required_tags as tag {
      resource.change.after.tags[tag] is not null
    }
  }
}

# Main rule
main = rule {
  resource_tags_valid
}

When you configure this policy in HCP Terraform, it evaluates every Terraform plan during the pull request workflow. If a developer tries to create infrastructure without required tags, Sentinel blocks the apply operation and requires the developer to add the missing tags before the changes can deploy. This enforces organizational standards automatically without manual review, ensuring compliance across all infrastructure managed through your GitOps workflow.

HashiCorp resources:

Terraform for GitOps:

Vault for GitOps secrets:

Packer for GitOps image building:

Next steps

In this section of Process automation, you learned why GitOps workflows improve deployment reliability, how GitOps principles create automated deployment processes, and which HashiCorp tools enable GitOps implementations. GitOps workflow is part of the Define and automate processes pillar.

Continue your automation journey with the following documents:

Edit this page on GitHub