Skip to main content

Creating container images for migrations

To integrate schema migrations into pipelines that deploy to container management systems (such as Kubernetes, AWS ECS, Google Cloud Run, etc.) it is recommended to create a dedicated container image per version that contains the migration tool (such as Atlas) and the relevant migration files.

In this guide we will demonstrate how to build a dedicated Docker image that includes Atlas and the relevant migrations files. We will demonstrate how to build this image as a GitHub Actions Workflow, but the same result can be achieved in any CI system.

Defining the Dockerfile

Suppose our project structure looks something like:

├── main.go
└── migrations
├── 20221031125934_init.sql
├── 20221031125940_add_users_table.sql
├── 20221031125948_add_products_table.sql
└── atlas.sum

Our goal is to build an image that contains:

  1. The migrations directory
  2. The Atlas binary

To do this we can build our container image with the official Atlas Docker image as the base layer.

To do this, our Dockerfile should be placed in the directory containing the migrations directory and will look something like this:

FROM arigaio/atlas:latest

COPY migrations /migrations

Verify our image

To test our new Dockerfile run:

docker build -t my-image .

Docker will build our image:

 => [internal] load build definition from Dockerfile                                          0.0s
=> => transferring dockerfile: 36B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [internal] load metadata for 0.0s
=> [internal] load build context 0.0s
=> => transferring context: 252B 0.0s
=> [1/2] FROM 0.0s
=> CACHED [2/2] COPY migrations /migrations 0.0s
=> exporting to image 0.0s
=> => exporting layers 0.0s
=> => writing image sha256:c928104de31fc4c99d114d40ea849ade917beae3df7ffe9326113b289939878e 0.0s
=> => naming to 0.0s

To verify Atlas can find your migrations directory and that its integrity is intact run:

docker run --rm migrations my-image migrate validate 

If no issues are found, no errors will be printed out.

Defining the GitHub Actions Workflow

Next, we define a GitHub Actions workflow that will build our container image and push it to the GitHub container repo ( on every push to our mainline branch:

name: Push Docker
- master
runs-on: ubuntu-latest
- uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
username: ${{ }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v3
push: true
file: ${{ matrix.file }}
tags:<repo name>:${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max

Save this file in your GitHub repository under the .github/workflows directory. After you push it to your mainline branch, you will see a run of the new workflow in the Actions tab of the repository.