I’m pretty sure that everyone has at some point experienced this mixed feeling of disbelieve and confusion when looking at code that was written weeks/months or years ago realizing that you have no idea what the code was meant to do.

We develop and apply a lot of patterns and technics to prevent this situations from happing but keep on forgetting that someone somewhere somtime has to turn our sourcecode into a working application and deploy it somewhere, or even better: continue developing it.

This is typically the point where you realize that there is a lot of knowledge about how to build and deploy your code that is only available in the peoples heads or one someones machine who by accident has the right set of versions and tools to get everything running.

This post will describe by example some patterns on how to keep this knowledge in your repository next to your code and how to ensure that it works in (almost) every envrionment.

OSS/closed source does not matter

to transform our sourcecode into something useful No one uses gcc/javac/… directly anymore so why should someone interested in our software be hassled with working with …

The example

The example project wich I will use to demomstrate the key points of a run file is the simple and well known TodoMVC application. The backend is implemented in Java and the frontend is made with Vue.js. For easier distribution we will produce a Docker image of our application and provide Terraform based code that deploys our application to AWS.

Choice of scripting language

If there is a better tool use it

Even though it’s hard, try not to get carried away when writing your runfile. Before adding a new task ask yourself: Is there already something that does the job I want? If so, then use it.

There are obvious examples like when you try to compile some Java code don’t call javac by hand, use Gradle or if you must Maven. The same goes for C++ that nowadays noone in his (TODO) right state of mind would compile by hand but use an appropiate build tool like CMake for example.

Prepare the enviroment

Check tools and versions

Check checksums


  • run
  • lint
  • build
  • deploy
  • test
  • helpers
  • format
  • setup ide/env?

  • deploy secrets from pass/gopass/…?

  • helps new developers

  • should be executable

  • no prerequsites to run the file

  • not to big, use subcommands if possible to strucutre your file

  • ensure environment as much as possible

  • if not possible to set up environment at least check it

  • everything in current dir is ok

  • lint all the things

  • provide meaningful help (not in readme, but in code

  • use a common scripting language (platforms)

  • meaningful default

  • config files

  • allow to override possibly enviroment dependent stuff

  • use it in ci

  • self contained

  • dont misue run, use gralde, rake or whatever if suitable

  • run is only a starter