10,000 scraps of paper

I <3 the simple “legend” used here to indicate which bands are supporting each date on this tour. There’s a minor coding mistake- do you see it?-, but the technique is simple and it works so well.

Visit a professional woodshop and ask a master carpenter what her favorite tool is. You may find it’s not a tool in the traditional sense, but a “jig” she built. In woodworking, jigs are patterns or templates built to make repeatable tasks more efficient and outcomes more consistent. Building a one-off bookcase may not warrant building a jig. But, if you’re building three or four of the same bookcase, it’s likely worth building a jig first, then using that jig to build the bookcases.

Once upon a time I was a carpenter and I made…mostly sawdust. Nowadays I work for Automattic, on a small team which makes…mostly websites. While each of our projects is unique in some aspects, the vast majority share this common foundation:

1. a GitHub repo,
2. a WordPress site,
3. a DeployHQ configuration to link those platforms together,
4. a distributed team of designers, developers and producers throwing pixels and puns around on Slack.

We have a creed at Automattic which states, “…Open Source is one of the most powerful ideas of our generation.” In celebration of that belief and in appreciation of the service DeployHQ provides our team, I’m happy to share a jig our team built to bootstrap new projects.

Our jig consists of a small command line application which integrates publicly accessible API’s from these service providers:

• Pressable.com- a managed WordPress host, part of the Automattic family
• GitHub.com- a well-known collaborative software development platform
• DeployHQ.com- a tool for managing software deployments
• Slack- an instant messaging and emoji proliferation platform

Here are the basic commands for our CLI tool:

• create-development-site Creates a new development site (on Pressable).
• create-production-site Creates a new production site (on Pressable).
• create-repository Creates a new GitHub repository in our GitHub org.

create-development-site makes use of Pressable’s “site clone” feature and takes a Pressable site-id as an input. The cloned site inherits the source site’s GitHub and DeployHQ setups. It is a more minor matter, but the jig also enforces our preferred site naming conventions- eg: development sites are named with the (production) “sitename” + “-development.mystagingwebsite.com” (the *.mystagingwebsite.com is a Pressable platform default).

create-production-site makes use of Pressable’s site provisioning API. It takes two arguments: a sitename and a GitHub reponame (scoped to our team’s GitHub organization). Optional arguments include a GitHub repo, which when provided, configures DeployHQ so that merges to master are auto-deployed to the production site via SFTP.

create-repository uses the GitHub API to provision a new repository with scaffolding for things such as directory structure (eg: our repos are the “wp-content” folder of the WordPress installation), issue templates, labels and more.

Provisioning repos and sites quickly and in a consistent manner from the command line alone may have been worth building the jig. However, the real value for us is creating sites and repos in a “workflow ready” state.

So, what does our “workflow ready” state look like?

It means that we have a WordPress site provisioned on Pressable, a code repository initialized on GitHub, Travis configured for CI, a DeployHQ project configured with our deploy strategy, and event logging flowing into Slack. With our jig, we can get to that “workflow ready” state in a single command:

mark.drovdahl@penguin:~/bin/deployhq-automation$ team51 create-repository --repo-slug="shiny-new-site" --create-production-site
Checking for updates..
Already up-to-date.
Creating scaffold/shiny-new-site directory.
Copying scaffold/templates/github directory to scaffold/shiny-new-site/.github.
Copying scaffold/templates/gitignore file to scaffold/shiny-new-site/.gitignore.
Copying scaffold/templates/.travis.yml file to scaffold/shiny-new-site/.travis.yml.
Copying scaffold/templates/Makefile file to scaffold/shiny-new-site/Makefile.
Copying scaffold/templates/EXAMPLE-README.md file to scaffold/shiny-new-site/README.md.
Creating repository README.
Local setup complete! Now we need to create and populate the repository on GitHub.
Creating GitHub repository.
Successfully created repository on GitHub (a8cteam51/shiny-new-site).
Adding, committing, and pushing files to GitHub.
 6/6 [============================] 100%
Configuring GitHub repository labels.
 17/17 [============================] 100%
Logging GitHub init script completion to Slack.
GitHub repository creation and setup is complete! https://github.com/a8cteam51/shiny-new-site
Creating and configuring new Pressable site.
Creating new Pressable site
Created new Pressable site.

Waiting for Pressable site to deploy.
    6 [============================]
The Pressable site has been deployed!

Creating new project in DeployHQ
Created new project in DeployHQ.

Verifying we received a public key when we created the new DeployHQ project.
Successfully retrieved public key from new DeployHQ project.

Adding DeployHQ public key to GitHub repository's deploy keys.
Successfully added DeployHQ public key to GitHub repository.

Connecting DeployHQ project to GitHub repository.
Successfully added and configured GitHub repository in DeployHQ

Creating new DeployHQ production server for project shiny-new-site.
    6 [============================]
Created new server in DeployHQ.

Verifying we received a webhook URL for automatic deploys when we created the new DeployHQ project.
Successfully retrieved webhook URL from new DeployHQ project.

Adding DeployHQ webhook URL to GitHub repository's list of hooks.
Successfully added DeployHQ webhook URL to GitHub repository.


Deploy HQ is now set up and ready to start receiving and deploying commits!

mark.drovdahl@penguin:~/dev$ git clone git@github.com:a8cteam51/shiny-new-site
Cloning into 'shiny-new-site'...
remote: Enumerating objects: 12, done.
remote: Counting objects: 100% (12/12), done.
remote: Compressing objects: 100% (11/11), done.
remote: Total 12 (delta 0), reused 9 (delta 0), pack-reused 0
Receiving objects: 100% (12/12), 14.95 KiB | 0 bytes/s, done.

Having the DeployHQ API at the center of our jig gives us flexibility and portability. If we ever need to integrate with a different source control platform or managed WordPress host, an update to our jig adding eg: --source-control-platform and --wp-hosting-platform arguments along with a new DeployHQ project template is all it would take.

What I love about this jig is what I love about any jig, digital or physical- it makes completing an often repeated task more efficient and the outcomes more consistent.

So, what tasks do you or your team have which might benefit from building a jig? What jigs have you built?

If you’re able, share your jig on GitHub and add the “digital-jig” topic to your repo.

— Mark Drovdahl, Senior Digital Producer @ Automattic Inc