​
Overview

This guide offers step-by-step instructions for implementing and customizing GitHub workflows to deploy preview apps on the Aptible platform. The workflows described in this documentation are included in this example repository, are ready for production, and can be adapted to suit your specific deployment requirements and integration needs.

​
Preview Deployment (preview.yml)

The preview.yml workflow automatically deploys a preview app for every pull request, enabling reviewers to test the changes introduced in the PR in a separate app in a selected Aptible environment. What this workflow does:
  1. Triggers automatically when pull requests are created or updated with new commits
  2. Creates a PostgreSQL database and a Redis database for the preview app
  3. Configures a new Aptible app configured with the necessary environment variables to connect to the databases from the previous step
  4. Builds and pushes a Docker image tagged with the PR number
  5. Deploys the application to Aptible using the image built in the previous step
  6. Creates an HTTPS endpoint for accessing the preview app

​
Preview Cleanup (deprovision_preview.yml)

The deprovision_preview.yml workflow handles the cleanup of preview resources when a pull request is closed. What this workflow does:
  1. Triggers when a pull request is closed (merged or rejected).
  2. Deprovisions the Aptible app and endpoint associated with the PR.
  3. Deprovisions the PostgreSQL and Redis databases created for the preview.

​
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:
  1. Create a “Robots” custom role in your Aptible organization, and grant it “Full Visibility” and “Deployment” permissions for the environment where you will be deploying.
  2. Invite a new robot user with a valid email address (for example, deploy@yourdomain.com) to the Robots role.
  3. 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.
  4. 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"
  5. Register the SSH Public Key with Aptible for the robot user.

​
Configuring the Environment

Add the following secrets in Github:
  • APTIBLE_ROBOT_PASSWORD: Password for your Aptible robot account
  • DOCKERHUB_USERNAME: Your Docker Hub username
  • DOCKERHUB_TOKEN: Access token for Docker Hub
  • DOCKERHUB_PASSWORD: Your Docker Hub password
Add the following variable in Github
  • APTIBLE_ROBOT_USERNAME: Email address of your Aptible robot account

​
Update the workflows and add them to your repository

  1. Update the environment variables:
    1. Replace preview-apps with your Aptible environment name.
    2. Replace aptible/deploy-demo-app with your Docker image name.
    3. Adjust the app name pattern if needed.
  2. Modify the database type, version, and name pattern as needed for your application.
  3. Update the tagging strategy if required in the Build and Push Docker images step.
  4. You can customize the workflow further by using different event types to trigger the workflows. The push and pull_request event documentation, in particular, includes practical examples for everyday use cases.