Travis CI Documentation (original) (raw)

Encryption Keys

Fork Repository settings
Encryption scheme
Usage
Fetch the public key

We have separate documentation on encrypting files.

A repository’s .travis.yml file can have “encrypted values”, such as environment variables, notification settings, and deploy api keys. These encrypted values can be added by anyone, but are only readable by Travis CI. The repository owner does not keep any secret key material.

Fork Repository settings #

Repository security settings for forked repositories on Git are available starting March 1st, 2022.

For Git repositories, you may manage per repository how the environment variables and the custom SSH keys will be handled in Travis CI when a build triggered as an effect of filing a Pull Request from a forked repository. Two settings are available specifically for this purpose, allowing you to customize your security vs. collaboration setup.

base repository - a Git repository, which is forked by someone else
fork or forked repository - any Git repository forked from the base repository
PR - Pull Request (e.g. in GitHub, BitBucket, GitLab) or Merge Request (in Assembla)

Please note: Repositories activated in Travis CI before March 1st, 2022 will have the Share encrypted environment variables with forks (PRs) setting set to OFF. Please verify your collaboration model if necessary (especially for public repositories). The Share SSH keys with forks (PRs) will be set to ON for private repositories not to break too many collaboration setups. Repository settings will be set by default to OFF for any repository activated in Travis CI after March 1st, 2022. For repositories activated in Travis CI after March 1st, 2022, you may want to consider changing the default settings depending on your collaboration model.

This setting determines if the base repository´s encrypted environment variables will be shared with the forked repository in a fork-to-base pull request (the fork repository merges changes into the base repository).

In the case of a base-to-base pull request (changes are merged from the base repository into itself), the encrypted environment variables will always be available. This allows collaborators to file Pull Requests using the repository encrypted environment variables and preserve existing checks configured, e.g. in GitHub.

In the case of a fork-to-fork pull request (changes are merged from the forked repository into itself), the encrypted environment variables from the base repository will never be available. Therefore, one needs to replace or bypass them directly in forked repository.

In the case of a fork-to-base pull request:

If this setting is ON, the encrypted environment variables will be available to the forked repository, which means that builds in the forked repository will have access to the encrypted environment variables from the base repository. This may be a less secure approach yet allows for a collaboration using forks and Pull Requests (PRs).
If this setting is OFF and the build relies on any encrypted environment variable, the PR from fork to base repository will fail. This secures your base repository encrypted environmental variables by putting a constraint on accessing them from forks.

Please Note: In the travis-ci.com environment, Custom SSH keys are only available for private repositories. Read more about custom SSH keys.

Starting June 2021 travis-ci.org is disabled and therefore no longer supported. Please use travis-ci.com.

Encryption scheme #

Travis CI uses asymmetric cryptography. For each registered repository, Travis CI generates an RSA keypair. Travis CI keeps the private key private, but makes the repository’s public key available to those who have access to the repository.

Once the public key is available, anyone (including those without push access to your repository) can encrypt data which can only be decrypted by Travis CI, using the corresponding private key.

Obtain public keys #

The method to obtain the public key depends on where the target repository exists, and the API version you are using.

Furthermore, the request may require authorization via the Authorization: tokenheader depending on the repository’s location and visibility, as well as the API version used.

Authorization header requirement

Repository visibility and location	API server	API v1	API v3
/repos/OWNER/REPO/key	/v3/repo/OWNER%2fREPO/key_pair/generated
public on .com	https://api.travis-ci.com	yes	yes
private on .com	https://api.travis-ci.com	yes	yes

Notice that API v3 endpoints above show the repository name with %2f.

If the Authorization: token header is required, you can obtain the token by visiting the account page:

travis-ci.com

Examples #

Here are some examples of curl commands to obtain the public key.

A public repository on travis-ci.com using API v1

curl https://api.travis-ci.com/repos/travis-ci/travis-build/key

A public repository on travis-ci.com using API v3

