travis-ci

node library to access the Travis-CI API

npm install travis-ci
35 downloads in the last day
291 downloads in the last week
2 037 downloads in the last month

node-travis-ci Build Status

node library to access the Travis-CI API

NPM

Instantiation

var Travis = require('travis-ci');
var travis = new Travis({
    version: '2.0.0'
});

// To access the Travis-CI Pro API
var travis = new Travis({
    version: '2.0.0',
    pro: true
});

API

Authentication

Many functions, such as travis.accounts, require authenticating as a user. Currently the only way to authenticate is to start with a github oauth token, request a travis access token, and authenticate with that.

travis.auth.github({
    github_token: GITHUB_OAUTH_TOKEN
}, function (err, res) {
    // res => {
    //     access_token: XXXXXXX
    // }
    travis.authenticate({
        access_token: res.access_token
    }, function (err) {
         // we've authenticated!
    });
});

As a convenience, authenticate also accepts github tokens, or github credentials (which are only sent to github) and performs the necessary requests to aquire a travis access token. For example:

travis.authenticate({
    github_token: GITHUB_OAUTH_TOKEN
}, function (err) {
    // we've authenticated! 
});

or

travis.authenticate({
    username: GITHUB_USERNAME,
    password: GITHUB_PASSWORD
}, function (err) {
    //we've authenticated!
});

Pro Tip: Authentication is simply a convenience function that ensures your token has the required permissions, then appends your access_token to all subsequent requests. You can alternatively pass access_token to any request where permission is required.

Accounts

Accounts calls require authentication.

travis.accounts(function (err, res) {
    // res => {
    //     "accounts": [
    //         {
    //             "id": 5186,
    //             "name": "Patrick Williams",
    //             "login": "pwmckenna",
    //             "type": "user",
    //             "repos_count": 48
    //         },
    //         {
    //             "id": ***,
    //             "name": "BitTorrent Torque Labs",
    //             "login": "bittorrenttorque",
    //             "type": "organization",
    //             "repos_count": ***
    //         },
    //         {
    //             "id": ***,
    //             "name": null,
    //             "login": "Studyokee",
    //             "type": "organization",
    //             "repos_count": ***
    //         },
    //         {
    //             "id": ***,
    //             "name": "BitTorrent Inc.",
    //             "login": "bittorrent",
    //             "type": "organization",
    //             "repos_count": ***
    //         }
    //     ]
    // }
});

Authorization

travis.auth.github({
    github_token: GITHUB_OAUTH_TOKEN
}, function (err, res) {
    // res => {
    //     access_token: ***
    // }
});

Additional endpoints that have not be implemented yet:

Endpoints that exist, but are intended for brower flows:

Branches

travis.branches(function (err, res) {
    // res => {
    //     branches: [],
    //     commits: []
    // }
});

Broadcasts

travis.broadcasts(function (err, res) {
    // res => {
    //     broadcasts: []
    // }
});

Builds

// to get the info for a specific build, specify the build id
// this is data used for pages such as:
// https://travis-ci.org/pwmckenna/node-travis-ci/builds/10380000
travis.builds({
    id: 10380000
}, function (err, res) {
    // res => {
    //     "build": {
    //         "id": 10380000,
    //         "repository_id": 1095505,
    //         "commit_id": 3053424,
    //         "number": "43",
    //         "pull_request": false,
    //         "pull_request_title": null,
    //         "pull_request_number": null,
    //         "config": {
    //             "language": "node_js",
    //             "node_js": [
    //                 "0.10.1"
    //             ],
    //             "script": [
    //                 "./node_modules/grunt-cli/bin/grunt test"
    //             ],
    //             ".result": "configured",
    //             "global_env": [
    //                 {
    //                     "secure": "SHezJGUSi1cc/V+AWBgmGe...
    //                 },
    //                 {
    //                     "secure": "opq2IxY6TquOtn4nCI75Y...
    //                 },
    //                 {
    //                     "secure": "f4rapdrgZJIeqUUBu3Bp/...
    //                 }
    //             ]
    //         },
    //         "state": "canceled",
    //         "started_at": null,
    //         "finished_at": "2013-10-30T23:19:20Z",
    //         "duration": 0,
    //         "job_ids": [
    //             10380001
    //         ]
    //     },
    //     "commit": {
    //         "id": 3053424,
    //         "sha": "af594e5b0744e6fdd4af5c7470652286420db430",
    //         "branch": "master",
    //         "message": "1.0.1",
    //         "committed_at": "2013-08-19T20:12:25Z",
    //         "author_name": "Patrick Williams",
    //         "author_email": "pwmckenna@gmail.com",
    //         "committer_name": "Patrick Williams",
    //         "committer_email": "pwmckenna@gmail.com",
    //         "compare_url": "https://github.com/pwmckenna/node-travis-ci/...
    //     },
    //     "jobs": [
    //         {
    //             "id": 10380001,
    //             "repository_id": 1095505,
    //             "build_id": 10380000,
    //             "commit_id": 3053424,
    //             "log_id": 4540661,
    //             "state": "canceled",
    //             "number": "43.1",
    //             "config": {
    //                 "language": "node_js",
    //                 "node_js": "0.10.1",
    //                 "script": [
    //                     "./node_modules/grunt-cli/bin/grunt test"
    //                 ],
    //                 ".result": "configured",
    //                 "global_env": "GITHUB_OAUTH_TOKEN=[secure] ...
    //             },
    //             "started_at": null,
    //             "finished_at": "2013-10-30T23:19:19Z",
    //             "queue": "builds.linux",
    //             "allow_failure": false,
    //             "tags": ""
    //         }
    //     ]
    // }
});
// to cancel a build
travis.builds.cancel({
    id: 10380000
}, function (err) {
});

