Dpl

This version of the README documents dpl v2, the next major version of dpl. The README for dpl v1, the version that is currently used in production on Travis CI can be found here.

Dpl is command line tool for deploying code, html, packages, or build artifacts to various service providers.

It is tightly integrated into Travis CI's deployment integration, but also used, and recommended by others, such as GitLab.

It is maintained by Travis CI, largely community driven, and it has existed since 2013. If you find support your preferred deployment target missing, please do not hesitate to get in touch, and we'll help you add it.

Table of Contents

• Requirements
• Installation
• Usage
• Maturity Levels
• Supported Providers
• Contributing to Dpl
• Old Issues
• Code of Conduct
• License
• Credits

Requirements

Dpl requires Ruby 2.3 or later.

Depending on the deployment target dpl might require additional runtimes (e.g. Go, Node.js, or Python) to be installed. It also might require sudo access in order to install a Debian package.

Dpl is generally optimized for usage on Linux systems.

Installation

This version of dpl is currently released as an alpha preview release. In order to install it, add the --pre flag:

gem install dpl --pre

Usage

Dpl is meant and optimized for usage in ephemeral build environments, such as Travis CI, or any other CI/CD pipeline.

Dpl is integrated to Travis CI's build configuration and build script compilation tooling, so all you need to do is add the proper configuration to your .travis.yml file. Please refer to the documentation for details.

For usage outside of Travis CI dpl can be executed as follows. Please refer to the respective providers for details.

dpl [provider] [options]

Dpl can be used locally, e.g. on your development machine, but it might leave artifacts that may alter the behaviour of your system. If you encounter this behaviour and it presents a serious issue to you then please open an issue.

Cleaning up the Git working directory

Dpl v1 has cleaned up the Git working directory by default, using git stash --all. The default for this option has been changed in dpl v2, and users now need to opt in to cleaning up any left over artifacts from the build process by passing the option --cleanup.

The status of the working directory is relevant only to providers that package and push it to the respective remote service (e.g. heroku when using the api strategy, package registry providers, etc.). Most providers will either push the latest Git commit, or pull code from a remote repository.

Maturity Levels

In order to communicate the current development status and maturity of dpl's support for a particular service the respective provider is marked with one of the following maturity levels, according to the given criteria:

• dev - the provider is in development (initial level)
• alpha - the provider is fully tested
• beta - the provider has been in alpha for at least a month, and successful real-world production deployments have been observed
• stable - the provider has been in beta for at least a month, and there are no open issues that qualify as critical (such as deployments failing, documented functionality broken, etc)

Supported Providers

Dpl supports the following providers:

• Anynines
• AWS CloudFormation
• AWS Code Deploy
• AWS ECR
• AWS Elastic Beanstalk
• AWS Lambda
• AWS OpsWorks
• AWS S3
• Azure Web Apps
• Bintray
• Bluemix Cloud Foundry
• Boxfuse
• Cargo
• Chef Supermarket
• Cloud Files
• Cloud Foundry
• Cloud66
• Convox
• Datica
• Engineyard
• Firebase
• Flynn
• Git (push)
• GitHub Pages
• GitHub Pages (API)
• GitHub Releases
• Gleis
• Google App Engine
• Google Cloud Store
• Hackage
• Hephy
• Heroku API
• Heroku Git
• Launchpad
• Netlify
• npm
• nuget
• OpenShift
• Packagecloud
• Puppet Forge
• PyPI
• Rubygems
• Scalingo
• Script
• Snap
• Surge
• TestFairy
• Transifex

Anynines

Support for deployments to Anynines is in alpha. Please see Maturity Levels for details.

Usage: dpl anynines [options]

Summary:

  Anynines deployment provider

Description:

  tbd

Options:

  --username USER         anynines username (type: string, required)
  --password PASS         anynines password (type: string, required)
  --organization ORG      anynines organization (type: string, required)
  --space SPACE           anynines space (type: string, required)
  --app_name APP          Application name (type: string)
  --buildpack PACK        Buildpack name or Git URL (type: string)
  --manifest FILE         Path to the manifest (type: string)

Common Options:

  --cleanup               Clean up build artifacts from the Git working directory before the deployment
  --run CMD               Commands to execute after the deployment finished successfully (type: array
                          (string, can be given multiple times))
  --help                  Get help on this command

Examples:

  dpl anynines --username user --password pass --organization org --space space
  dpl anynines --username user --password pass --organization org --space space --app_name app

Options can be given via env vars if prefixed with ANYNINES_. E.g. the option --password can be given as ANYNINES_PASSWORD=<password>.

AWS CloudFormation

Usage: dpl cloudformation [options]

Summary:

  AWS CloudFormation deployment provider

Description:

  tbd

Options:

  --access_key_id ID           AWS Access Key ID (type: string, required)
  --secret_access_key KEY      AWS Secret Key (type: string, required)
  --region REGION              AWS Region to deploy to (type: string, default: us-east-1)
  --template STR               CloudFormation template file (type: string, required, note: can be either a
                               local path or an S3 URL)
  --stack_name NAME            CloudFormation Stack Name. (type: string, required)
  --stack_name_prefix STR      CloudFormation Stack Name Prefix. (type: string)
  --[no-]promote               Deploy changes (default: true, note: otherwise a change set is created)
  --role_arn ARN               AWS Role ARN (type: string)
  --sts_assume_role ARN        AWS Role ARN for cross account deployments (assumed by travis using given AWS
                               credentials). (type: string)
  --capabilities STR           CloudFormation allowed capabilities (type: array (string, can be given multiple
                               times), known values: CAPABILITY_IAM, CAPABILITY_NAMED_IAM,
                               CAPABILITY_AUTO_EXPAND, see:
                               https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html)
  --[no-]wait                  Wait for CloutFormation to finish the stack creation and update (default: true)
  --wait_timeout SEC           How many seconds to wait for stack creation and update. (type: integer, default:
                               3600)
  --create_timeout SEC         How many seconds to wait before the stack status becomes CREATE_FAILED (type:
                               integer, default: 3600, note: valid only when creating a stack)
  --parameters STR             key=value pairs or ENV var names (type: array (string, can be given multiple
                               times))
  --output_file PATH           Path to output file to store CloudFormation outputs to (type: string)

Common Options:

  --cleanup                    Clean up build artifacts from the Git working directory before the deployment
  --run CMD                    Commands to execute after the deployment finished successfully (type: array
                               (string, can be given multiple times))
  --help                       Get help on this command

Examples:

  dpl cloudformation --access_key_id id --secret_access_key key --template str --stack_name name
  dpl cloudformation --access_key_id id --secret_access_key key --template str --stack_name name --region region

Options can be given via env vars if prefixed