MenuX

⌘K

Docs

Product

Apps Databases Platform Security & Compliance

Pricing Customers Company

Install CLI

Deploy with CI/CD

To make it easier to deploy on Aptible—whether you're migrating from another platform or deploying your first application—we offer integrations with several continuous integration services.

Deploying with Git
Deploying with Docker

If your team is already using a Git-based deployment workflow, deploying your app to Aptible should be relatively straightforward.

Deploying with Git

Prerequisites

To deploy to Aptible via Git, you must have a public SSH key associated with your account. We recommend creating a robot user to manage your deployment:

Create a Robots custom Aptible role in your Aptible organization. Grant it "Read" and "Manage" permissions for the environment where you would like to deploy.
Invite a new robot user with a valid email address (for example, deploy@yourdomain.com) to the Robots role.
Sign out of your Aptible account, accept the invitation from the robot user's email address, and set a password for the robot's Aptible account.
Generate a new SSH key pair to be used by the robot user, and don't set a password: ssh-keygen -t ed25519 -C "your_email@example.com"
Register the SSH Public Key with Aptible for the robot user.

GitHub ActionsCircleCITravis CIGitLab CI

Configuring SSH

To deploy to Aptible via GitHub Actions, you must first create an encrypted secret for your repository with the following values:

Name: APTIBLE_GIT_SSH_KEY
Value: The contents of the SSH Private Key created in the previous step.

Configuring the Environment

You also need to set environment variables on your repository with the name of your Aptible environment and app, in APTIBLE_ENVIRONMENT and APTIBLE_APP, respectively. You can configure these the same way that the SSH key was added to the workflow, via workflow secrets on the GitHub Workflow.

Configuring the Workflow

Finally, you must configure the workflow to deploy your application to Aptible:

on:
  push:
    branches: [ main ]

env:
  APTIBLE_ENVIRONMENT: ${{ secrets.APTIBLE_ENVIRONMENT }}
  APTIBLE_APP: ${{ secrets.APTIBLE_APP }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: webfactory/ssh-agent@v0.5.4
        with:
          ssh-private-key: ${{ secrets.APTIBLE_GIT_SSH_KEY }}
      - name: Deploy to Aptible
        run: |
          ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
          git remote add aptible git@beta.aptible.com:${APTIBLE_ENVIRONMENT}/${APTIBLE_APP}.git
          git push aptible ${GITHUB_SHA}:master

Let’s break down how this works. We begin by defining when the workflow should run (when a push is made to the main branch), and the environment variables we need (our Aptible environment and app names):

on:
  push:
    branches: [ main ]

env:
  APTIBLE_ENVIRONMENT: ${{ secrets.APTIBLE_ENVIRONMENT }}
  APTIBLE_APP: ${{ secrets.APTIBLE_APP }}

Next, we run a pair of common steps that check out a shallow clone of our repository and configure the environment’s SSH agent using the private key we provided.

steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: webfactory/ssh-agent@v0.5.4
        with:
          ssh-private-key: ${{ secrets.APTIBLE_GIT_SSH_KEY }}

Finally, we add our SSH private key to the workflow environment, configure a new remote for our repository on Aptible’s platform, and push our branch to Aptible:

steps:
      . . .
      - name: Deploy to Aptible
        run: |
          ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
          git remote add aptible git@beta.aptible.com:${APTIBLE_ENVIRONMENT}/${APTIBLE_APP}.git
          git push aptible ${GITHUB_SHA}:master

From there, the procedure for a Dockerfile-based deployment remains the same!

Configuring SSH

To deploy to Aptible via CircleCI, add your SSH Private Key via the CircleCI Dashboard with the following values:

Hostname: beta.aptible.com
Private Key: The contents of the SSH Private Key created in the previous step.

Configuring the Environment

You also need to set environment variables on your project with the name of your Aptible environment and app, in APTIBLE_ENVIRONMENT and APTIBLE_APP, respectively. You can add these to your project using environment variables on the Circle CI dashboard.

Configuring the Deployment

Finally, you must configure the Circle CI project to deploy your application to Aptible:

version: 2.1

jobs:
  git-deploy:
    docker:
      - image: debian:latest
    filters:
      branches:
        only:
          - circle-deploy
    steps:
      # Add your private key to your repo: https://circleci.com/docs/2.0/configuration-reference/#add-ssh-keys
      - checkout
      - run:
          name: Git push and deploy to Aptible
          command: |
            apt-get update && apt-get install -y git openssh-client
            ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
            git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
            git push aptible $CIRCLE_SHA1:master

workflows:
  version: 2
  deploy:
    jobs:
      - git-deploy

Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the circle-deploy branch):

