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 or node pools you want to run this job on,if different from default runtime: services: - #any supported service depth: #postive integer gitConfig: - #git config 1 - #git config 2 vote: on_success: Verified: 1 Code-Review: 2 on_failure: Verified: -1 Code-Review: -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 always: - #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 the default nodePool specified in subscription nodePools section||Set to the nodePool(s) you want to run the 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|
||Set the labels and values to be set for Gerrit projects once the build completes. 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|
|always:||no default||Include commands you want to execute irrespective of CI workflow status. 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|
If some common scripts need to be used in multiple sections of your CI job then instead of writing them in all the sections repetitively you can define a template once and use this at all the places and keep your shippable.yml file clean and small. These templates are basically yml anchors, to know more about yml anchors and how to use them please click here.
Below is a sample yml using templates defined in the shippable.yml.
templates: &template-script - echo "common-script 1" - echo "common-script 2" - echo "common-script 3" language: node_js build: pre_ci: - echo "hello world!" - *template-script ci: - echo "hello world!" - *template-script post_ci: - echo "hello world!" - *template-script on_success: - echo "hello world!" - *template-script
Defining separate templates for each of the files might be an overhead if you want to use some common templates in more than one file. You can avoid this by creating a separate
shippable.templates.yml in the root directory of your project and define all your templates in this file and use them in your yml. This helps significantly in reducing the number of lines in your yml and also makes your ymls more neat and clean.
Below is a sample yml using templates defined in a separate file.
templates1: &template-script-1 - echo "common-script 1" - echo "common-script 2" templates2: &template-script-2 - echo "common-script 3" - echo "common-script 4" templates3: &template-script-3 - echo "common-script 5" - echo "common-script 6"
language: node_js build: pre_ci: - echo "hello world!" - *template-script-1 ci: - echo "hello world!" - *template-script-2 post_ci: - echo "hello world!" - *template-script-3 on_success: - echo "hello world!" - *template-script-1
There might be some cases where you need to use some common templates in more than one projects. In this case, instead of defining these templates in each of the projects you can rather keep them in some public repo and then mention their raw file path in
externalReferences section, and then use templates defined in this file in your jobs.
Below is an example showing how you can import external templates files and use the templates defined in those files in your jobs.
- external template file
templates1: &template-script-1 - echo "common-script 1" - echo "common-script 2" templates2: &template-script-2 - echo "common-script 3" - echo "common-script 4"
- external templates file
templates3: &template-script-3 - echo "common-script 5" - echo "common-script 6" templates4: &template-script-4 - echo "common-script 7" - echo "common-script 8"
externalReferences: - https://github.com/sampleTest/sample_templates/raw/master/template1.yml - https://github.com/sampleTest/sample_templates/raw/master/template2.yml templates5: &template-script-5 - echo "common-script 1" - echo "common-script 2" templates6: &template-script-6 - echo "common-script 3" - echo "common-script 4"
language: node_js build: pre_ci: - echo "hello world!" - *template-script-1 ci: - echo "hello world!" - *template-script-2 post_ci: - echo "hello world!" - *template-script-3 - *template-script-4 on_success: - echo "hello world!" - *template-script-5 - *template-script-6
- YML templates should be given in a single line script only. Passing template in a multi-line script wont work.
ci: - | echo "This is job A" *template-script # this is not allowed echo "some more scripts"
- Currently we support
externalReferencesonly from a public repo, so please make sure your external templates file are publically accessible.