{"id":13647581,"url":"https://github.com/Shopify/shipit-engine","last_synced_at":"2025-04-22T02:32:11.420Z","repository":{"id":14515086,"uuid":"17228890","full_name":"Shopify/shipit-engine","owner":"Shopify","description":"Deployment coordination","archived":false,"fork":false,"pushed_at":"2025-04-16T22:31:37.000Z","size":6085,"stargazers_count":1436,"open_issues_count":70,"forks_count":148,"subscribers_count":493,"default_branch":"main","last_synced_at":"2025-04-17T10:29:20.348Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://shopify.engineering/introducing-shipit","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"sensu/sensu-build","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shopify.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-02-26T22:59:57.000Z","updated_at":"2025-04-16T11:47:09.000Z","dependencies_parsed_at":"2024-01-13T20:57:30.100Z","dependency_job_id":"d844b4d1-3227-4242-be19-d9b76ed6565c","html_url":"https://github.com/Shopify/shipit-engine","commit_stats":null,"previous_names":[],"tags_count":81,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshipit-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshipit-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshipit-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shopify%2Fshipit-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shopify","download_url":"https://codeload.github.com/Shopify/shipit-engine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249396512,"owners_count":21264306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:03:39.594Z","updated_at":"2025-04-22T02:32:10.996Z","avatar_url":"https://github.com/Shopify.png","language":"Ruby","readme":"# Shipit - Documentation\n[![Build Status](https://travis-ci.org/Shopify/shipit-engine.svg?branch=master)](https://travis-ci.org/Shopify/shipit-engine)\n[![Gem Version](https://badge.fury.io/rb/shipit-engine.svg)](http://badge.fury.io/rb/shipit-engine)\n\n**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:\n\n* add new applications to your deployment environment without having to change core configuration files repeatedly \u0026mdash; `shipit.yml` is basically plug and play\n* control the pace of development by pushing, locking, and rolling back deploys from within Shipit\n* enforce checklists and provide monitoring right at the point of deployment.\n\nShipit 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.\n\nThis guide aims to help you [set up](#installation-and-setup), [use](#using-shipit), and [understand](#reference) Shipit.\n\n*Shipit requires a database (MySQL, PostgreSQL or SQLite3), redis, and Ruby 2.6 or superior.*\n\n* * *\n\u003ch2 id=\"toc\"\u003eTable of contents\u003c/h2\u003e\n\n**I. INSTALLATION \u0026 SETUP**\n\n* [Installation](#installation)\n* [Updating an existing installation](#updating-shipit)\n\n**II. USING SHIPIT**\n\n* [Adding stacks](#adding-stacks)\n* [Working on stacks](#working-on-stacks)\n* [Configuring stacks](#configuring-stacks)\n\n**III. REFERENCE**\n\n* [Format and content of shipit.yml](#configuring-shipit)\n* [Script parameters](#script-parameters)\n* [Configuring providers](#configuring-providers)\n* [Free samples](/examples/shipit.yml)\n\n**IV. INTEGRATING**\n\n* [Registering webhooks](#integrating-webhooks)\n\n**V. CONTRIBUTING**\n\n* [Instructions](#contributing-instructions)\n* [Local development](#contributing-local-dev)\n\n* * *\n\n\u003ch2 id=\"installation-and-setup\"\u003eI. INSTALLATION \u0026 SETUP\u003c/h2\u003e\n\n\u003ch3 id=\"installation\"\u003eInstallation\u003c/h3\u003e\n\nTo create a new Shipit installation you can follow the [setup guide](docs/setup.md).\n\n\u003ch3 id=\"updating-shipit\"\u003eUpdating an existing installation\u003c/h3\u003e\n\n1. If you locked the gem to a specific version in your Gemfile, update it there.\n2. Update the `shipit-engine` gem with `bundle update shipit-engine`.\n3. Install new migrations with `rake shipit:install:migrations db:migrate`.\n\n\u003ch3 id=\"special-update\"\u003eSpecific updates requiring more steps\u003c/h3\u003e\n\nIf 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)\n\n* * *\n\n\u003ch2 id=\"using-shipit\"\u003eII. USING SHIPIT\u003c/h2\u003e\n\nThe main workflows in Shipit are [adding stacks](#adding-stacks), [working on stacks](#working-on-stacks), and [configuring stacks](#configuring-stacks).\n\nA **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.).\n\n\u003ch3 id=\"adding-stacks\"\u003eAdd a new stack\u003c/h3\u003e\n\n1. From the main page in Shipit, click **Add a stack**.\n2. On the **Create a stack** page, enter the required information:\n    * Repo\n    * Branch\n    * Environment\n    * Deploy URL\n3. When you're finished, click **Create stack**.\n\n\u003ch3 id=\"working-on-stacks\"\u003eWork on an existing stack\u003c/h3\u003e\n\n1. 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.\n2. Click the name of the stack you want to open.\n3. From a stack's overview page, you can:\n    * review previous deploys\n    * deploy any undeployed commits by clicking **Deploy**\n    * rollback to an earlier build by clicking **Rollback to this deploy**\n    * adjust the stack's settings by clicking the gear icon in the page header\n    * perform any custom tasks that are defined in the `shipit.yml` file\n4. When you're ready to deploy an undeployed commit, click the relevant **Deploy** button on the stack's overview page.\n5. From the **Deploy** page, complete the checklist, then click **Create deploy**.\n\n\n\n\u003ch3 id=\"configuring-stacks\"\u003eEdit stack settings\u003c/h3\u003e\n\nTo edit a stack's settings, open the stack in Shipit, then click the gear icon in the page header.\n\nFrom a stack's **Settings** page, you can:\n\n* change the deploy URL\n* enable and disable continuous deployment\n* lock and unlock deploys through Shipit\n* resynchronize the stack with GitHub\n* delete the stack from Shipit\n\n* * *\n\n\u003ch2 id=\"reference\"\u003eIII. REFERENCE\u003c/h2\u003e\n\n\u003ch3 id=\"configuring-shipit\"\u003eConfiguring \u003ccode\u003eshipit.yml\u003c/code\u003e\u003c/h3\u003e\n\nThe settings in the `shipit.yml` file relate to the different things you can do with Shipit:\n\n* [Installing Dependencies](#installing-dependencies) (`dependencies`)\n* [Deployment](#deployment) (`deploy`, `rollback`, `fetch`)\n* [Environment](#environment) (`machine.environment`, `machine.directory`, `machine.cleanup`)\n* [CI](#ci) (`ci.require`, `ci.hide`, `ci.allow_failures`)\n* [Merge Queue](#merge-queue) (`merge.revalidate_after`, `merge.require`, `merge.ignore`, `merge.max_divergence`)\n* [Custom Tasks](#custom-tasks) (`tasks`)\n* [Custom links](#custom-links) (`links`)\n* [Review Process](#review-process) (`review.checklist`, `review.monitoring`, `review.checks`)\n\nAll the settings in `shipit.yml` are optional. Most applications can be deployed from Shipit without any configuration.\n\nAlso, if your repository is deployed different ways depending on the environment, you can have an alternative `shipit.yml` by including the environment name.\n\nFor example for a stack like: `my-org/my-repo/staging`, `shipit.staging.yml` will have priority over `shipit.yml`.\n\nLastly, if you override the `app_name` configuration in your Shipit deployment, `yourapp.yml` and `yourapp.staging.yml` will work.\n\n* * *\n\n\u003ch3 id=\"respecting-bare-files\"\u003eRespecting bare \u003ccode\u003eshipit.yml\u003c/code\u003e files\u003c/h3\u003e\n\nShipit will, by default, respect the \"bare\" \u003ccode\u003eshipit.yml\u003c/code\u003e file as a fallback option if no more specifically-named file exists (such as \u003ccode\u003eshipit.staging.yml\u003c/code\u003e).\n\nYou can configure this behavior via the attribute \u003ccode\u003eShipit.respect_bare_shipit_file\u003c/code\u003e.\n\n- The value \u003ccode\u003efalse\u003c/code\u003e will disable this behavior and instead cause Shipit to emit an error upon deploy if Shipit cannot find a more specifically-named file.\n- Setting this attribute to any other value (**including \u003ccode\u003enil\u003c/code\u003e**), or not setting this attribute, will cause Shipit to use the default behavior of respecting bare \u003ccode\u003eshipit.yml\u003c/code\u003e files.\n\nYou can determine if Shipit is configured to respect bare files using \u003ccode\u003eShipit.respect_bare_shipit_file?\u003c/code\u003e.\n\n* * *\n\n\u003ch3 id=\"installing-dependencies\"\u003eInstalling dependencies\u003c/h3\u003e\n\nThe **\u003ccode\u003edependencies\u003c/code\u003e** step allows you to install all the packages your deploy script needs.\n\n\u003ch4 id=\"bundler-support\"\u003eBundler\u003c/h4\u003e\n\nIf your application uses Bundler, Shipit will detect it automatically and take care of the `bundle install` and prefix your commands with `bundle exec`.\n\nBy default, the following gem groups will be ignored:\n\n  - `default`\n  - `production`\n  - `development`\n  - `test`\n  - `staging`\n  - `benchmark`\n  - `debug`\n\nThe gems you need in order to deploy should be in a different group, such as `deploy`.\n\nFor example:\n\n```yml\ndependencies:\n  bundler:\n    without:\n      - development\n      - test\n      - debug\n```\n\n\u003ch4 id=\"other-dependencies\"\u003eOther dependencies\u003c/h4\u003e\n\nIf your deploy script uses another tool to install dependencies, you can install them manually via `dependencies.override`:\n\n```yml\ndependencies:\n  override:\n    - npm install\n```\n\n**\u003ccode\u003edependencies.pre\u003c/code\u003e** If you wish to execute commands before Shipit installs the dependencies, you can specify them here.\n\nFor example:\n\n```yml\ndependencies:\n  pre:\n    - mkdir tmp/\n    - cp -R /var/cache/ tmp/cache\n```\n\u003cbr\u003e\n\n**\u003ccode\u003edependencies.post\u003c/code\u003e** If you wish to execute commands after Shipit installed the dependencies, you can specify them here:\n\nFor example:\n\n```yml\ndependencies:\n  post:\n    - cp -R tmp/cache /var/cache/\n```\n\u003cbr\u003e\n\n\n\u003ch3 id=\"deployment\"\u003eDeployment\u003c/h3\u003e\n\nThe `deploy` and `rollback` sections are the core of Shipit:\n\n**\u003ccode\u003edeploy.override\u003c/code\u003e** 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.\n\nFor example:\n\n```yml\ndeploy:\n  override:\n    - ./script/deploy\n```\n\u003cbr\u003e\n\n**\u003ccode\u003edeploy.pre\u003c/code\u003e** If you wish to execute commands before Shipit executes your deploy script, you can specify them here.\n\nFor example:\n\n```yml\ndeploy:\n  pre:\n    - ./script/notify_deploy_start\n```\n\u003cbr\u003e\n\n**\u003ccode\u003edeploy.post\u003c/code\u003e** If you wish to execute commands after Shipit executed your deploy script, you can specify them here.\n\nFor example:\n\n```yml\ndeploy:\n  post:\n    - ./script/notify_deploy_end\n```\n\u003cbr\u003e\n\n\nYou can also accept custom environment variables defined by the user that triggers the deploy:\n\n**\u003ccode\u003edeploy.variables\u003c/code\u003e** contains an array of variable definitions.\n\nFor example:\n\n```yaml\ndeploy:\n  variables:\n    -\n      name: RUN_MIGRATIONS\n      title: Run database migrations on deploy\n      default: 1\n```\n\u003cbr\u003e\n\n**\u003ccode\u003edeploy.variables.select\u003c/code\u003e** will turn the input into a `\u003cselect\u003e` of values.\n\nFor example:\n\n```yaml\ndeploy:\n  variables:\n    -\n      name: REGION\n      title: Run a deploy in a given region\n      select:\n        - east\n        - west\n        - north\n```\n\u003cbr\u003e\n\n**\u003ccode\u003edeploy.max_commits\u003c/code\u003e** defines the maximum number of commits that should be shipped per deploy. Defaults to `8` if no value is provided.\n\nTo disable this limit, you can use use an explicit null value: `max_commits: null`. Continuous Delivery will then deploy any number of commits.\n\nHuman users will be warned that they are not respecting the recommendation, but allowed to continue.\nHowever continuous delivery will respect this limit. If there is no deployable commits in this range, a human intervention will be required.\n\nFor example:\n\n```yaml\ndeploy:\n  max_commits: 5\n```\n\u003cbr\u003e\n\n**\u003ccode\u003edeploy.interval\u003c/code\u003e** defines the interval between the end of a deploy and the next deploy, when continuous delivery is enabled. You can use s, m, h, d as units for seconds, minutes, hours, and days. Defaults to 0, which means a new deploy will start as soon as the current one finishes.\n\nFor example, this will wait 5 minutes after the end of a deploy before starting a new one:\n\n```yaml\ndeploy:\n  interval: 5m\n```\n\n**\u003ccode\u003edeploy.retries\u003c/code\u003e** enables retries for a stack, and defines the maximum amount of times that Shipit will retry a deploy that finished with a `failed`, `error` or `timedout` status.\n\nFor example, this will retry a deploy twice if it fails.\n\n```yaml\ndeploy:\n  retries: 2\n```\n\n**\u003ccode\u003erollback.override\u003c/code\u003e** contains an array of the shell commands required to rollback the application to a previous state. Shipit will try to infer it from the repository structure, but you can change the default inference. This key defaults to `disabled` unless Capistrano is detected.\n\nFor example:\n\n```yml\nrollback:\n  override:\n    - ./script/rollback\n```\n\u003cbr\u003e\n\n**\u003ccode\u003erollback.pre\u003c/code\u003e** If you wish to execute commands before Shipit executes your rollback script, you can specify them here:\n\nFor example:\n\n```yml\nrollback:\n  pre:\n    - ./script/notify_rollback_start\n```\n\u003cbr\u003e\n\n**\u003ccode\u003erollback.post\u003c/code\u003e** If you wish to execute commands after Shipit executed your rollback script, you can specify them here:\n\nFor example:\n\n```yml\nrollback:\n  post:\n    - ./script/notify_rollback_end\n```\n\u003cbr\u003e\n\n\n**\u003ccode\u003efetch\u003c/code\u003e** contains an array of the shell commands that Shipit executes to check the revision of the currently-deployed version. This key defaults to `disabled`.\n\nFor example:\n```yml\nfetch:\n  curl --silent https://app.example.com/services/ping/version\n```\n\n**Note:** Currently, deployments in emergency mode are configured to occur concurrently via [the `build_deploy` method](https://github.com/Shopify/shipit-engine/blob/main/app/models/shipit/stack.rb),\nwhose `allow_concurrency` keyword argument defaults to `force`, where `force` is true when emergency mode is enabled. \nIf you'd like to separate these two from one another, override this method as desired in your service.\n\n\u003ch3 id=\"kubernetes\"\u003eKubernetes\u003c/h3\u003e\n\n**\u003ccode\u003ekubernetes\u003c/code\u003e** allows to specify a Kubernetes namespace and context to deploy to.\n\nFor example:\n```yml\nkubernetes:\n  namespace: my-app-production\n  context: tier4\n```\n\n**\u003ccode\u003ekubernetes.template_dir\u003c/code\u003e** allows to specify a Kubernetes template directory. It defaults to `./config/deploy/$ENVIRONMENT`\n\n\u003ch3 id=\"environment\"\u003eEnvironment\u003c/h3\u003e\n\n**\u003ccode\u003emachine.environment\u003c/code\u003e** contains the extra environment variables that you want to provide during task execution.\n\nFor example:\n```yml\nmachine:\n  environment:\n    key: val # things added as environment variables\n```\n\n\u003ch3 id=\"directory\"\u003eDirectory\u003c/h3\u003e\n\n**\u003ccode\u003emachine.directory\u003c/code\u003e** specifies a subfolder in which to execute all tasks. Useful for repositories containing multiple applications or if you don't want your deploy scripts to be located at the root.\n\nFor example:\n```yml\nmachine:\n  directory: scripts/deploy/\n```\n\n\u003ch3 id=\"cleanup\"\u003eCleanup\u003c/h3\u003e\n\n**\u003ccode\u003emachine.cleanup\u003c/code\u003e** specifies whether or not the deploy working directory should be cleaned up once the deploy completed. Defaults to `true`, but can be useful to disable temporarily to investigate bugs.\n\nFor example:\n```yml\nmachine:\n  cleanup: false\n```\n\n\u003ch3 id=\"ci\"\u003eCI\u003c/h3\u003e\n\n**\u003ccode\u003eci.require\u003c/code\u003e** contains an array of the [statuses context](https://docs.github.com/en/rest/reference/commits#commit-statuses) you want Shipit to disallow deploys if any of them is missing on the commit being deployed.\n\nFor example:\n```yml\nci:\n  require:\n    - ci/circleci\n```\n\n**\u003ccode\u003eci.hide\u003c/code\u003e** contains an array of the [statuses context](https://docs.github.com/en/rest/reference/commits#commit-statuses) you want Shipit to ignore.\n\nFor example:\n```yml\nci:\n  hide:\n    - ci/circleci\n```\n\n**\u003ccode\u003eci.allow_failures\u003c/code\u003e** contains an array of the [statuses context](https://docs.github.com/en/rest/reference/commits#commit-statuses) you want to be visible but not to required for deploy.\n\nFor example:\n```yml\nci:\n  allow_failures:\n    - ci/circleci\n```\n\n**\u003ccode\u003eci.blocking\u003c/code\u003e** contains an array of the [statuses context](https://docs.github.com/en/rest/reference/commits#commit-statuses) you want to disallow deploys if any of them is missing or failing on any of the commits being deployed.\n\nFor example:\n```yml\nci:\n  blocking:\n    - soc/compliance\n```\n\n\u003ch3 id=\"merge-queue\"\u003eMerge Queue\u003c/h3\u003e\n\nThe merge queue allows developers to register pull requests which will be merged by Shipit once the stack is clear (no lock, no failing CI, no backlog). It can be enabled on a per stack basis via the settings page.\n\nIt can be customized via several `shipit.yml` properties:\n\n**\u003ccode\u003emerge.revalidate_after\u003c/code\u003e** a duration after which pull requests that couldn't be merged are rejected from the queue. Defaults to unlimited.\n\nFor example:\n```yml\nmerge:\n  revalidate_after: 12m30s\n```\n\n**\u003ccode\u003emerge.require\u003c/code\u003e** contains an array of the [statuses context](https://docs.github.com/en/rest/reference/commits#commit-statuses) that you want Shipit to consider as failing if they aren't present on the pull request. Defaults to `ci.require` if present, or empty otherwise.\n\nFor example:\n```yml\nmerge:\n  require:\n    - continuous-integration/travis-ci/push\n```\n\n**\u003ccode\u003emerge.ignore\u003c/code\u003e** contains an array of the [statuses context](https://docs.github.com/en/rest/reference/commits#commit-statuses) that you want Shipit not to consider when merging pull requests. Defaults to the union of `ci.allow_failures` and `ci.hide` if any is present or empty otherwise.\n\nFor example:\n```yml\nmerge:\n  ignore:\n    - codeclimate\n```\n\n**\u003ccode\u003emerge.method\u003c/code\u003e** the [merge method](https://docs.github.com/en/rest/reference/pulls#merge-a-pull-request--parameters) to use for this stack. If it's not set the default merge method will be used. Can be either `merge`, `squash` or `rebase`.\n\nFor example:\n```yml\nmerge:\n  method: squash\n```\n\n**\u003ccode\u003emerge.max_divergence.commits\u003c/code\u003e** the maximum number of commits a pull request can be behind its merge base, after which pull requests are rejected from the merge queue.\n\nFor example:\n```yml\nmerge:\n  max_divergence:\n    commits: 50\n```\n\n**\u003ccode\u003emerge.max_divergence.age\u003c/code\u003e** a duration after the commit date of the merge base, after which pull requests will be rejected from the merge queue.\n\nFor example:\n```yml\nmerge:\n  max_divergence:\n    age: 72h\n```\n\n\u003ch3 id=\"custom-tasks\"\u003eCustom tasks\u003c/h3\u003e\n\nYou can create custom tasks that users execute directly from a stack's overview page in Shipit. To create a new custom task, specify its parameters in the `tasks` section of the `shipit.yml` file. For example:\n\n**\u003ccode\u003etasks.restart\u003c/code\u003e** restarts the application.\n\n```yml\ntasks:\n  restart:\n    action: \"Restart Application\"\n    description: \"Sometimes needed if you want the application to restart but don't want to ship any new code.\"\n    steps:\n      - ssh deploy@myserver.example.com 'touch myapp/restart.txt'\n```\n\nBy default, custom tasks are not allowed to be triggered while a deploy is running. But if it's safe for that specific task, you can change that behavior with the `allow_concurrency` attribute:\n\n```yml\ntasks:\n  flush_cache:\n    action: \"Flush Cache\"\n    steps:\n      - ssh deploy@myserver.example.com 'myapp/flush_cache.sh'\n    allow_concurrency: true\n```\n\nTasks like deploys can prompt for user defined environment variables:\n\n```yml\ntasks:\n  restart:\n    action: \"Restart Application\"\n    description: \"Sometimes needed if you want the application to restart but don't want to ship any new code.\"\n    steps:\n      - ssh deploy@myserver.example.com 'touch myapp/restart.txt'\n    variables:\n      -\n        name: FORCE\n        title: Restart server without waiting for in-flight requests to complete (Dangerous).\n        default: 0\n```\n\nYou can also make these variables appear in the task title:\n\n```yml\ntasks:\n  failover:\n    action: \"Failover a pod\"\n    title: \"Failover Pod %{POD_ID}\"\n    steps:\n      - script/failover $POD_ID\n    variables:\n      - name: POD_ID\n```\n\n\u003ch3 id=\"custom-links\"\u003eCustom Links\u003c/h3\u003e\n\nYou can add custom links to the header of a stacks overview page in Shipit. To create a new custom link, specify its parameters in the links section of the shipit.yml file. The link title is a humanized version of the key. For example:\n\n**\u003ccode\u003elinks.monitoring_dashboard\u003c/code\u003e** creates a link in the header of of the page titled \"Monitoring dashboard\"\n\nYou can specify multiple custom links:\n\n```yml\nlinks:\n  monitoring_dashboard: https://example.com/monitoring.html\n  other_link: https://example.com/something_else.html\n```\n\n\u003ch3 id=\"review-process\"\u003eReview process\u003c/h3\u003e\n\nYou can display review elements, such as monitoring data or a pre-deployment checklist, on the deployment page in Shipit:\n\n**\u003ccode\u003ereview.checklist\u003c/code\u003e** contains a pre-deploy checklist that appears on the deployment page in Shipit, with each item in the checklist as a separate string in the array. It can contain `strong` and `a` HTML tags. Users cannot deploy from Shipit until they have checked each item in the checklist.\n\nFor example:\n\n```yml\nreview:\n  checklist:\n    - \u003e\n      Do you know if it is safe to revert the code being shipped? What happens if we need to undo this deploy?\n    - Has the Docs team been notified of any major changes to the app?\n    - Is the app stable right now?\n```\n\u003cbr\u003e\n\n**\u003ccode\u003ereview.monitoring\u003c/code\u003e** contains a list of inclusions that appear on the deployment page in Shipit. Inclusions can either be images or iframes.\n\nFor example:\n\n```yml\nreview:\n  monitoring:\n    - image: https://example.com/monitoring.png\n    - iframe: https://example.com/monitoring.html\n```\n\n\u003cbr\u003e\n\n**\u003ccode\u003ereview.checks\u003c/code\u003e** contains a list of commands that will be executed during the pre-deploy review step.\nTheir output appears on the deployment page in Shipit, and if continuous delivery is enabled, deploys will only be triggered if those commands are successful.\n\nFor example:\n\n```yml\nreview:\n  checks:\n    - bundle exec rake db:migrate:status\n```\n\n\u003ch3 id=\"shell-commands-timeout\"\u003eShell commands timeout\u003c/h3\u003e\n\nAll the shell commands can take an optional `timeout` parameter. This is the value in seconds that a command can be inactive before Shipit will terminate the task.\n\n```yml\ndeploy:\n  override:\n    - ./script/deploy:\n        timeout: 30\n  post:\n    - ./script/notify_deploy_end: { timeout: 15 }\nreview:\n  checks:\n    - bundle exec rake db:migrate:status:\n        timeout: 60\n```\n\nSee also `commands_inactivity_timeout` in `secrets.yml` for a global timeout setting.\n\n\n***\n\n\u003ch2 id=\"script-parameters\"\u003eScript parameters\u003c/h2\u003e\n\nYour deploy scripts have access to the following environment variables:\n\n* `SHIPIT`: Set to `1` to allow your script to know it's executed by Shipit\n* `SHIPIT_LINK`: URL to the task output, useful to broadcast it in an IRC channel\n* `SHIPIT_USER`: Full name of the user that triggered the deploy/task\n* `GITHUB_REPO_NAME`: Name of the GitHub repository being used for the current deploy/task.\n* `GITHUB_REPO_OWNER`: The GitHub username of the repository owner for the current deploy/task.\n* `EMAIL`: Email of the user that triggered the deploy/task (if available)\n* `ENVIRONMENT`: The stack environment (e.g `production` / `staging`)\n* `BRANCH`: The stack branch (e.g `main`)\n* `LAST_DEPLOYED_SHA`: The git SHA of the last deployed commit\n* `DIFF_LINK`: URL to the diff on GitHub.\n* `TASK_ID`: ID of the task that is running\n* All the content of the `secrets.yml` `env` key\n* All the content of the `shipit.yml` `machine.environment` key\n\nThese variables are accessible only during deploys and rollback:\n\n* `REVISION`: the git SHA of the revision that must be deployed in production\n* `SHA`: alias for REVISION\n\n\u003ch2 id=\"configuring-providers\"\u003eConfiguring providers\u003c/h2\u003e\n\n### Heroku\n\nTo use Heroku integration (`lib/snippets/push-to-heroku`), make sure that the environment has [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) available.\n\n### Kubernetes\n\nFor Kubernetes, you have to provision Shipit environment with the following tools:\n\n* `kubectl`\n* `kubernetes-deploy` [gem](https://github.com/Shopify/kubernetes-deploy)\n\n\u003ch2 id=\"integrating\"\u003eIV. INTEGRATING\u003c/h2\u003e\n\n\u003ch3 id=\"integrating-webhooks\"\u003eRegistering webhooks\u003c/h3\u003e\n\nShipit handles several webhook types by default, listed in `Shipit::Wehbooks::DEFAULT_HANDLERS`, in order to implement default behaviours. Extra handler blocks can be registered via `Shipit::Webhooks.register_handler`. Valid handlers need only implement the `call` method - meaning any object which implements `call` - blocks, procs, or lambdas are valid. The webhooks controller will pass a `params` argument to the handler. Some examples:\n\n\n\u003ch4\u003eRegistering a Plain old Ruby Object as a handler\u003c/h4\u003e\n\n```ruby\nclass PullRequestHandler\n  def call(params)\n    # do something with pull request webhook events\n  end\nend\n\nShipit::Webhooks.register_handler('pull_request', PullRequestHandler)\n```\n\n\u003ch4\u003eRegistering a Block as a handler\u003c/h4\u003e\n\n```ruby\nShipit::Webhooks.register_handler('pull_request') do |params|\n  # do something with pull request webhook events\nend\n```\n\nMultiple handler blocks can be registered. If any raise errors, execution will be halted and the request will be reported failed to github.\n\n\u003ch2 id=\"contributing\"\u003eV. CONTRIBUTING\u003c/h2\u003e\n\n\u003ch3 id=\"contributing-instructions\"\u003eInstructions\u003c/h3\u003e\n\n1. Fork it ( https://github.com/shopify/shipit-engine/fork )\n1. Create your feature branch (git checkout -b my-new-feature)\n1. Commit your changes (git commit -am 'Add some feature')\n1. Push to the branch (git push origin my-new-feature)\n1. Create a new Pull Request\n\n\u003ch3 id=\"contributing-local-dev\"\u003eLocal development\u003c/h3\u003e\n\nThis repository has a [test/dummy](/test/dummy) app in it which can be used for local development without having to setup a new rails application.\n\nRun `./bin/bootstrap` in order to bootstrap the dummy application. The bootstrap script is going to:\n\n- Copy `config/secrets.development.example.yml` to `config/secrets.development.yml`;\n- Make sure all dependencies are installed;\n- Create and seed database (recreate database if already available);\n\nRun `./test/dummy/bin/rails server` to run the rails dummy application.\n\nSet the environment variable `SHIPIT_DISABLE_AUTH=1` in order to disable authentication.\n\nIf you need to test caching behaviour in the dummy application, use `bin/rails dev:cache`.\n","funding_links":[],"categories":["Configuration Management","Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShopify%2Fshipit-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShopify%2Fshipit-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShopify%2Fshipit-engine/lists"}