jobs:
  git-deploy:
    docker:
      - image: debian:latest
    filters:
      branches:
        only:
          - circle-deploy

The most important part of this configuration is the value of the command key under the run step. Here we add our SSH private key to the Circle CI environment, configure a new remote for our repository on Aptible’s platform, and push our branch to Aptible:

jobs:
  git-deploy:
    # # #
    steps:
      - checkout
      - run:
          name: Git push and deploy to Aptible
          command: |
            apt-get update && apt-get install -y git openssh-client
            ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
            git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
            git push aptible $CIRCLE_SHA1:master

From there, the procedure for a Dockerfile-based deployment remains the same!

Configuring SSH

To deploy to Aptible via Travis CI, add your SSH Private Key via the Travis CI repository settings with the following values:

Name: APTIBLE_GIT_SSH_KEY
Value: The base64-encoded contents of the SSH Private Key created in the previous step.

⚠️ Warning
The SSH private key added to the Travis CI environment variable must be base64-encoded.

Configuring the Environment

Configuring the Deployment

Finally, you must configure the Travis CI project to deploy your application to Aptible:

language: generic
sudo: true

services:
  - docker

jobs:
  include:
    - stage: push
      if: branch = travis-deploy
      addons:
        ssh_known_hosts: beta.aptible.com
      before_script:
        - mkdir -p ~/.ssh
        # to save it, cat <<KEY>> | base64 and save that in secrets
        - echo "$APTIBLE_GIT_SSH_KEY" | base64 -d > ~/.ssh/id_rsa
        - chmod 0400 ~/.ssh/id_rsa
        - eval "$(ssh-agent -s)"
        - ssh-add ~/.ssh/id_rsa
        - ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts

      script:
        - git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
        - git push aptible $TRAVIS_COMMIT:master

Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the travis-deploy branch) and where we are going to deploy (so we add beta.aptible.com as a known host):

# # #
jobs:
  include:
    - stage: push
      if: branch = travis-deploy
      addons:
        ssh_known_hosts: beta.aptible.com

The Travis CI configuration then allows us to split our script into two parts, with the before_script configuring the Travis CI environment to use our SSH key:

      # Continued from above
      before_script:
        - mkdir -p ~/.ssh
        # to save it, cat <<KEY>> | base64 and save that in secrets
        - echo "$APTIBLE_GIT_SSH_KEY" | base64 -d > ~/.ssh/id_rsa
        - chmod 0400 ~/.ssh/id_rsa
        - eval "$(ssh-agent -s)"
        - ssh-add ~/.ssh/id_rsa
        - ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts

Finally, our script block configures a new remote for our repository on Aptible’s platform, and pushes our branch to Aptible:

      # Continued from above
      script:
        - git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
        - git push aptible $TRAVIS_COMMIT:master

From there, the procedure for a Dockerfile-based deployment remains the same!

Configuring SSH

To deploy to Aptible via GitLab CI, add your SSH Private Key via the GitLab CI dashboard with the following values:

Key: APTIBLE_GIT_SSH_KEY
Value: The base64-encoded contents of the SSH Private Key created in the previous step.

⚠️ Warning
The SSH private key added to the GitLab CI environment variable must be base64-encoded.

