Common Workflows

Having a basic understanding of LinchPin is crucial to this section. Knowing the basic CLI operations leads nicely into using LinchPin in powerful ways.

Using linchpin fetch

The linchpin fetch command provides a simple way to access a resource from a remote location. One could simply perform a git clone, or use wget to download a workspace. However, linchpin fetch makes this process simpler, and includes some tooling to make the workflow smooth.

$ linchpin fetch --help
Usage: linchpin fetch [OPTIONS] REMOTE

  Fetches a specified linchpin workspace or component from a remote location

  -t, --type TYPE              Which component of a workspace to fetch.
                               (Default: workspace)
  -r, --root ROOT              Use this to specify the location of the
                               workspace within the root url. If root is not
                               set, the root of the given remote will be used.
  --dest DEST                  Workspaces destination, the fetched workspace
                               will be relative to this location. (Overrides
  --branch REF                 Specify the git branch. Used only with git
                               protocol (eg. master).
  --protocol [git|http|local]  Specify a protocol. (Default: git)
  --nocache                    Do not check the cached time, just copy the
                               data to the destination
  -h, --help                   Show this message and exit.

Fetching a Remote Workspace

This document will cover how to use linchpin fetch to obtain a workspace from both a git repository. An example for fetching an http workspace can be found here.

First, determine the destination. By default, the destination location is the current working directory. In this guide, we’ll use /tmp/workspaces.

$ mkdir /tmp/workspaces
$ cd /tmp/workspaces

Using the simplest possible linchpin fetch command will fetch the workspaces from git://

$ linchpin fetch git://
destination workspace: /tmp/workspaces/

$ pwd
$ ls -l
total 4
-rw-rw-r-- 1 herlo herlo 980 Sep  5 13:53 linchpin.log
drwxrwxr-x 5 herlo herlo 140 Sep  5 13:54 multi-target
drwxrwxr-x 2 herlo herlo  80 Sep  5 13:54 openstack
drwxrwxr-x 3 herlo herlo 120 Sep  5 13:54 os-server-addl-vols

The directory structure of should match the local directory as shown above.

As can be easily seen, linchpin fetch performed a git clone. Then copied all of the directories to the current directory. linchpin fetch assumes the root of the repository is a workspace.

Additional Options

If pulling all workspaces was not the intended action, there are other useful options. First, perform a little clean up.

$ cd && rm -rf /tmp/workspaces  # remove the workspaces directory
$ ls -l /tmp/workspaces
ls: cannot access '/tmp/workspaces/': No such file or directory


From here on in, this guide will use the LinchPin git repository. There are several workspaces with useful use cases. Feel free to peruse them as desired. This guide will use these workspaces going forward.

To clone from a repository with multiple workspaces (eg. the linchpin repository), a root must be specified. It is also recommended to use the --dest flag.

$ linchpin fetch git:// \
> --root workspaces/simple --dest /tmp/workspaces
Created destination workspace: /tmp/workspaces/simple

In this example, there are additional options. Let’s cover them in detail:

--root ROOT
This is the root of the repository. Normally, the root of the repository is used. However, if the workspaces reside elsewhere (eg. workspaces), use this option.
If the current working directory is not the desired location, use this option.

Performing a listing will show how these options affected the fetch.

$ ls -R /tmp/workspaces/

PinFile  README.rst

As expected, the simple root was pulled down, and placed inside the /tmp/workspaces directory on the local machine.

To have all workspaces copied into /tmp/workspaces, a change is needed.

$ linchpin fetch git:// \
> --root workspaces --dest /tmp
destination workspace: /tmp/workspaces


An observant user will notice that the same destination was used. This is because linchpin fetch maps the ROOT to the destination automatically. This behavior can be adjusted by removing the –dest option and specifying –workspace instead.

Listing the files again reveals more workspaces.

$ ls /tmp/workspaces/
dummy-aws  dummy-two  os-server-addl-vols  random  simple

Take a moment and investigate each of these workspaces.

Contents of a Workspace

Whether a workspace watch created, or pulled using linchpin fetch, they all have should some common components.

A short description of the purpose for (or use case) the workspace
A declarative file which indicates which resources should be provisioned, any inventory layout to be generated, hooks, and other configurations


The PinFile can be in YAML, JSON format. It can also be a script that returns JSON to STDOUT

No other requirements are put on a workspace. However, there can be several other files or directories. See Managing Resources for more information.