diff --git a/website/source/docs/command-line/push.html.markdown b/website/source/docs/command-line/push.html.markdown new file mode 100644 index 000000000..9717f1142 --- /dev/null +++ b/website/source/docs/command-line/push.html.markdown @@ -0,0 +1,33 @@ +--- +layout: "docs" +page_title: "Push - Command-Line" +description: |- + The `packer push` Packer command takes a template and pushes it to a build service that will automatically build this Packer template. +--- + +# Command-Line: Build + +The `packer push` Packer command takes a template and pushes it to a build +service. The build service will automatically build your Packer template and +expose the artifacts. + +This command currently only sends templates to +[Atlas](https://atlas.hashicorp.com) by HashiCorp, but the command will +be pluggable in the future with alternate implementations. + +External build services such as Atlas make it easy to iterate on Packer +templates, especially when the builder you're running may not be easily +accessable (such as developing `qemu` builders on Mac or Windows). + +For the `push` command to work, the +[push configuration](/docs/templates/push.html) +must be completed within the template. + +## Options + +* `-create=true` - If the build configuration matching the name of the push + doesn't exist, it will be created if this is true. This defaults to true. + +* `-token=FOO` - An access token for authenticating the push. This can also + be specified within the push configuration in the template. By setting this + in the template, you can take advantage of user variables. diff --git a/website/source/docs/templates/push.html.markdown b/website/source/docs/templates/push.html.markdown new file mode 100644 index 000000000..1f97a3048 --- /dev/null +++ b/website/source/docs/templates/push.html.markdown @@ -0,0 +1,65 @@ +--- +layout: "docs" +page_title: "Templates: Push" +description: |- + Within the template, the push section configures how a template can be + pushed to a remote build service. +--- + +# Templates: Push + +Within the template, the push section configures how a template can be +[pushed](/docs/command-line/push.html) to a remote build service. + +Push configuration is responsible for defining what files are required +to build this template, what the name of build configuration is in the +build service, etc. + +The only build service that Packer can currently push to is +[Atlas](https://atlas.hashicorp.com) by HashiCorp. Support for other build +services will come in the form of plugins in the future. + +Within a template, a push configuration section looks like this: + +```javascript +{ + "push": { + // ... push configuration here + } +} +``` + +## Configuration Reference + +There are many configuration options available for the builder. They are +segmented below into two categories: required and optional parameters. Within +each category, the available configuration keys are alphabetized. + +### Required + +* `name` (string) - Name of the build configuration in the build service. + If this doesn't exist, it will be created (by default). + +### Optional + +* `address` (string) - The address of the build service to use. By default + this is `https://atlas.hashicorp.com`. + +* `base_dir` (string) - The base directory of the files to upload. This + will be the CWD when the build service executes your template. This + path is relative to the template. + +* `include` (array of strings) - Glob patterns to include relative to + the `base_dir`. If this is specified, only files that match the include + pattern are included. + +* `exclude` (array of strings) - Glob patterns to exclude relative to + the `base_dir`. + +* `token` (string) - An access token to use to authenticate to the build + service. For Atlas, you can retrieve this access token in your account + section by clicking your account name in the upper right corner. + +* `vcs` (bool) - If true, Packer will detect your VCS (if there is one) + and only upload the files that are tracked by the VCS. This is useful + for automatically excluding ignored files. This defaults to true. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index b686bb515..a403ad336 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -13,6 +13,7 @@