​

Using a Companion Git Repository

Some features supported by Aptible don’t map perfectly to Docker Images.

Specifically:

• Explicit Services (Procfiles)
• .aptible.yml

You can however use those along with Direct Docker Image Deploy by adding a Companion Git Repository.

​

Providing a Procfile

When you deploy directly from a Docker image, Aptible uses your image’s CMD to know which service command to run, you can create a separate App, or add a Procfile via a companion git repository.

To do so, create a new empty git repository containing a Procfile, and include all your services in the Procfile.

For example:

web: some-command
background: some-other-command

Then, push this git repository to your App’s Git Remote. Make sure to push to the master branch to trigger a deploy:

git push aptible master

When you do this, Aptible will use your Docker Image, but with the services defined in the Procfile.

​

Providing .aptible.yml

When you deploy directly from a Docker Image, you don’t normally use a git repository associated with your app. This means you don’t have a .aptible.yml file.

Generally, we recommend architecting your app to avoid the need for a .aptible.yml file when using Direct Docker Image deploy, but if you’d like to use one nonetheless, you can.

To do so, create new empty git repository containing a .aptible.yml file, and include your desired configuration in it.

For example:

before_release:
  - do some task
  - do other task

Then, push this git repository to your App’s Git Remote. Make sure to push to the master branch to trigger a deploy:

git push aptible master

When you do this, Aptible will use your Docker Image, and run respect the instructions from your .aptible.yml file, e.g. by running before_release commands;

​

Synchronizing git and Docker image deploys

If you are using a companion git repository to complement your Direct Docker Image deploy with a Procfile and/or a .aptible.yml file, you can synchronize their deploys.

To do so, push the updated Procfile and/or .aptible.yml files to a branch on Aptible that is not master. For example:

git push aptible master:update-the-Procfile

Pushing to a non-master will not trigger a deploy. Once that’s done, deploy normally using aptible deploy, but add the --git-commitish argument, like so:

aptible deploy \
  --app "$APP_HANDLE" \
  --docker-image "$DOCKER_IMAGE" \
  --git-commitish "$BRANCH"

This will trigger a new deployment using the image you provided, using the services from your Procfile and/or the instructions from your .aptible.yml file.

In the example above, $BRANCH represents the remote branch you pushed your updated files to. In the git push example above, that’s update-the-Procfile.

​

Disabling Companion Git Repositories

Companion Git Repositories can be disabled on dedicated stacks by request to Aptible Support. Once disabled, deploying using a companion git repository will result in a failed operation without any warning.

When Companion Git Repositories are disabled, your deploys must use either deploy with Git or Docker Image. Attempts to perform mixed-mode deployment using Companion Git Repositories will raise an error.

​

How-to

If you’d like to go down this route, first make sure that you are not using Companion Git Repositories in your deployments. There is a “Deploying with a Companion Git Repository is deprecated” warning when you deploy that will inform you if this is the case. If you find an app currently using a Companion Git Repository, you’ll need to get rid of it. To do so, follow the instructions in Migrating from Dockerfile Deploy. Once all your apps have been migrated, contact Aptible Support to disable the Companion Git Repositories.