grunt-heroku-build-api

Upload your app to Heroku using the Build and Source Endpoints of the Platform API and the power of Grunt.

Getting Started

This plugin requires Grunt.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-heroku-build-api --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-heroku-build-api');

The "heroku_build_api" task

Overview

In your project's Gruntfile, add a section named heroku_build_api to the data object passed into grunt.initConfig().

grunt.initConfig({
  heroku_build_api: {
    your_target: {
      options: {
        heroku_auth_token: // Heroku Platform API Authorization Token
        heroku_app: // The name of the heroku app to deploy to,
        source_url: // Optional url to a source .tar.gz file suitable for use by the Build Endpoint
        source_tar: // Optional filename of the source.tar.gz that can be uploaded to the Build Endpoint
        version: // Optional version string to pass to the Heroku Platform API Build Endpoint. 
      },
      files: [] // the files array you know and love, to specify which files to compress into a .tar.gz file
    },
  },
})

You must provide options.heroku_auth_token, options.heroku_app and some specification of source (see below). If any of these are missing, the task will fail with an error.

If options.source_url exists, files and options.source_tar will be ignored. The Build Endpoint of the Platform API will be called with options.source_url as a parameter.

If you provide options.source_tar, and if it is a .tar.gz (or .tgz) file, it will be uploaded to the Sources Endpoint, built by the Build Endpoint and deployed to the app specified by options.heroku_app.

If you don't provide options.source_url or options.source_tar, the files specified by files will be tarred and gzipped and the resulting source tarball will be uploaded to the Sources Endpoint and building and deployment will go from there.

Options

options.heroku_auth_token

Type: String
Default value: ''

A Heroku Platform API Authorization Token. You can run

heroku auth:token

from the command line to generate this value. It can also be found on your Heroku Account page. It is required to use the API. See Heroku's Platform API docs for more information.

You can optionally leave this empty and set the HEROKU_API_KEY environment variable or (preferred) a setting in the .netrc instead. It's still also backwards compatible with older versions and will look for the HEROKU_AUTH_TOKEN environment variable, as well.

options.heroku_app

Type: String
Default value: ''

The name of the Heroku app to deploy to. Also required.

options.source_tar

Type: String
Default value: ''

An optional path to a source .tar.gz (or .tgz) tarball that can be uploaded to the Sources Endpoint.

options.source_url

Type: String
Default value: ''

An optional URL to a source .tar.gz (or .tgz) tarball somewhere on the interwebs that can be handed to the Build Endpoint.

options.version

Type: String

A string that you can use to track different versions of builds. It's not used by the Platform API. More informaiton can be found under "Creating builds" at [Building and Releasing using the Platform API] (https://devcenter.heroku.com/articles/build-and-release-using-the-api#creating-builds)

files

Type: Array

The same files array you are used to with Grunt. Use it to specify which files and directories to compress into a source .tar.gz file that will then be uploaded, built, and deployed to your app.

Default Options

In this example, the default options are used to do something with whatever. So if the testing file has the content Testing and the 123 file had the content 1 2 3, the generated result would be Testing, 1 2 3.

grunt.initConfig({
  heroku_build_api: {
    options: {},
    files: {
      'dest/default_options': ['src/testing', 'src/123'],
    },
  },
})

Custom Options

In this example, custom options are used to do something else with whatever else. So if the testing file has the content Testing and the 123 file had the content 1 2 3, the generated result in this case would be Testing: 1 2 3 !!!

grunt.initConfig({
  heroku_build_api: {
    options: {
      separator: ': ',
      punctuation: ' !!!',
    },
    files: {
      'dest/default_options': ['src/testing', 'src/123'],
    },
  },
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. I loosely follow Google's JavaScript style guide, so you can't go wrong there. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• v0.2.2 Replaced heroku-auth-finder with my forked version that works on win32. Cleaned up tests and fixed a problem with log stream ending early and failing a test case.
• v0.2.0 Added the capability to get Heroku API token from either HEROKU_API_TOKEN env setting or .netrc file.
• v0.1.0 Initial version. I guess you'd call it a beta.

License

Copyright (c) 2015 Brad Ledbetter. Licensed under the MIT license.