Building a Package

At its core Escape provides abstractions to work with packages. A package is a collection of files, plus a bit of metadata to tell Escape what it can do. Based on the metadata Escape knows how to build, test, deploy, destroy and operate the unit.

Metadata doesn’t have to be written by hand, but can be compiled from an Escape plan. Let’s create a new workspace and initialise a new Escape plan using the plan init command.

mkdir workspace
cd workspace
escape plan init --name quickstart/hello-world

This should create an Escape plan in the default location escape.yml; looking a little something like this:

name: quickstart/hello-world
version: [email protected]


The `[email protected]` at the end of our version signals to Escape that it should auto-version from there. Versioning is covered in depth here.

We can use the plan preview command to make sure that our plan compiles and to have a look at what Escape makes of it:

escape plan preview

That’s looking tidy. We don’t have to run the escape plan preview command explicitly for any of our build steps as Escape will do it automatically, but it can be a handy validation step). NB. If you’re getting an “Unauthorized” error here, you need to configure your Inventory.

We now have enough to create an empty package, but usually we do want to put something inside it. Our Escape plan includes a reference to, but the file doesnae exist! Let’s create it:

echo "Thanks for reading" >

We’ve only told Escape to include, but we can also add globbing patterns and whole directories. In anyway, we are ready to create our first package!

escape run release

Which outputs:

Release: Releasing quickstart/hello-world-v0.0.0
  Build: ✔️ Completed build
  Test: ✔️ Tests passed.
  Destroy: ✔️ Destruction complete
  Deploy: ✔️ Successfully deployed hello-world-v0.0.0 with deployment name quickstart/hello-world in the dev environment.
  Smoke tests: ✔️ Smoke tests passed.
  Destroy: ✔️ Destruction complete
  Package: ✔️ Packaged quickstart/hello-world-v0.0.0 at /home/user/workspace/.escape/target/hello-world-v0.0.0.tgz
  Push: ✔️ Push successful.
Release: ✔️ Successfully released quickstart/hello-world-v0.0.0

Each time we release a package, Escape will execute all the different steps, even if they have not yet been defined. After these steps have been executed, Escape will add all the files in includesto our package and upload it with our compiled Escape plan to the Inventory. Even though we haven’t told Escape how to build or deploy anything we still get a valid package.

We can keep running escape run release and see the version number increase for each successful push.

We’ve finished packaging. Our file includes are now packaged up and are now available in the Inventory. We ain’t done yet though, we haven’t defined how we want to build and deploy our package. Keep on reading to find out how we can do this: