Configure your build
All configuration for CI happens through shippable.yml which should be present at the root of the repository you want to build using Shippable. The following sections describe the overall structure of the shippable.yml file, as well as detailed descriptions of every section in it.
Advanced configurations are addressed in the CI->Advanced Options section in the left menu.
Anatomy of shippable.yml
The structure of a basic shippable.yml is shown below. The sections below explore each section of the yml in greater detail.
language: node_js: # language runtime - #language version # Optional: select the node pool you want to run this job on,if different from default runtime: nodePool: <node pool name> services: - #any supported service depth: #postive integer gitConfig: - #git config 1 - #git config 2 env: - #env1=foo - #env2=bar matrix: build: pre_ci: pre_ci_boot: image_name: image_tag: pull: options: ci: - #command1 - #command2 post_ci: - #command1 - #command2 on_success: - #command1 - #command2 on_failure: - #command1 - #command2 cache: cache_dir_list: - #dir1 push: - #command1 integrations: notifications: - integrationName: type: recipients: - #recp1 - #recp2 hub: - integrationName: type: agent_only:
A brief overview of each section of the yml is provided in this table. For a detailed explanation of each tag, you can scroll to the specific section of this page.
|yml tag||default behavior without tag||Description of usage|
|language:||language gets set to ruby||Set to the language your project is written in. e.g. node_js. Read more|
|runtime:||depends on language||Set to the language runtime version(s) you want to build against. Read more|
|depth:||no default||Set to a positive integer for the repository to be shallow cloned. Read more|
|gitConfig:||no default||Set to the list of git configs that are to be set globally before the repo is cloned. Read more|
|services:||no services are available||Specify the services you need for your CI workflow, e.g. postgres, mysql, etc. Read more|
|env:||Only standard environment variables are available during your CI workflow||Set custom environment variables for your builds. , including
|matrix:||no default||Used to include or exclude only specific combination(s) from a build matrix. This is only relevant if you are triggering matrix builds, i.e. running several builds per trigger. Read more|
|build:||no default||Wrapper for several sub-sections like
|pre_ci:||no default||Used primarily if you need to use a custom image for your build or if you need to customize behavior of the default CI container. You can build your image from a Dockerfile or pull an image from a Docker registry in this section. Commands in this section run outside the CI container, so you should not include any commands required for your CI workflow here. Read more|
|pre_ci_boot:||no default||Used to override the default image used for CI with your own custom image. You can also set specific options for booting up the default CI container. Read more|
|ci:||depends on language||Include all commands for your CI workflow. Commands in this section are run inside your CI container, so any dependencies you need for your build should be installed as the first set of commands in this section. If this section is missing or empty, we call some default commands based on language, e.g.
|post_ci:||no default||Include commands that are not really a part of your core CI workflow but should be run after CI finishes. Commands in this section are run inside your CI container. Read more|
|on_success:||no default||Include commands you want to execute only if your CI workflow passes, i.e. the ci section exits with 0. Commands in this section are run inside your CI container. Read more|
|on_failure:||no default||Include commands you want to execute only if your CI workflow fails, i.e. the ci section does not exit with 0. Commands in this section are run inside your CI container. Read more|
|push:||no default||Used to push Docker image to an image registry, especially if you are pushing to Google Container Registry or Amazon ECR. Commands in this section run outside your CI container.|
|cache:||nothing is cached||Used to turn on caching. If set to true, the build directory SHIPPABLE_BUILD_DIR is cached. To cache specific folders, you can use the tag cache_dir_list. Read more|
|cache_dir_list:||if cache is set to true, default is SHIPPABLE_BUILD_DIR||Used to specify a list of folders that you want to cache between builds. Read more|
|integrations:||no default||Wrapper for several subsections like
|notifications:||Email notifications sent to last committer and author on build failure or status change to success||Used to send Slack, Hipchat, IRC notifications as well as to customize default email notification settings. This section can also be used to trigger a custom webhook or to trigger another Shippable project at various points during your CI workflow. Read more|
|hub:||no default||Include this section if you want to interact with any Docker registry to pull a private image or push an image. Read more|
|keys:||no default||Include this section if you need to use SSH or PEM keys to interact with services that are not natively supported on Shippable. Read more|