<commit_before># Travis CI

Hopefully you have some tests or just lint checks that you want to run
in a continuous manner, whenever new commits are pushed or on code from pull requests.

We currently use Travis CI and thus prefer it for consistency, but other CIs are ok given reasonable consideration.

Go to https://travis-ci.com/profile/tobiipro
and enable Travis CI integration for your repository.

**NOTE** It is recommended that on the repository's Travis CI settings page you
* enable `Build only if .travis.yml is present`
* **if you have long-running builds such as deployment to AWS CloudFormation**,  
  enable `Limit concurrent jobs: 1`
* enable `Auto cancel branch builds`
* enable `Auto cancel pull request builds`
* add cronjob `master - daily - Always run`

Link to the repository's page on Travis CI
and embed a status image for the `master` branch (or more) in `README.md`, in short add:

```md
# <software product> [![Build Status][2]][1]

...

  [1]: https://travis-ci.com/tobiipro/<repo>
  [2]: https://travis-ci.com/tobiipro/<repo>.svg?branch=master
```

**NOTE** for private repositories, you'll want to go https://travis-ci.com/tobiipro/<repo>,
click the status image, select 'Image URL' and copy the SVG URL (the link has a unique token).

Reference: https://docs.travis-ci.com/user/status-images/

Don't forget to commit the most important thing: a `.travis.yml` ([template](../repo/dot.travis.yml)) file which configures your Travis CI build.


## Debugging

If you experience failures and you want to debug inside a Travis worker,
see [how to debug](https://docs.travis-ci.com/user/running-build-in-debug-mode/).

You can speed up the process, by running `support-firecloud/bin/travis-debug --token X --job Y`, where
- X is the token that you see at https://travis-ci.com/profile/
  - you can omit `--token X` if you have an environment variable `TRAVIS_API_TOKEN`
- Y can be a numeric job ID or a job URL or even a build URL (most useful)

**NOTE** Remember that you can almost always run `--help`,
so `support-firecloud/bin/travis-debug --help`, to get proper info.

Once you SSH via the tmate session, you will be welcomed by the message:

>   Run individual commands; or execute configured build phases
>   with `travis_run_*` functions (e.g., `travis_run_before_install`).

So run `travis_run_before_install` in order to bootstrap the machine.
Once that command finishes, you will be welcome by the message:

>   Please run `./.travis.sh debug` to activate your debug session !!!

So run `./.travis.sh debug` in order to setup the shell session (e.g. environment variables like `PATH`).


## Secrets

**NOTE** See related docs on [how to manage secrets](how-to-manage-secrets.md).

If you have Travis-specific values to encrypt e.g. a Slack API token for notifications,
then you can add encrypted values in the `.travis.yml` file that only Travis CI can decrypt.

**NOTE** If you're working with **public repositories**,
you can simply use the `travis-encrypt` utility in the `support-firecloud` repository
and shortcircuit the official [`Travis CI` client](https://github.com/travis-ci/travis.rb) which requires Ruby&co.
Use `support-firecloud/bin/travis-encrypt --value "..."` instead of `travis encrypt "..."` in the examples below.

For **private repositories**, you need to use the official (and Ruby heavy) [Travis CI client](https://github.com/travis-ci/travis.rb). On OSX run `brew install travis` to install it.

```shell
travis encrypt --com something_super_secret
```

Now you can add the `secret: "..."` text to your `.travis.yml` file.
<commit_msg>add note about travis_run_before_install crashing<commit_after># Travis CI

Hopefully you have some tests or just lint checks that you want to run
in a continuous manner, whenever new commits are pushed or on code from pull requests.

We currently use Travis CI and thus prefer it for consistency, but other CIs are ok given reasonable consideration.

Go to https://travis-ci.com/profile/tobiipro
and enable Travis CI integration for your repository.

**NOTE** It is recommended that on the repository's Travis CI settings page you
* enable `Build only if .travis.yml is present`
* **if you have long-running builds such as deployment to AWS CloudFormation**,  
  enable `Limit concurrent jobs: 1`
* enable `Auto cancel branch builds`
* enable `Auto cancel pull request builds`
* add cronjob `master - daily - Always run`

Link to the repository's page on Travis CI
and embed a status image for the `master` branch (or more) in `README.md`, in short add:

```md
# <software product> [![Build Status][2]][1]

...

  [1]: https://travis-ci.com/tobiipro/<repo>
  [2]: https://travis-ci.com/tobiipro/<repo>.svg?branch=master
```

**NOTE** for private repositories, you'll want to go https://travis-ci.com/tobiipro/<repo>,
click the status image, select 'Image URL' and copy the SVG URL (the link has a unique token).

Reference: https://docs.travis-ci.com/user/status-images/

Don't forget to commit the most important thing: a `.travis.yml` ([template](../repo/dot.travis.yml)) file which configures your Travis CI build.


## Debugging

If you experience failures and you want to debug inside a Travis worker,
see [how to debug](https://docs.travis-ci.com/user/running-build-in-debug-mode/).

You can speed up the process, by running `support-firecloud/bin/travis-debug --token X --job Y`, where
- X is the token that you see at https://travis-ci.com/profile/
  - you can omit `--token X` if you have an environment variable `TRAVIS_API_TOKEN`
- Y can be a numeric job ID or a job URL or even a build URL (most useful)

**NOTE** Remember that you can almost always run `--help`,
so `support-firecloud/bin/travis-debug --help`, to get proper info.

Once you SSH via the tmate session, you will be welcomed by the message:

>   Run individual commands; or execute configured build phases
>   with `travis_run_*` functions (e.g., `travis_run_before_install`).

So run `travis_run_before_install` in order to bootstrap the machine.  
Once that command finishes, you will be welcome by the message:

>   Please run `./.travis.sh debug` to activate your debug session !!!

So run `./.travis.sh debug` in order to setup the shell session (e.g. environment variables like `PATH`).

**NOTE** If `travis_run_before_install` fails and crashes the tmate session, you can try running `./.travis.sh before-install` (equivalent but safer).


## Secrets

**NOTE** See related docs on [how to manage secrets](how-to-manage-secrets.md).

If you have Travis-specific values to encrypt e.g. a Slack API token for notifications,
then you can add encrypted values in the `.travis.yml` file that only Travis CI can decrypt.

**NOTE** If you're working with **public repositories**,
you can simply use the `travis-encrypt` utility in the `support-firecloud` repository
and shortcircuit the official [`Travis CI` client](https://github.com/travis-ci/travis.rb) which requires Ruby&co.
Use `support-firecloud/bin/travis-encrypt --value "..."` instead of `travis encrypt "..."` in the examples below.

For **private repositories**, you need to use the official (and Ruby heavy) [Travis CI client](https://github.com/travis-ci/travis.rb). On OSX run `brew install travis` to install it.

```shell
travis encrypt --com something_super_secret
```

Now you can add the `secret: "..."` text to your `.travis.yml` file.

{'fraction_non_alphanumeric': 0.10853658536585366, 'fraction_numerical': 0.0013550135501355014, 'mean_word_length': 4.125694444444444, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 17, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2921398', 'n_tokens_mistral': 2289, 'n_tokens_neox': 2204, 'n_words': 968}