curl -H "Authorization: token **TOKEN**" https://api.travis-ci.com/v3/repo/travis-ci%2ftravis-build/key_pair/generated

A private repository on travis-ci.com using API v3

curl -H "Authorization: token **TOKEN**" https://api.travis-ci.com/v3/repo/OWNER%2fREPO/key_pair/generated

Usage #

The easiest way to encrypt something with the public key is to use Travis CLI. This tool is written in Ruby and published as a gem. First, you need to install the gem:

If you are using travis-ci.com, you need to login first:

Then, you can use encrypt command to encrypt data (This example assumes you are running the command in your project directory. If not, add -r owner/project):

travis encrypt SOMEVAR="secretvalue"

Or, if you are using travis-ci.com, you will need to add --pro to the CLI:

travis encrypt --pro SOMEVAR="secretvalue"

This will output a string looking something like:

secure: ".... encrypted data ...."

Now you can place it in the .travis.yml file.

You can also skip the above, and add it automatically by running:

travis encrypt SOMEVAR="secretvalue" --add

Please note that the name of the environment variable and its value are both encoded in the string produced by “travis encrypt.” You must add the entry to your .travis.yml with key “secure” (underneath the “env” key). This makes the environment variable SOMEVAR with value “secretvalue” available to your program.

You may add multiple entries to your .travis.yml with key “secure.” They will all be available to your program.

Encrypted values can be used insecure environment variables in the build matrixand notifications.

Escape Symbols #

When you use travis encrypt to encrypt sensitive data, it is important to note that it will be processed as a bash statement. This means that secret you are encrypting should not cause errors when bash parses it. Having incomplete data will cause bash to dump the error statement to the log, which contains portions of your sensitive data.

Thus, you need to escape special characterssuch as braces, parentheses, backslashes, and pipe symbols.

For example, you would type ma&w!doc as ma\&w\!doc.

And to assign the string 6&a(5!1Ab\ to FOO:

travis encrypt "FOO=6\\&a\\(5\\!1Ab\\\\"

travis encrypts the string FOO=6\&a\(5\!1Ab\\, which then bash uses to evaluate in the build environment.

Equivalently, you can do

travis encrypt 'FOO=6\&a\(5\!1Ab\\'

Notifications Example #

We want to add campfire notifications to our .travis.yml file, but we don’t want to publicly expose our API token.

The entry should be in this format:

notifications:
  campfire:
    rooms: "[subdomain]:[api token]@[room id]"

For us, that is somedomain:abcxyz@14.

We encrypt this string

travis encrypt somedomain:abcxyz@14

Which produces something like this

Please add the following to your .travis.yml file:

  secure: "ABC5OwLpwB7L6Ca...."

We add to our .travis.yml file

notifications:
  campfire:
    rooms:
      secure: "ABC5OwLpwB7L6Ca...."

And we’re done.

Detailed Discussion #

The secure var system takes values of the form { 'secure' => 'encrypted string' } in the (parsed YAML) configuration and replaces it with the decrypted string.

notifications:
  campfire:
    rooms:
      secure: "encrypted string"

becomes

notifications:
  campfire:
    rooms: "decrypted string"

while

notifications:
  campfire:
    rooms:
      - secure: "encrypted string"

becomes

notifications:
  campfire:
    rooms:
      - "decrypted string"

In the case of secure env vars

env:
  - secure: "encrypted string"

becomes

env:
  - "decrypted string"

Fetch the public key #

You can fetch the public key for your repository with Travis API, using /repos/:owner/:name/key or/repos/:id/key endpoints, for example:

https://api.travis-ci.com/repos/travis-ci/travis-ci/key

You can also use the travis tool for retrieving said key:

Or, if you’re not in your project directory:

travis pubkey -r owner/project

Note, travis uses travis.slug in your project to determine the endpoints if it exists (check by using git config --local travis.slug), if you rename your repo or move your repo to another user/organization, you might need to change it.