PSICK: a Puppet control-repo you clone, populate and run

PSICK ships a filled-in control repo rather than an empty scaffold

Most Puppet control repositories start as a directory tree with a handful of manifests and a lot of decisions left to you. PSICK takes the opposite position. It is presented as a modern, opinionated, general purpose and customisable control-repo, and the README lists what that buys you: support for multiple ways of testing local Puppet code, including unit, integration and acceptance tests against multiple targets, support for several CI solutions such as GitLab, GitHub and CD4PE, and usability in any Puppet setup built on Puppet Enterprise or Puppet Open Source, with or without Foreman. The word opinionated is doing real work there. You inherit a set of choices about where Hiera data lives, how profiles are structured and how code reaches a machine. The trade is that you get a working environment on day one and spend your effort changing it rather than assembling it. The companion module, puppet-psick, is what makes the classification layer work, providing an interface for Hiera driven nodes classification and ready to use profiles for common system baselines, with application specific profiles handled through the separate psick_profile module. Sample Hiera data for the repository lives in its own psick-hieradata module.

The psick command creates either a minimal skeleton or the full contents

Entry to the project is a single shell entry point named psick, living at the top of the repository. The setup instructions begin with cloning the project and invoking that command:

    git clone https://github.com/example42/psick
    cd psick
    ./psick create

The command currently does one thing: it creates a new control-repo and populates it either with a bare minimal skeleton or with the full PSICK contents. The README is explicit that picking single components, diffing them against your own control-repo and updating them locally are future capabilities rather than current ones. That is worth knowing before you plan a workflow around incremental updates, because today the choice is binary and the fork carries the whole set of choices with it. After the create step you work inside your own repository, and there is an important caveat about where you run the remaining commands. If you copied the full PSICK contents, run them from your own control-repo directory. If you took the minimal skeleton, run them from the PSICK directory. The documentation warns that some scripts in bin/ and the other integrations might not work correctly in a setup that is not the full PSICK. In other words, the minimal skeleton is a starting point for reading and learning the structure, not a supported production shape.

Hiera data is loaded from a module, not from a directory in your repo

The directory listing is where PSICK makes its conventions visible, and one choice stands out from the usual control-repo pattern. A standard layout has a hieradata/ directory inside the control-repo, and Hiera 5 reads hiera.yaml to find it. PSICK keeps that directory around but notes that since version 0.9.3 its default datadir is loaded from a module in modules/hieradata/data instead. An equivalent Hiera 3 file ships as hiera3.yaml, which was linked to /etc/puppetlabs/puppet/hiera.yaml. The rest of the layout follows the familiar set: environment.conf as the environment configuration file, manifests/ holding just site.pp as the main manifest, a Puppetfile that defines the external modules to add via r10k, and modules/ where those modules are placed, which is gitignored because r10k populates it. Alongside those, PSICK adds directories of its own: bin/ holds tools and scripts for Puppet related operations, docs/ carries extra documentation, site/ is an additional modules directory for local profiles and tools, docker/ holds files used for building images for multiple operating systems, vagrant/ contains environments where local Puppet code can be tested, and .gitlab-ci.yaml is a sample GitLab pipeline for code testing and deployment. The top-level listing shows further tooling such as packer/, terraform/, gitlab/, spec/, keys and inventory.yaml, plus a bolt-project.yaml.

bin/puppet_setup.sh does the heavy lifting and asks for root

The setup path assumes Puppet 4 or later is already present or that you are willing to install it with the bundled cross-OS script, which uses the official Puppet repositories:

    sudo bin/puppet_install.sh # Only if you don't have Puppet 4 installed

Next you need the prerequisite gems, hiera-eyaml, deep_merge and r10k, and the modules directory populated by r10k:

    bin/puppet_setup.sh        # Only if you don't have the prerequisites gems

If you already have r10k and the prerequisite gems, the underlying command is a plain r10k install:

    r10k puppetfile install -v

There is a third script for the optional tooling:

    bin/setup.sh               # Only if you want to install Vagrant and Docker

That script installs and runs r10k and then uses Puppet to install the other software, and the recommended Vagrant and Docker tools are what the vagrant/ and docker/ directories are meant to work with. The behaviours that matter operationally are all stated plainly. You are always asked to confirm or skip each step, the script uses sudo for operations that need root privileges, and it can be interrupted with CTRL+C at any time. For unattended setups in CI pipelines you can pass the argument auto to skip confirmation requests:

        bin/puppet_setup.sh auto
        bin/setup.sh auto

Both the development workstation and the Puppet server need this treatment. The control-repo has to be placed into the /etc/puppetlabs/code/environments/ directory on the server, and the modules directory has to be populated in both places.

The setup scripts are documented as untested on Mac in places