Configuring the Environment

Configuring the Deployment

Finally, you must configure the GitLab CI pipeline to deploy your application to Aptible:

image: debian:latest

git_deploy_job:
  only:
    - gitlab-deploy
  before_script:
    - apt-get update && apt-get install -y git
    # taken from: https://docs.gitlab.com/ee/ci/ssh_keys/
    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'
    - eval $(ssh-agent -s)
    # to save it, cat <<KEY>> | base64 and save that in secrets
    - echo "$DEMO_APP_APTIBLE_GIT_SSH_KEY" | base64 -d | tr -d '
' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
  script:
    - |
      ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
      git remote add aptible git@beta.aptible.com:$DEMO_APP_APTIBLE_ENVIRONMENT/$DEMO_APP_APTIBLE_APP.git
      git push aptible $CI_COMMIT_SHA:master

Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the gitlab-deploy branch), and then we define the before_script that will configure SSH in our job environment:

  # . . .
  before_script:
    - apt-get update && apt-get install -y git
    # taken from: https://docs.gitlab.com/ee/ci/ssh_keys/
    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'
    - eval $(ssh-agent -s)
    - echo "$DEMO_APP_APTIBLE_GIT_SSH_KEY" | base64 -d | tr -d '
' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh

Finally, our script block configures a new remote for our repository on Aptible’s platform, and pushes our branch to Aptible:

  # Continued from above
  script:
    - |
      ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
      git remote add aptible git@beta.aptible.com:$DEMO_APP_APTIBLE_ENVIRONMENT/$DEMO_APP_APTIBLE_APP.git
      git push aptible $CI_COMMIT_SHA:master

From there, the procedure for a Dockerfile-based deployment remains the same!

Deploying with Docker

Prerequisites

To deploy to Aptible with a Docker image via a CI integration, you should create a robot user to manage your deployment:

Create a Robots custom Aptible role in your Aptible organization. Grant it "Read" and "Manage" permissions for the environment where you would like to deploy.
Invite a new robot user with a valid email address (for example, deploy@yourdomain.com) to the Robots role.
Sign out of your Aptible account, accept the invitation from the robot user's email address, and set a password for the robot's Aptible account.

GitHub ActionsTravis CI

Some of the below instructions and more information can also be found on the Github Marketplace page for the Deploy to Aptible Action.

Configuring the Environment

To deploy to Aptible via GitHub Actions, you must first create encrypted secrets for your repository with Docker registry and Aptible credentials:

DOCKERHUB_USERNAME and DOCKERHUB_TOKEN: The credentials for your private Docker registry (in this case, DockerHub).
APTIBLE_USERNAME and APTIBLE_PASSWORD: The credentials for the robot account created to deploy to Aptible.

Configuring the Workflow

Additionally, you will need to set some environment variables within the GitHub Actions workflow:

IMAGE_NAME: The Docker image you wish to deploy from your Docker registry.
APTIBLE_ENVIRONMENT: The name of the Aptible environment acting as the target for this deployment.
APTIBLE_APP: The name of the app within the Aptible environment we are deploying with this workflow.

Configuring the Workflow

Finally, you must configure the workflow to deploy your application to Aptible:

on:
  push:
      branches: [ main ]

env:
  IMAGE_NAME: user/app:latest
  APTIBLE_ENVIRONMENT: "my_environment"
  APTIBLE_APP: "my_app"


jobs:
  deploy:
    runs-on: ubuntu-latest

      # Allow multi platform builds.
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v2

      # Allow use of secrets and other advanced docker features.
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      # Log into Docker Hub
      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # Build image using default dockerfile.
      - name: Build and push
        uses: docker/build-push-action@v3
        with:
          push: true
          tags: ${{ env.IMAGE_NAME }}

      - name: Deploy to Aptible
        uses: aptible/aptible-deploy-action@v1
        with:
          username: ${{ secrets.APTIBLE_USERNAME }}
          password: ${{ secrets.APTIBLE_PASSWORD }}
          environment: ${{ env.APTIBLE_ENVIRONMENT }}
          app: ${{ env.APTIBLE_APP }}
          docker_img: ${{ env.IMAGE_NAME }}
          private_registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
          private_registry_password: ${{ secrets.DOCKERHUB_TOKEN }}

