↓Skip to main content

Creating Container Images with Buildah and GitLab

·4 mins
Table of Contents

This article explains how to use Buildah with GitLab projects to create and publish container images. Buildah provides a less complex and more secure option for image creation than Docker and BuildKit.

How This Works #

Buildah is a command-line tool for building and publishing images that can run within a container. This means that you can run it on any development system as well as with any CI service, including GitHub Actions, GitLab Pipelines, Forgejo Actions and Tekton. Unlike Docker, it does not require network services or root access.

Buildah is part of the CNCF Podman Container Tools Project. This project also provides the Skopeo and Podman command-line tools. These tools can all run inside containers to automate operations for images.

GitLab includes a range of services for containers, so that you can build, store and use container images without needing any other systems.

By default, the GitLab Pipelines CI service uses containers. This means that it can run Buildah from within a container image, and then use the images that it builds as environments for other CI jobs.

GitLab instances can provide a container registry for each project that they host. You can use this registry as either a private store for images that you also push to other registries, or allow external access, so that this registry can act as the main store for the images that the project maintains.

The GitLab company offer a component for container scanning, so that you can add this feature in any GitLab Pipeline without any extra maintenance.

Set Up #

By default, projects on GitLab.com have the container registry feature enabled. If you use a private instance of GitLab, the administrators of the instance will need to configure container registry support.

To use Buildah with GitLab, you will need a .gitlab-ci.yml file in the root directory of the project. This provides the configuration for GitLab Pipelines. See below for an example.

Buildah can build container images from command-line instructions, or you can provide a configuration file in the Dockerfile format. See below for an example.

Once you push an image to the container registry for the project it becomes visible in the Web interface for GitLab. To view a project container registry in the GitLab Web interface, go to the project and select Deploy > Container registry.

Example .gitlab-ci.yml for GitLab #

This .gitlab-ci.yml file runs Buildah to create an image from the Containerfile, and then publishes the image that it builds to the container registry for the GitLab project. The CI job in this example only builds an image for the linux/amd64 platform, which is Linux on 64-bit Intel-compatible CPUs.

---
stages:
  - build

build-image-amd64:
  stage: build
  tags:
    - saas-linux-small-amd64
  image: quay.io/buildah/stable
  variables:
    FQ_IMAGE_NAME: "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
    STORAGE_DRIVER: vfs
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
  script:
    - buildah build --platform=linux/amd64 -t $FQ_IMAGE_NAME .
    - buildah push $FQ_IMAGE_NAME

Example Containerfile #

A Containerfile uses the Dockerfile format. The name indicates that this file may by used by standards-compliant tools like Buildah, and does not include any features that are specific to Docker.

FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:24-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 3000
USER node
CMD ["node", "dist/server.js"]

More on Container Image Formats #

Modern container tools support two formats for images: the OCI Image Specification format and the Docker Version 2 (Schema 2) format. The OCI specification formalises the older Docker format, which means that you can convert images between the formats. By default, Buildah creates images in the OCI format.

In some cases, you will need to build images in the Docker format. For example, you must build images with the Docker format to use the ONBUILD instruction.

To configure Buildah to create images in the Docker format, specify the Docker format with the --format=docker command-line option, or by setting the BUILDAH_FORMAT environment variable to docker.

GitLab container registries support both container image formats.

Resources #

Buildah #

GitLab #

Buildah on GitLab #