The documented caveats around the scripts are more than legal boilerplate. The README states that scripts are mostly tested on Mac and Linux environments, and then that on Mac some package installations do not work. There is no list of which packages fail, so a Mac user has to discover that empirically. This matters because the repository is presented as cross-OS, with a cross OS Puppet install script and a docker/ directory holding files for building images for multiple operating systems. The script design also carries a security weight that a code-only library does not: bin/puppet_setup.sh invokes sudo for the steps that need root, and bin/setup.sh installs and runs r10k and then delegates further installation to Puppet. Running it means granting root to a shell script from a repository you cloned, on a machine where the Docker and Vagrant tooling it installs will then be used to bring up full operating system environments. That is normal for infrastructure automation, but it should be a deliberate decision rather than the first thing you paste into a terminal. The scripts are interactive by default, and the auto argument exists for CI, which are two different trust postures for the same script.

CI wiring and test targets are configuration, not a hosted service

Testing is the part of PSICK that goes furthest beyond a bare control-repo. The repository supports unit, integration and acceptance tests on multiple targets, and the top-level listing shows the machinery that implies: a spec/ directory, a .rspec file, .fixtures.yml for fixture modules, a Rakefile, a Gemfile alongside Gemfile.disable, .rubocop.yml and .yardopts for linting and documentation, plus several CI entry points. The README names GitLab, GitHub and CD4PE as supported CI solutions and ships .gitlab-ci.yaml as a sample pipeline for code testing and deployment. Other continuous integration entry points sit at the root too, including a Jenkinsfile, .travis.yml with a .travis.yml.nopdk companion, appveyor.yml and a Dangerfile. The repository also advertises a Gitpod ready-to-code badge and carries .gitpod.yml and .gitpod.Dockerfile, so a browser based environment is possible without assembling one yourself. Compatibility is stated in version terms: Puppet OSS 4.9 or later, or Puppet Enterprise 2017.1.0 or later. The vagrant/ directory holds environments where local Puppet code can be exercised before it reaches a server, and docker/ holds the files for building images across operating systems, which gives you a way to test the same code against more than one target distribution.

No releases, and a psick command that promises more than it does

Two facts about the project's maturity are worth putting next to the feature list. First, the repository publishes no GitHub releases, so there is no tagged artifact to pin a production deployment to and no changelog-based upgrade path for the control-repo itself. The last push to the repository was on 2026-04-29, and the project is not archived. Second, the psick command is described in the present tense as doing one job, with component selection, diffing against an existing control-repo and local updates all framed as future work. That is a common pattern in infrastructure tooling where the skeleton ships first and the migration tooling arrives later, but it means that today the upgrade story for a fork is manual. The related modules follow their own release cycles and are not pinned by anything in this repository. The included CHANGELOG.md and CONTRIBUTING.md files indicate that change tracking and contribution rules exist, and the .pdkignore file points to the Puppet Development Kit conventions, while metadata.json carries module metadata. The licence is Apache-2.0, which permits modification and redistribution of the control-repo contents with the usual obligations to retain notices, and the repository also carries a separate License.md file alongside the LICENSE file, so it is worth reading both before you redistribute a forked copy inside a company.

Where PSICK overlaps with a plain control-repo of your own

The honest alternative here is not a competing product but the alternative of writing the same handful of files yourself. A conventional control-repo gives you environment.conf, manifests/site.pp, a Puppetfile, hiera.yaml and an empty modules/ directory, and you assemble everything else. PSICK is that skeleton plus working conventions: node classification through the puppet-psick module, baseline profiles, sample Hiera data from psick-hieradata, application profiles through psick_profile, CI configuration, and Vagrant and Docker test environments. The difference in approach is therefore about how much opinion you inherit. If your organisation already has an agreed control-repo shape, an established module set and its own Hiera layout, PSICK adds a large amount of inherited structure that you would have to unpick. The Hiera datadir change since version 0.9.3 is the clearest example, since it moves where data resolves from and would interact with any existing hiera.yaml. If you are starting fresh, the argument runs the other way: the alternative to adopting PSICK is months of assembling and testing the same layers, and the psick create command with the full contents is the shortest route to a working pipeline.

Editorial conclusion

PSICK suits teams already on Puppet 4 or later who want a filled-in control repository with node classification, profiles and test environments instead of an empty skeleton, and it suits people who want to see how a mature control-repo is put together. It is the wrong choice if you need something small, if your workstation is a Mac where the install scripts are known to fail on some packages, or if you need a released artifact, since the repository publishes no GitHub releases and its last push was on 2026-04-29. Before adopting it, check that bin/puppet_setup.sh completes on your platform, decide whether you want the full PSICK contents or the minimal skeleton, and confirm your Puppet server can read the Hiera layout that PSICK ships.

Frequently asked questions

Official sources

1. example42/psick on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README