From there, you can review our resources for Direct Docker Image Deployments!

Configuring the Environment

To define how the Docker image is built and deployed, you’ll need to set a few additional variables:

APTIBLE_USERNAME and APTIBLE_PASSWORD: The credentials for the robot account created to deploy to Aptible.
APTIBLE_DOCKER_IMAGE: The name of the Docker image you wish to deploy to Aptible.

If you are using a private registry to store your Docker image, you also need to specify credentials to be passed to Aptible:

APTIBLE_PRIVATE_REGISTRY_USERNAME: The username of the account that can access the private registry containing the Docker image.
APTIBLE_PRIVATE_REGISTRY_PASSWORD: The password of the account that can access the private registry containing the Docker image.

Configuring the Deployment

Finally, you must configure the workflow to deploy your application to Aptible:

language: generic
sudo: true

services:
  - docker

jobs:
  include:
  - stage: build-and-test
    script: |
      make build
      make test
  - stage: push
    if: branch = main
    script: |
      # login to your registry
      docker login \
        -u $APTIBLE_PRIVATE_REGISTRY_EMAIL \
        -p $APTIBLE_PRIVATE_REGISTRY_PASSWORD
      # push your docker image to your registry
      make push

      # download the latest aptible cli and install it
      wget https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/latest/aptible-toolbelt_latest_debian-9_amd64.deb && \
        dpkg -i ./aptible-toolbelt_latest_debian-9_amd64.deb && \
        rm ./aptible-toolbelt_latest_debian-9_amd64.deb

      # login and deploy your app
      aptible login \
        --email "$APTIBLE_USERNAME" \
        --password "$APTIBLE_PASSWORD"
      aptible deploy \
        --environment "$APTIBLE_ENVIRONMENT" \
        --app "$APTIBLE_APP"

Let’s break down how this works. The script for the build-and-test stage does what it says on the label: It builds our Docker image as runs tests on it, as we’ve defined in a Makefile.

Then, script from the push stage pushes our image to the Docker registry:

# login to your registry
docker login \
  -u $APTIBLE_PRIVATE_REGISTRY_EMAIL \
  -p $APTIBLE_PRIVATE_REGISTRY_PASSWORD
# push your docker image to your registry
make push

Finally, it installs the Aptible CLI in the Travis CI build environment, logs in to Aptible, and deploys your Docker image to the specified envrionment and app:

# download the latest aptible cli and install it
wget https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/aptible-toolbelt-latest_amd64.deb && \
  dpkg -i ./aptible-toolbelt-latest_amd64.deb && \
  rm ./aptible-toolbelt-latest_amd64.deb

# login and deploy your app
aptible login \
  --email "$APTIBLE_USERNAME" \
  --password "$APTIBLE_PASSWORD"
aptible deploy \
  --environment "$APTIBLE_ENVIRONMENT" \
  --app "$APTIBLE_APP"

From there, you can review our resources for Direct Docker Image Deployments!

Getting Started

Core Concepts

Reference

How-to Guides

Troubleshooting

Deploy with CI/CD

Deploying with Git

Prerequisites

Configuring SSH

Configuring the Environment

Configuring the Workflow

Configuring SSH

Configuring the Environment

Configuring the Deployment

Configuring SSH

Configuring the Environment

Configuring the Deployment

Configuring SSH

Configuring the Environment

Configuring the Deployment

Deploying with Docker

Prerequisites

Configuring the Environment

Configuring the Workflow

Configuring the Workflow

Configuring the Environment

Configuring the Deployment

Deploy with CI/CD

Product

Resources

Support

Company