npm-travis v1.0.2
npm-travis
This tool allows integrating Travis test runs with npm-based workflows. The original use case was triggering Travis builds from Jenkins in Wikimedia's Gerrit code review tool.
The basic idea is that the npm-travis
binary will push a throwaway
branch to github containing the current git HEAD (which is under
review and has not yet been merged). It then uses the Travis API
to monitor the build triggered by this push, stream the logs as
they appear (for real-time progress feedback), and then exit with
an error code corresponding to the passed/failed status of the
travis build (after deleting the temporary branch).
In WMF's actual use, we push to Gerrit's repository, which then gets
mirrored to github. (You can specify the --remote
option to the
CLI to specify a particular push target.) This adds a little bit
of latency, but it prevents our Gerrit-to-github synchronization job
from attempting to "sync" and remove our temporary branch while we're
in the middle of using it. This also allows us to use Gerrit's
access controls to give npm-travis
the ability to push only to
branches prefixed with npm-travis/
.
Suggested use
$ cd my-node-tool
$ npm install --save-dev npm-travis
Then add the following to the package.json
of my-node-tool:
"scripts": {
"travis": "npm-travis"
}
Add a job to trigger npm run travis
to verify a submitted patch (for
example, using Jenkins Job Builder/Zuul). The exit status of this
job will mirror the Travis build status, and the console log will
contain the console output of all Travis jobs (build configurations)
associated with this build.
For non-node.js projects, you can install the npm-travis tool globally
(npm install -g npm-travis
) and just invoke the npm-travis
binary
directly in the Jenkins job (rather than using npm run
).
Advanced use
If you would like to have a separate Jenkins job for every Travis
build configuration, use the --job
option:
"scripts": {
"travis-1": "npm-travis --job 1",
"travis-2": "npm-travis --job 2",
/* etc */
}
If Travis triggers N jobs per build (for example, 7.1
, 7.2
, ... 7.N
)
then there should be N scripts here.
Jenkins should then trigger npm run travis-1
...npm run travis-N
.
Each job's exit status will mirror the Travis passed/failed status,
and the Jenkins console log will contain the Travis log output for
only the specific job/build configuration.
Configuration
The npm-travis
tool needs two pieces of information: the name of
the github repository which is triggering the Travis build, and
a git remote which it can push to. The name of the git remote
(referred to as <remote>
below) is given by the --remote
command-line option, defaulting to github
. It then attempts to
discover the github repository name as follows:
- If there is a repository name given on the command line, use that.
- Otherwise, use
git remote show <remote>
to look at the push URL. If the push URL looks like a github url, extract the repository name from it. - Otherwise, use
git remote show origin
and see if its push URL looks like a github URL, extracting a repository name if so. - Otherwise, look in
package.json
in the current working directory, and see if itsrepository
field looks like a github URL, and extract a repository name. - Fail.
It then checks whether the git remote <remote>
exists, and if it
does not it will create it using:
git remote add <remote> git@github.com:<repository name>
In the common case where you've cloned the code from github, this just
works. For WMF's setup, we want to push to Gerrit, but the Gerrit
push URL doesn't map in a simple way to the github repository name.
So we create a git remote named gerrit
ahead of time, and then
invoke npm-travis --remote gerrit <repository name>
, explicitly
giving the github repository name on the command line.
Security
Note that running npm-travis
pushes a branch to the github
repository for your project, and therefore that task must be given
write access to the project on github. Furthermore, if the task is
triggered on patch submission, anyone with permission to submit
patches can create a (short-lived) branch on your repository and run
arbitrary code on a Travis instance. Be cautious. You might want to
point npm-travis
at a fork or mirror of your github repository.
In addition, Travis "secure variables" are normally
disabled for cross-origin pull requests;
but since npm-travis
uses same-origin branches rather than pull
requests, it is not safe to use Travis "secure variables" in
repositories using npm-travis
.
License
MIT license; see LICENSE.
(c) 2014 by C. Scott Ananian