The control repository is the heart of code management for r10k and Code Manager. It is a single point of entry, represented as a Git repository, that describes one or more environments of one or more Puppet Masters. 

r10k is designed to provide the following to a Puppet environment, from a control repository:

• Each Puppet module required to make a code set via the Puppetfile
• A Hiera hierarchy
• Hiera data
• An environment-specific configuration
• Any additional code (such as site.pp, roles, or profiles)

Multiple states on a single Puppet Master can be achieved by using a concept that was launched in Puppet 3: Puppet environments. In Puppet 3, we gained the ability to use multiple directories to store code, and to select which code directory each agent uses individually. Code Manager and r10k expand on this concept by treating every branch of the control repository as a completely separate environment.

If a control repository contains multiple branches, r10k can deploy each branch individually, as a separate environment. This does make our control repository branches a little different from a standard Git repository. Traditionally, the best model is trunk-based development, which gives us one master branch that is intended to receive all of the finished code changes. A Puppet control repository usually contains multiple long-lived and short-lived branches, with varying levels of intention to merge code between the branches. In the best scenario, we merge our code with the different levels of environments, until we reach production. Our Puppetfile, covered later in this chapter, is often the file that differs the most between the environments.

In a situation where an organization has formal production, preproduction, and development environments, and users actively working on Puppet code, we may see the following branches:

• Production
• Preproduction
• Development
• Feature1
• Feature2

Feature1 and Feature2 would be considered short-lived branches, with changes intended for merging into the development environment. Puppet environments are not required to be one for one with what an organization would consider their own environments, and often should not be. Do not feel restricted to making your Puppet environments exactly conform to the organizational boundaries of servers.

One of the easiest ways to view these environments is to categorize your control-repo branches internally as production-like and non-production-like.