Git Based Dynamic Environments
==============================

R10k can use Git repositories to implement dynamic environments. You can create,
update, and delete Puppet environments automatically as part of your normal Git
workflow.

Dynamic Environments in a nutshell
----------------------------------

The core idea of dynamic environments is that you should be able to manage your
Puppet modules in the same manner that you would manage any other code base. It
builds on top of Git topic branch model.

[git-topic-branching]: http://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches

One of the most prevalent ways of using Git relies on using [topic branches][git-topic-branching].
Whenever changes need to be made that need to be reviewed or tested before going
live, they should be done in a different, short lived branch called a topic
branch. Work can be freely done on a topic branch in isolation and when the work
is completed it is merged into a "master" or "production" branch. This is very
powerful because it allows any number of people to rapidly develop features in
isolation and merge features in a single operation.

The dynamic environment model extends this git branching strategy to
your live Puppet masters. It creates a mapping between Git branches and Puppet
environments so that you can use the Git branching model and have that be
seamlessly reflected in Puppet environments. This means that creating a new Git
branch creates a new Puppet environment, updating a Git branch will update that
environment, and deleting a Git branch will remove that environment.

R10k supports both [directory and config file environments](https://puppet.com/docs/puppet/latest/env_environments.html).
Ensure that the basedir for your sources and your puppet config align.

How it works
------------

R10k works by tracking the state of your Git repository or repositories. Each
repository's branches will be cloned into a directory with a matching name,
creating a Puppet environment for the branch. If a repository includes a
Puppetfile, such as the control repo, the Forge modules and Git/SVN
repositories described within will be cloned as well, into the same directories.
Subsequent changes to the branches will be kept in sync on the filesystem by
future r10k runs. Finally, if there are directories that do not match existing
branches, r10k will assume that the branches for those environments were delete
and will remove those environments.

r10k will need to be be able to authenticate with each repository. Most Git
systems support authentication with SSH keys. GitHub calls them [deploy
keys][github-deploy-keys]. Bitbucket calls them [deployment
keys][bitbucket-deployment-keys]. Stash calls them [SSH access
keys][stash-access-keys].

[github-deploy-keys]: https://developer.github.com/guides/managing-deploy-keys/#deploy-keys
[bitbucket-deployment-keys]: https://confluence.atlassian.com/display/BITBUCKET/Use+deployment+keys
[stash-access-keys]: https://confluence.atlassian.com/display/STASH/SSH+access+keys+for+system+use

Configuration
-------------

The following configuration options can be specified for Git based environment
sources.

### invalid_branches:

This setting specifies how Git branch names that cannot be cleanly mapped to
Puppet environments will be handled.

Valid values:

  * 'correct_and_warn': Non-word characters will be replaced with underscores
    and a warning will be emitted. (Default)
  * 'correct': Non-word characters will silently be replaced with underscores.
  * 'error': Branches with non-word characters will be ignored and an error will
    be emitted.
