diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef1e1aa7b..619dba3f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
# Unreleased
+* Update the bundler discovery section to let the `sed` command work with modern macs (issue #1371)
+* Add config for `post` scripts on both deploy and rollback sections to run `on_error`
+* Updated the code to allow for post scripts to run on command errors
+* Added extra env config (FAILED/FAILURE_MESSAGE) for use in pre-/post-scripts
+* Updated README to include `dependencies.bundler.frozen`
+* Updated README to include sections on post scripts with on_error flag
+* Refactored README to use mostly pure markdown instead of HTML
+
# 0.42.1
* Fix unbounded memory usage in RefreshCheckRunsJob(#1436)
diff --git a/README.md b/README.md
index 6f7df0e94..c77135a55 100644
--- a/README.md
+++ b/README.md
@@ -4,73 +4,73 @@
**Shipit** is a deployment tool that makes shipping code better for everyone. It's especially great for large teams of developers and designers who work together to build and deploy GitHub repos. You can use it to:
-* add new applications to your deployment environment without having to change core configuration files repeatedly — `shipit.yml` is basically plug and play
-* control the pace of development by pushing, locking, and rolling back deploys from within Shipit
-* enforce checklists and provide monitoring right at the point of deployment.
+* Add new applications to your deployment environment without having to change core configuration files repeatedly — `shipit.yml` is basically plug and play
+* Control the pace of development by pushing, locking, and rolling back deploys from within Shipit
+* Enforce checklists and provide monitoring right at the point of deployment.
Shipit is compatible with just about anything that you can deploy using a script. It natively detects stacks using [bundler](http://bundler.io/) and [Capistrano](http://capistranorb.com/), and it has tools that make it easy to deploy to [Heroku](https://www.heroku.com/) or [RubyGems](https://rubygems.org/). At Shopify, we've used Shipit to synchronize and deploy hundreds of projects across dozens of teams, using Python, Rails, RubyGems, Java, and Go.
This guide aims to help you [set up](#installation-and-setup), [use](#using-shipit), and [understand](#reference) Shipit.
-*Shipit requires a database (MySQL, PostgreSQL or SQLite3), redis, and Ruby 2.6 or superior.*
+*Shipit requires a database (MySQL, PostgreSQL or SQLite3), Redis, and Ruby 2.6 or superior.*
* * *
-
Table of contents
+## Table of contents
-**I. INSTALLATION & SETUP**
+### I. INSTALLATION & SETUP
* [Installation](#installation)
* [Updating an existing installation](#updating-shipit)
-**II. USING SHIPIT**
+### II. USING SHIPIT
* [Adding stacks](#adding-stacks)
* [Working on stacks](#working-on-stacks)
* [Configuring stacks](#configuring-stacks)
-**III. REFERENCE**
+### III. REFERENCE
* [Format and content of shipit.yml](#configuring-shipit)
* [Script parameters](#script-parameters)
* [Configuring providers](#configuring-providers)
* [Free samples](/examples/shipit.yml)
-**IV. INTEGRATING**
+### IV. INTEGRATING
* [Registering webhooks](#integrating-webhooks)
-**V. CONTRIBUTING**
+### V. CONTRIBUTING
* [Instructions](#contributing-instructions)
* [Local development](#contributing-local-dev)
* * *
-
I. INSTALLATION & SETUP
+## I. INSTALLATION & SETUP {#installation-and-setup}
-
Installation
+### Installation
To create a new Shipit installation you can follow the [setup guide](docs/setup.md).
-
Updating an existing installation
+### Updating an existing installation {#updating-shipit}
1. If you locked the gem to a specific version in your Gemfile, update it there.
2. Update the `shipit-engine` gem with `bundle update shipit-engine`.
3. Install new migrations with `rake shipit:install:migrations db:migrate`.
-
Specific updates requiring more steps
+### Specific updates requiring more steps {#special-update}
If you are upgrading from `0.21` or older, you will have to update the configuration. Please follow [the dedicated upgrade guide](docs/updates/0.22.md)
* * *
-
II. USING SHIPIT
+## II. USING SHIPIT {#using-shipit}
The main workflows in Shipit are [adding stacks](#adding-stacks), [working on stacks](#working-on-stacks), and [configuring stacks](#configuring-stacks).
A **stack** is composed of a GitHub repository, a branch, and a deployment environment. Shipit tracks the commits made to the branch, and then displays them in the stack overview. From there, you can deploy the branch to whatever environment you've chosen (some typical environments include *production*, *staging*, *performance*, etc.).
-
Add a new stack
+### Add a new stack {#adding-stacks}
1. From the main page in Shipit, click **Add a stack**.
2. On the **Create a stack** page, enter the required information:
@@ -80,7 +80,7 @@ A **stack** is composed of a GitHub repository, a branch, and a deployment envir
* Deploy URL
3. When you're finished, click **Create stack**.
-
Work on an existing stack
+### Work on an existing stack {#working-on-stacks}
1. If you want to browse the list of available stacks, click **Show all stacks** on the main page in Shipit. If you know the name of the stack you're looking for, enter it in the search field.
2. Click the name of the stack you want to open.
@@ -93,9 +93,7 @@ A **stack** is composed of a GitHub repository, a branch, and a deployment envir
4. When you're ready to deploy an undeployed commit, click the relevant **Deploy** button on the stack's overview page.
5. From the **Deploy** page, complete the checklist, then click **Create deploy**.
-
-
-
Edit stack settings
+### Edit stack settings {#configuring-stacks}
To edit a stack's settings, open the stack in Shipit, then click the gear icon in the page header.
@@ -109,9 +107,9 @@ From a stack's **Settings** page, you can:
* * *
-
III. REFERENCE
+## III. REFERENCE {#reference}
-
Configuring shipit.yml
+### Configuring `shipit.yml` {#configuring-shipit}
The settings in the `shipit.yml` file relate to the different things you can do with Shipit:
@@ -137,36 +135,36 @@ Lastly, if you override the `app_name` configuration in your Shipit deployment,
* * *
-
Respecting bare shipit.yml files
+### Respecting bare `shipit.yml` files {#respecting-bare-files}
-Shipit will, by default, respect the "bare" shipit.yml file as a fallback option if no more specifically-named file exists (such as shipit.staging.yml).
+Shipit will, by default, respect the "bare" `shipit.yml` file as a fallback option if no more specifically-named file exists (such as `shipit.staging.yml`).
-You can configure this behavior via the attribute Shipit.respect_bare_shipit_file.
+You can configure this behaviour via the attribute `Shipit.respect_bare_shipit_file`.
-- The value false will disable this behavior and instead cause Shipit to emit an error upon deploy if Shipit cannot find a more specifically-named file.
-- Setting this attribute to any other value (**including nil**), or not setting this attribute, will cause Shipit to use the default behavior of respecting bare shipit.yml files.
+* The value `false` will disable this behaviour and instead cause Shipit to emit an error upon deploy if Shipit cannot find a more specifically-named file.
+* Setting this attribute to any other value (**including `nil`**), or not setting this attribute, will cause Shipit to use the default behaviour of respecting bare `shipit.yml` files.
-You can determine if Shipit is configured to respect bare files using Shipit.respect_bare_shipit_file?.
+You can determine if Shipit is configured to respect bare files using `Shipit.respect_bare_shipit_file?`.
* * *
-
Installing dependencies
+### Installing dependencies
-The **dependencies** step allows you to install all the packages your deploy script needs.
+The **`dependencies`** step allows you to install all the packages your deploy script needs.
-
Bundler
+#### Bundler {#bundler-support}
If your application uses Bundler, Shipit will detect it automatically and take care of the `bundle install` and prefix your commands with `bundle exec`.
By default, the following gem groups will be ignored:
- - `default`
- - `production`
- - `development`
- - `test`
- - `staging`
- - `benchmark`
- - `debug`
+ * `default`
+ * `production`
+ * `development`
+ * `test`
+ * `staging`
+ * `benchmark`
+ * `debug`
The gems you need in order to deploy should be in a different group, such as `deploy`.
@@ -181,7 +179,7 @@ dependencies:
- debug
```
-
Other dependencies
+#### Other dependencies
If your deploy script uses another tool to install dependencies, you can install them manually via `dependencies.override`:
@@ -191,7 +189,8 @@ dependencies:
- npm install
```
-**dependencies.pre** If you wish to execute commands before Shipit installs the dependencies, you can specify them here.
+
+**`dependencies.pre`** If you wish to execute commands before Shipit installs the dependencies, you can specify them here.
For example:
@@ -201,9 +200,20 @@ dependencies:
- mkdir tmp/
- cp -R /var/cache/ tmp/cache
```
-
-**dependencies.post** If you wish to execute commands after Shipit installed the dependencies, you can specify them here:
+
+**`dependencies.bundler.frozen`** If you wish to execute your bundle, for the **deploy** group, without the frozen flag:
+
+For example:
+
+```yml
+dependencies:
+ bundler:
+ frozen: false
+```
+
+
+**`dependencies.post`** If you wish to execute commands after Shipit installed the dependencies, you can specify them here:
For example:
@@ -212,14 +222,12 @@ dependencies:
post:
- cp -R tmp/cache /var/cache/
```
-
-
-
Deployment
+### Deployment
The `deploy` and `rollback` sections are the core of Shipit:
-**deploy.override** contains an array of the shell commands required to deploy the application. Shipit will try to infer it from the repository structure, but you can change the default inference.
+**`deploy.override`** contains an array of the shell commands required to deploy the application. Shipit will try to infer it from the repository structure, but you can change the default inference.
For example:
@@ -228,9 +236,9 @@ deploy:
override:
- ./script/deploy
```
-
-**deploy.pre** If you wish to execute commands before Shipit executes your deploy script, you can specify them here.
+
+**`deploy.pre`** If you wish to execute commands before Shipit executes your deploy script, you can specify them here.
For example:
@@ -239,9 +247,9 @@ deploy:
pre:
- ./script/notify_deploy_start
```
-
-**deploy.post** If you wish to execute commands after Shipit executed your deploy script, you can specify them here.
+
+**`deploy.post`** If you wish to execute commands after Shipit executed your deploy script, you can specify them here.
For example:
@@ -250,12 +258,31 @@ deploy:
post:
- ./script/notify_deploy_end
```
-
+
+
+If you would like the post script to run even on error, you can pass the following option:
+
+```yml
+deploy:
+ post:
+ - ./script/notify_deploy_end: { on_error: true }
+```
+
+Or
+
+```yml
+deploy:
+ post:
+ - ./script/notify_deploy_end:
+ on_error: true
+```
+
+This option can come in handy when you are tracking deployment externally. The default behaviour will not run the post script.
You can also accept custom environment variables defined by the user that triggers the deploy:
-**deploy.variables** contains an array of variable definitions.
+**`deploy.variables`** contains an array of variable definitions.
For example:
@@ -267,9 +294,9 @@ deploy:
title: Run database migrations on deploy
default: 1
```
-
-**deploy.variables.select** will turn the input into a `