Companion Git Repositories are deprecated and will be disabled November 3rd, 2025. You should now provide your Procfile and .aptible.yml files within your container image when deploying from Docker Image.

​
What is a Companion Git Repository?

Initially, Aptible supported deploying applications only via Git: users provided a Dockerfile, and the platform built the app image. In June 2017, we added support for deploying pre-built Docker images. At that time, if you needed to define processes or migrations using a Procfile or .aptible.yml, those files still had to be provided via Git in addition to your image. This pattern of providing configuration files via Git is known as a Companion Git Repository. In January 2018, we added support to provide Procfiles and .aptible.yml within Docker Images. At that time we indicated that the Companion Git Repository was deprecated, but gave an indefinite timeline for customers to migrate.

​
Why are Companion Git Repositories being deprecated now?

This deployment style was only necessary for roughly six months. In retrospect, we didn’t sufficiently encourage migration. Over the past seven years, many customers, both new and existing, have unintentionally continued using Companion Git Repositories, which can result in unpredictable behavior when updating services or lifecycle hooks. In order to continue to modernize and simplify our platform, we’re finally taking action to require customers to stop using this deprecated feature.

​
What impact will this have on me?

Hopefully, none! Fewer than 2% of apps hosted on Aptible use a Companion Git Repository, and even fewer include a Procfile or .aptible.yml. Since there is no functional difference in how these files are provided, migrating off the deprecated method will not affect app behavior. We have notified impacted customers directly and provided them with a list of affected apps. Unless you migrate, impacted apps will fail to deploy. You can temporarily continue using the feature by acknowledging the deprecation. See “Using Companion Git Repositories during deprecation.”

​
How do I migrate?

To check if your deployments rely on a Companion Git Repository, inspect your deploy logs for the phrase companion git repo detected. This will indicate if a Procfile or .aptible.yml is being used:
Found Procfile in git directory: using services from Procfile (companion git repo detected) Found .aptible.yml in git directory: using hook commands from .aptible.yml (companion git repo detected)
  1. If you have a Procfile or .aptible.yml file in your repository, you must embed it in your Docker image. To do so, follow the instructions at Procfiles and .aptible.yml with Direct Docker Image Deploy.
  2. If you modified your image to add the Procfile or .aptible.yml, rebuild your image and push it again.
  3. Deploy using aptible deploy as documented in using aptible deploy, with one exception: the first time you deploy (you don’t need to do it again), add the --git-detach flag to this command.
In some cases, you’ll find neither your Procfile or .aptible.yml are being provided via a Companion Git Repo, and you can skip right to step 3.

​
Using Companion Git Repositories during deprecation

During the deprecation period, any attempt to deploy using a Companion Git Repository will fail with this message:
You are attempting to deploy with a Companion Git Repository, but this functionality is being deprecated. You CAN continue to use this feature for a limited time…
You can either immediately migrate using the instructions above, or configure your App to bypass this validation: 
aptible config:set --app $app_handle APTIBLE_ACK_COMPANION_REPO_DEPRECATION=true
By setting the configuration variable APTIBLE_ACK_COMPANION_REPO_DEPRECATION, you will be able to continue to deploy this App using your Companion Git Repo, but only until it is disabled platform wide on November 3rd, 2025!