Documentation

travis.documentation(function (err, res) {
    // res => <html>
    //     ...
    // </html
});

Endpoints

travis.endpoints(function (err, res) {
    // res => [
    //     {
    //         "name": "Home",
    //         "doc": "",
    //         "prefix": "/",
    //         "routes": [
    //             {
    //                 "uri": "/",
    //                 "verb": "GET",
    //                 "doc": "Landing point...",
    //                 "scope": "public"
    //             },
    //             {
    //                 "uri": "/redirect",
    //                 "verb": "GET",
    //                 "doc": "Simple endpoints that redirects somewhere else...",
    //                 "scope": "public"
    //             },
    //             {
    //                 "uri": "/config",
    //                 "verb": "GET",
    //                 "doc": "Provides you with system info:...",
    //                 "scope": "public"
    //             }
    //         ]
    //     },
    //     {
    //         "name": "Accounts",
    //         "doc": "",
    //         "prefix": "/accounts",
    //         "routes": [
    //             {
    //                 "uri": "/accounts/",
    //                 "verb": "GET",
    //                 "doc": "",
    //                 "scope": "private"
    //             }
    //         ]
    //     },
    //     ...
    // ]
});
travis.endpoints({
    prefix: 'endpoints'
}, function (err, res) {
    // res => {
    //     "name": "Endpoints",
    //     "doc": "Documents all available API endpoints...",
    //     "prefix": "/endpoints",
    //     "routes": [
    //         {
    //             "uri": "/endpoints/",
    //             "verb": "GET",
    //             "doc": "Lists all available API endpoints by URI prefix...",
    //             "scope": "public"
    //         },
    //         {
    //             "uri": "/endpoints/:prefix",
    //             "verb": "GET",
    //             "doc": "Infos about a specific controller....",
    //             "scope": "public"
    //         }
    //     ]
    // }
});

Hooks

All hook calls require authentication.

travis.hooks(function (err, res) {
    // res => [
    //     {
    //         id: 1095505,
    //         name: 'node-travis-ci',
    //         owner_name: 'pwmckenna',
    //         description: 'node library to access the Travis-CI API',
    //         active: true,
    //         private: false,
    //         admin: true
    //     }
    //     ...
    // ]
});
travis.hooks({
    id: 1095505,
    hook: {
        active: false
    }
}, function (err, res) {
});

Jobs

travis.jobs({
    id: JOB_ID
}, function (err, res) {
    // res => {
    //     "job": {
    //         "id": 9624444,
    //         "repository_id": 1095505,
    //         "repository_slug": "pwmckenna/node-travis-ci",
    //         "build_id": 9624443,
    //         "commit_id": 2836527,
    //         "log_id": 3986694,
    //         "state": "failed",
    //         ...
    //     },
    //     "commit": {
    //         "id": 2836527,
    //         "sha": "431d6e5d899f165e4786ce82c4672975cddca670",
    //         "branch": "master",
    //         "message": "fixing builds test",
    //         ...
    //     }
    // }
});
travis.jobs.log({
    job_id: JOB_ID
}, function (err, res) {

});

