Shopify / shipit-engine

Shipit - Documentation **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 — 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 and Capistrano, and it has tools that make it easy to deploy to Heroku or RubyGems. 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, use, and understand Shipit. *Shipit requires a database (MySQL, PostgreSQL or SQLite3), redis, and Ruby 2.6 or superior.* • * * Table of contents **I. INSTALLATION & SETUP** • Installation • Updating an existing installation **II. USING SHIPIT** • Adding stacks • Working on stacks • Configuring stacks **III. REFERENCE** • Format and content of shipit.yml • Script parameters • Configuring providers • Free samples **IV. INTEGRATING** • Registering webhooks **V. CONTRIBUTING** • Instructions • Local development • * * I. INSTALLATION & SETUP Installation To create a new Shipit installation you can follow the setup guide. Updating an existing installation • If you locked the gem to a specific version in your Gemfile, update it there. • Update the gem with . • Install new migrations with . Specific updates requiring more steps If you are upgrading from or older, you will have to update the configuration. Please follow the dedicated upgrade guide • * * II. USING SHIPIT The main workflows in Shipit are adding stacks, working on stacks, and 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 • From the main page in Shipit, click **Add a stack**. • On the **Create a stack** page, enter the required information: • Repo • Branch • Environment • Deploy URL • When you're finished, click **Create stack**. Work on an existing stack • 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. • Click the name of the stack you want to open. • From a stack's overview page, you can: • review previous deploys • deploy any undeployed commits by clicking **Deploy** • rollback to an earlier build by clicking **Rollback to this deploy** • adjust the stack's settings by clicking the gear icon in the page header • perform any custom tasks that are defined in the file • When you're ready to deploy an undeployed commit, click the relevant **Deploy** button on the stack's overview page. • From the **Deploy** page, complete the checklist, then click **Create deploy**. Edit stack settings To edit a stack's settings, open the stack in Shipit, then click the gear icon in the page header. From a stack's **Settings** page, you can: • change the deploy URL • enable and disable continuous deployment • lock and unlock deploys through Shipit • resynchronize the stack with GitHub • delete the stack from Shipit • * * III. REFERENCE Configuring shipit.yml The settings in the file relate to the different things you can do with Shipit: • Installing Dependencies ( ) • Deployment ( , , ) • Environment ( , , ) • CI ( , , ) • Merge Queue ( , , , ) • Custom Tasks ( ) • Custom links ( ) • Review Process ( , , ) • Inherit From( ) All the settings in are optional. Most applications can be deployed from Shipit without any configuration. Also, if your repository is deployed different ways depending on the environment, you can have an alternative by including the environment name. For example for a stack like: , will have priority over . In order to reduce duplication across different environment specific files, you can specify an key in your relevant file. This key expects a string of the file name to inherit from. If this key is specified, a deep-merge will be performed on the file therein, overwriting any duplicated values from the parent. See Inherit From( ) for example. Lastly, if you override the configuration in your Shipit deployment, and will work. • * * Respecting bare shipit.yml 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 ). You can configure this behavior 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. You can determine if Shipit is configured to respect bare files using Shipit.respect_bare_shipit_file? . • * * Installing dependencies The ** dependencies ** step allows you to install all the packages your deploy script needs. Bundler If your application uses Bundler, Shipit will detect it automatically and take care of the and prefix your commands with . By default, the following gem groups will be ignored: • - • - • - • The gems you need in order to deploy should be in a different group, such as . For example: Other dependencies If your deploy script u…