Working with environment variables
You can customize your build workflow by using environment variables that are set at runtime and available during your build. For example, you can run a different set of tests depending on which branch the build is running for, as shown below.
build: ci: - if [ "$BRANCH" == "master" ]; then ./runAllTests; fi - if [ "$BRANCH" == "dev" ] && [ "$IS_PULL_REQUEST" == true ]; then ./runSubsetTests; fi
The example above uses our standard environment variables to determine which tests should be run during a build.
We support the following kinds of environment variables.
Standard environment variables are pre-populated by us and are automatically available to you during every build. For example, you can use the $BRANCH variable to call different scripts depending on which branch is being built as shown above.
User defined environment variables are your custom variables which you can define in the
env section of your shippable.yml. You can define one or multiple variables, as well as encrypt variables to store sensitive information. For example, the snippet below makes the variables $TEST and $FOO available during your build workflow.
env: - TEST=1 FOO=foo
More on these types of variables:
Standard variables are pre-populated by Shippable and are available to you for every build. A complete list is provided below.
|BASE_BRANCH||Name of the target branch into which the pull request changes will be merged.|
|BRANCH||Name of branch being built.|
|BUILD_NUMBER||Build number for current build.|
|BUILD_URL||Direct URL link to the build output.|
|CACHE_DIR||If cache is true in the build section of shippable.yml, then true. Otherwise false.|
|COMMIT||Commit id that is being built and tested.|
|COMMITTER||Name of the last committer.|
|COMMIT_MESSAGE||Commit message specified in the commit.|
|COMPARE_URL||A link to GitHub/Bitbucket's comparision view for the push.|
|HEAD_BRANCH||This is only set for pull requests and is the name of the branch the pull request was opened from.|
|IS_PULL_REQUEST||Set to true if the job is a pull request. If not, this will be set to false.|
|IS_FORK||Set to true if the job belongs to a forked project. If not, this will be set to false.|
|JOB_ID||ID of job in Shippable.|
|JOB_NUMBER, SHIPPABLE_JOB_NUMBER, SHIPPABLE_JOB_ID||All three variables are the same & represent the number of the job in Shippable.|
|LAST_AUTHOR||Name of the last author.|
|LAST_SUCCESSFUL_BUILD_TIMESTAMP||Timestamp of the last successful build in seconds. This will be set to false for the first build or for the build with no prior successful builds.|
|ORG_NAME||Name of the organization/user that owns the repository currently being built (e.g. This will be set to
|PROJECT_ID||ID of the Shippable Project.|
|PULL_REQUEST||Pull request number if the job is a pull request. If not, this will be set to false.|
|PULL_REQUEST_BASE_BRANCH||Name of the branch that the pull request will be merged into. It should be the same as BASE_BRANCH.|
|PULL_REQUEST_REPO_FULL_NAME||Full name of the repository from where the pull request originated.|
|REPO_FULL_NAME||Full name of the repository currently being built (eg.
|REPO_NAME||Name of the repository currently being built (eg. This will be set to
|REPOSITORY_URL||URL of your GitHub or Bitbucket repository.|
|SHIPPABLE_AMI_VERSION||The machine image version of the node. For example,
|SHIPPABLE_BUILD_DIR||Directory where the repository is cloned.|
|SHIPPABLE_BUILD_ID||ID of build in Shippable.|
|SHIPPABLE_BUILD_NUMBER||Build number for current build.|
|SHIPPABLE_BUNDLER_ARGS||The value of bundler_args in the build section of shippable.yml.|
|SHIPPABLE_COMMIT_RANGE||Parent commit… current commit being built.|
|SHIPPABLE_GEMFILE||The gemfile specified for the job in the shippable.yml.|
|SHIPPABLE_GO_VERSION||GO version specified for the job.|
|SHIPPABLE_GOPATH||PATH set to $HOME|
|SHIPPABLE_JDK_VERSION||The jdk for the job in the shippable.yml.|
|SHIPPABLE_LEIN_VERSION||Clojure version specified for the job.|
|SHIPPABLE_NODE_VERSION||NodeJS version specified for the job.|
|SHIPPABLE_PHP_VERSION||PHP version specified for the job.|
|SHIPPABLE_POSTGRES_CMD||"sudo -u postgres \$SHIPPABLE_POSTGRES_BINARY -c "config_file=/etc/postgresql/\$SHIPPABLE_POSTGRES_VERSION/main/postgresql.conf""|
|SHIPPABLE_PYTHON_VERSION||Python version specified for the job.|
|SHIPPABLE_REPO_DIR||The directory where builds run.|
|SHIPPABLE_REPO_SLUG||Full name of the repository being built (e.g.
|SHIPPABLE_RUBY||Ruby version version specified for the job.|
|SHIPPABLE_SCALA_VERSION||Scala version specified for the job.|
|SHIPPABLE_SELENIUM_BINARY||Location of selenium binary. It is set only if selenium is in the addons or services in the shippable.yml.|
|SHIPPABLE_SUBMODULE_ENABLED||Whether or not submodules in the repository will be updated.|
|SHIPPABLE_WWW_URL||Direct URL link to the shippable main application website.|
|SHIPPABLE_NODE_ARCHITECTURE||Architecture of the node that runs the build.|
|SHIPPABLE_NODE_OPERATING_SYSTEM||Operating system of the node that runs the build.|
|SUBSCRIPTION_ID||ID of the Subscription.|
|IS_GIT_TAG||Set to true if the build is triggered by a git tag push webhook. If not, this will be set to false.|
|GIT_TAG_NAME||The git tag name if the build is triggered by a git tag push webhook or a release webhook.|
|IS_RELEASE||Set to true if the build is triggered by a release webhook. If not, this will be set to false. This env variable is currently supported for GitHub only.|
|IS_PRERELEASE||Set to true if the release is marked pre-release when it was published. If not, this will be set to false. This env variable is currently supported for GitHub only.|
|RELEASED_AT||The timestamp when the release was published. This env variable is currently supported for GitHub only.|
|RELEASE_NAME||The name of the release webhook. This env variable is currently supported for GitHub only.|
Gerrit specific variables
When a Gerrit CI build is triggered a set of environment variables are automatically made available that you can use in your scripts.
|GERRIT_PROJECT||The name of the gerrit project|
|GERRIT_REST_URL||Gerrit REST api endpoint|
|GERRIT_HOST||Gerrit server hostname|
|GERRIT_PORT||Gerrit server SSH port|
|GERRIT_BRANCH||The current branch of the project|
|GERRIT_EVENT_TYPE||The name of the event which triggered the build|
|GERRIT_CHANGE_ID||The change-Id of the change|
|GERRIT_CHANGE_URL||The canonical URL of the change|
|GERRIT_CHANGE_NUMBER||The change number|
|GERRIT_CHANGE_SUBJECT||The description of change|
|GERRIT_CHANGE_COMMIT_MESSAGE||The commit message for the change’s current patch set|
|GERRIT_REFSPEC||The git reference at the revision of current patch set|
|GERRIT_PATCHSET_NUMBER||The patchset number|
|GERRIT_PATCHSET_REVISION||Git commit for current patchset|
|GERRIT_CHANGE_OWNER_NAME||The name of the change owner|
|GERRIT_CHANGE_OWNER_EMAIL||The name of the change owner|
|GERRIT_CHANGE_OWNER||The name and email of the change owner|
|GERRIT_PATCHSET_UPLOADER_NAME||The name of the patchset uploader|
|GERRIT_PATCHSET_UPLOADER_EMAIL||The email of the patchset uploader|
|GERRIT_PATCHSET_UPLOADER||The name and email of the patchset uploader|
|GERRIT_CHANGE_UPLOADER_NAME||The name of the change uploader|
|GERRIT_CHANGE_UPLOADER_EMAIL||The email of the change uploader|
|GERRIT_CHANGE_UPLOADER||The name and email of the change uploader|
Travis compatible variables
We support several environment variables to help customers migrating from Travis CI. These are listed below:
User defined Variables
If you need your own environment variables for your build, you can specify these in your yml:
# environment variable env: - FOO=foo BAR=bar
If you want to trigger builds against combinations of environment variables, you can include the combinations you need, one on each line. For example, the yml below will trigger 2 builds for each commit:
# environment variable env: - TEST=true PROD=false - TEST=false PROD=true
Env variables can create an exponential number of builds when combined with
rvm , node_js etc. i.e. it is multiplicative. For an example, please check out the Matrix Builds section.
Note that, the environment variables can also be given in yaml dictionary format as specified below.
# environment variable env: - TEST: true PROD: false - TEST: false PROD: true
To avoid a matrix build and kick off a single build with all environments, you can use the global tag as detailed in the section below.
Please note that environment variables set in the
pre_ci section are not available in the
on_failure sections since
pre_ci commands are run on the build machine and not inside the CI container.
If you want to define one or more environment variables that do not trigger multiple builds, you should use the
env: global: - FOO=true - BAR=false
The snippet above will trigger just one build with both variables set.
If you want to define a set of variables that are global, and another set that trigger a build matrix, you can configure that as shown below:
env: global: - FOO=true - BAR=false matrix: - TEST=test - PROD=prod
The snippet above will trigger 2 builds: one with environment variables (TEST=test, FOO=true, BAR=false) and another with (PROD=prod, FOO=true, BAR=false).
Note that, the environment variables can also be given in yaml dictionary format for both
matrix variables, as specified below.
env: global: - FOO: true - BAR: false matrix: - TEST: test - PROD: prod
You can also use encrypted variables in the global or matrix sections if needed. More on encrypted variables below.
If you need to include environment variables that are used to store sensitive information like passwords or keys, you should encrypt them and enter the encrypted value in your yml.
To encrypt an environment variable, go to your Shippable subscription or project settings. Choose 'Encrypt' from the left sidebar menu. Enter your variables in the textbox in the Encrypt section and click on
Encrypt. This will give you the encrypted string that you can use in your yml.
You can then include the encrypted string in your yml using the
secure tag. The variables are then available during your build:
env: - secure: <encrypted output> build: ci: - echo $FOO
As with other user defined environment variables, you can specify multiple secure variables in your yml to trigger a build matrix or specify them as global.
- Due to the security risk of exposing your secure variables, we do not decrypt secure variables for pull request from the forks of public projects. Secure variable decryption is limited to the pull request triggered from the branches on the same repository.
- Decrypted secured variables are not displayed in the script tab for security reasons.
- Project owners can decrypt secure variables by going to their Settings tab, choosing Encrypt in the sidebar menu, and then entering the secure variable in the Decrypt section.