Logs

travis.logs({
    id: LOG_ID
}, function (err, res) {
    // res => {
    //     log: {
    //         id: 3986694,
    //         job_id: 9624444,
    //         type: 'Log',
    //         body: 'Using worker: worker-linux-6-2.bb.travis-ci.org:travis-linux-15\n\n$ export GITHUB_OAUTH_TOKEN=[secure]...
    //     }
    // }
});

Repos

travis.repos({
    owner_name: 'pwmckenna'
//  member: 'pwmckenna
}, function (err, res) {
    // res => {
    //     "repos": [
    //         {
    //         "id": 1095505,
    //         "slug": "pwmckenna/node-travis-ci",
    //         "description": "node library to access the Travis-CI API",
    //         "last_build_id": 6347735,
    //         "last_build_number": "468",
    //         "last_build_state": "started",
    //         "last_build_duration": null,
    //         "last_build_language": null,
    //         "last_build_started_at": "2013-04-15T09:45:29Z",
    //         "last_build_finished_at": null
    //         }
    //     ]
    // }
});
travis.repos({
    owner_name: 'pwmckenna',
    name: 'node-travis-ci'
}, function (err, res) {
    // res => {
    //     "repo": {
    //         "id": 1095505,
    //         "slug": "pwmckenna/node-travis-ci",
    //         "description": "node library to access the Travis-CI API",
    //         ...
    //     }
    // }
});
travis.repos.key({
    id: 
}, function (err, res) {
    // res => {
    //   key: '-----BEGIN RSA PUBLIC KEY-----\nMIGfMA0GCSqGSIb...'    
    // }
});
travis.repos.builds({
    owner_name: 'pwmckenna',
    name: 'node-travis-ci'
}, function (err, res) {
    // res => {
    //     builds: [],
    //     commits: []
    // }
});

Requests

Requests calls require authentication.

travis.requests({
    build_id: BUILD_ID    
}, function (err, res) {
    // res => {
    //     "result": true,
    //     "flash": [
    //         {
    //             "notice": "The build was successfully restarted."
    //         }
    //     ]
    // }
});

Stats

travis.stats.repos(function (err, res) {
    // res => {
    //     stats: {
    //         params:
    //         current_user:
    //     }
    // }
});
travis.stats.tests(function (err, res) {
    // res => {
    //     stats: {
    //         params:
    //         current_user:
    //     }
    // }
});

Users

All user calls require authentication.

travis.users(function (err, res) {
    // res => {
    //     "user": {
    //         "id": 5186,
    //         "name": "Patrick Williams",
    //         "login": "pwmckenna",
    //         "email": "patrick@bittorrent.com",
    //         "gravatar_id": "894f552b86b959df97353a7296baee5c",
    //         "locale": "en",
    //         "is_syncing": false,
    //         "synced_at": "2013-10-30T22:47:49Z",
    //         "correct_scopes": true,
    //         "created_at": "2012-02-07T22:17:38Z"
    //     }
    // }
});
travis.users.permissions(function (err, res) {
    // res => {
    //     "permissions": [
    //         1446577,
    //         107140,
    //         1402719,
    //         1392622,
    //         ...
    //     ]
    // }

});
travis.users.sync(function (err, res) {
    // res => {
    //     "result": true
    // }
});

Workers

travis.workers(function (err, res) {
    // res => {
    //     workers: []
    // }
});

CLI

To install as a command line utility, just install globally via npm.

npm install -g travis-ci

The entire library is available via command line interface. While it uses subcommands, the api is the same as above.

travis-ci authenticate --username=pwmckenna --password=superSecret
=>  {
        "access_token": "F7DlolJkD15isf4KEDuh_A"
    }
# or
travis-ci auth github --github_token=ef7c329fb63479eb5be9719bb8b23162072bb20d
=>  {
        "access_token": "F7DlolJkD15isf4KEDuh_A"
    }

Pro Tip: Passing OAuth tokens or github credentials via the command line will leave them in your shell history for all to see. Please shell responsibly.

Use the access_token above in all subsequent commands that require authentication, such as requesting the builds for this project:

travis-ci repos builds --owner_name=pwmckenna --name=node-travis-ci --access_token=F7DlolJkD15isf4KEDuh_A
=>  {
        "builds": [
            {
                "id": 9630304,
                "repository_id": 1095505,
                "pull_request": false,
                "state": "passed",
                ...
            },
            ...
        ]
    }
npm loves you