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_app:
source_url:
source_tar:
version:
},
files: []
},
},
})
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.