Use version control

Version control tracks changes to files over time so you can collaborate safely, understand what changed, and recover quickly when something breaks. This document focuses on Git as the version control system, but you can apply the same practices to other version control systems. Without version control, teams often share configuration through email, chat, shared drives, or production servers, which makes it hard to review changes, reproduce history, or roll back to a known-good state.

The following are key concepts when using version control with Git:

• Repository: A project folder that Git tracks.
• Commit: A saved snapshot of your changes with a message explaining why you made them.
• Branch: A separate line of work you use to develop changes without impacting the main branch.
• Pull request (PR): A review process for merging changes from a branch into the main branch.

Why use version control

Version control helps you solve the following problems:

• Collaborate without overwriting changes: Version control lets multiple people work on the same files and merge updates with a clear history.

• Review changes before you apply them: Pull requests and code reviews help you catch mistakes early.

• Recover when something breaks: Version control lets you roll back by reverting to an earlier commit.

• Create an audit trail: Commit history records who changed what and why, which supports security and compliance reviews.

Establish safe workflows

As you adopt version control, keep your workflow simple and add protections as your team grows.

• Use branches and pull requests: Create a branch for each change, open a pull request, and merge after review.

• Protect the main branch: Require pull request reviews, block force pushes, and require automated checks when you have them.

• Preview changes before merging: For example, when you use HashiCorp tools with version control, you can preview the impact of changes during pull requests. Run terraform plan to see infrastructure changes, packer validate to check image templates, nomad plan to preview application deployments, or consul validate to verify service configurations before merging to the main branch.

Write useful commit messages

Commit messages help you and your teammates understand what changed and why.

Use a short summary line that describes the intent of the change, then add details when the change needs extra context.

<type>: <short summary>

<optional details about what changed and why>

Example:

docs: add onboarding notes for version control

Explain basic Git terms and how to make a first commit.

Use version control with HashiCorp tools

HashiCorp tools use declarative configuration files written in HCL (HashiCorp Configuration Language) that work well with version control. Store these configuration files in a Git repository to track changes, collaborate with teammates, and review updates before applying them.

Configuration files for HashiCorp tools include:

• Terraform configuration files (.tf) define infrastructure resources, providers, and modules
• Packer templates (.pkr.hcl) define machine images and build configurations
• Vault policies (.hcl) define access control and secret management rules
• Consul service definitions and configuration files manage service discovery and mesh networking
• Nomad job specifications (.nomad or .hcl) define application deployments and scheduling
• Sentinel policies (.sentinel) define policy-as-code rules for governance
• Boundary configuration files define access policies and target resources

When you store these files in version control, you gain the same benefits across all HashiCorp tools. You can collaborate through branches and pull requests, track changes through commit history, and review infrastructure, security policies, and deployment configurations before applying them to production environments.

HashiCorp resources

• Read Define infrastructure as code to understand why version control pairs well with declarative infrastructure
• Review Map your workflows to identify processes that benefit from repeatable reviews and approvals
• Learn to standardize workflows across HashiCorp tools with version control

Learn how HashiCorp tools integrate with version control:

• Read about Terraform version control workflows for automated planning and applying
• Learn about HCP Packer image pipelines for tracked and versioned machine images
• Explore Vault policy management for versioned security policies and audit trails
• Read about Nomad job submission workflows for declarative application deployments

External resources:

• Install Git with the Git downloads for Windows, macOS, and Linux
• Read the Git documentation for commands, workflows, and troubleshooting
• Read the Pro Git book for comprehensive Git fundamentals

Next steps

Use version control is part of the Define and automate processes pillar.

After you commit your first changes, take the following steps to keep building your workflow:

• Implement CI/CD to automate checks and deployments for version-controlled changes
• Assess your automation maturity to identify where you can standardize and automate next
• Create reusable modules to share and version infrastructure components