travis-bot

This is a small utility to run a set of "plugins" against a Pull Request on Travis and then report a set of results to Github.

Getting Started

To use travis-bot you'll need to set up a few things:

1. Create a Github account to use for bot activity. This will be the account login and profile photo that you'll see when the bot comments on a pull request.

2. Create a personal access token for the Github bot account.

3. In the Travis settings for your repository, set the personal access token as an environment variable called GITHUB_TOKEN.

   

4. Add travis-bot as a dependency to your project:

   npm install --save-dev travis-bot

5. Create a file called travis-bot.config.js at the root of your project (i.e. this file needs to be commited to your Github repository).

6. In this new file add the following:

   const travisbot = require('travis-bot');
   
   module.exports = {
     botUsername: `<Add the Github Username for your Bot Account Here>`
     plugins: [
       new travisbot.plugins.Size({
         globPattern: '**/*.js',
         globOptions: {
           ignore: [
             '**/node_modules/**/*',
           ]
         },
       }),
     ],
   };

7. Add the following to your .travis.yml file

   after_script:
     - npm install -g travis-bot
     - travis-bot

Now you can commit your code and if everything is set up correctly, you'll see comments from your bot account.

Running Locally

You can see what travis-bot will do locally with the following:

npm install --global travis-bot
travis-bot

This is useful if you want to see the file differences without waiting on Travis.

Customising Config Path

You can use the -c flag to define a custom config path:

travis-bot -c ./some-path-my-config.js

Customising Install and Build

If npm install && npm build will not suffice for your project, you define a buildCommand parameter in your config file to define the command to run in the two checkouts of your project.

module.exports {
  // Custom build command in travis.config.js
  buildCommand: `npm install && gulp`,


  botUsername: `....`,
  plugins: [...]
}

How it Works

When you run travis-bot it checks out two versions of your project.

1. If run locally, it'll checkout the default branch of your repo AND use the current directory and the current files for the second version.
2. If run on Travis, it'll checkout the base of the Pull Request, or the target branch, for the first version and it'll checkout the Pull Request commit as the second version.

These are checked out into tempory files under /tmp and travis-bot will npm install && npm run build in each repository.

After this, each plugin defined in your config file will be called with a beforePath and afterPath. This allows plugins to compare files or anything else they want.

Plugins are expected to return a promise that resolves to an object with a prettyLog parameter and a markdownLog parameter. The prettyLog is used to display plugin output to the console and markdownLog is used to print to the Github comment raised against the Pull Request.

Adding Custom Plugins

You can build custom plugins, the key things to note are:

Your plugin must:

1. ..have a name property.
2. ..have a run method.
3. ..return a Promise from the run method.

And your plugin should:

1. ..resolve the run promise with an objectwith prettyLog and markdownLog string parameters.