q8sctl user guideBuild images in CI

Build images in CI

You can build Docker images in your Continuous Integration (CI) pipelines using q8sctl’s init command. This command allows you to build and push images to a container registry directly from your CI environment (e.g. GitHub Actions, GitLab CI, Jenkins).

Building in CI ensures that your images are always up-to-date for all collaborators, eliminating the need for each user to build images locally, or even to have Docker installed on their machines.

When to trigger builds

You should consider building new images in your CI pipeline in the following scenarios:

  • Changes to Q8Sproject file: If you modify the Q8Sproject file, which defines the execution targets and their dependencies, it should trigger a new build to reflect these changes.
  • New branches: When a new branch is created, building images ensures that the branch has its own set of images based on the current state of the Q8Sproject file.

Usage with GitHub Actions

Here is an example of a GitHub Actions workflow that builds and pushes a Docker image using q8sctl:

.github/workflows/build-and-push.yml
name: Q8S Build and Push
run-name: Job Images Build and Push
 
on:
  create:
    # Trigger when a new branch is created
  push:
    paths:
      - "Q8Sproject" # Run only if Q8Sproject file changes
  workflow_dispatch:
    # Allow manual triggering of the workflow
 
env:
  # Use docker.io for Docker Hub if empty
  REGISTRY: ghcr.io
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      # This is used to complete the identity challenge
      # with sigstore/fulcio when running outside of PRs.
      id-token: write
 
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
 
      # Install the cosign tool except on PR
      # https://github.com/sigstore/cosign-installer
      - name: Install cosign
        if: github.event_name != 'pull_request'
        uses: sigstore/cosign-installer@v3.5.0
        with:
          cosign-release: "v2.2.4"
 
      # Set up BuildKit Docker container builder to be able to build
      # multi-platform images and export cache
      # https://github.com/docker/setup-buildx-action
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3.0.0
 
      # Login against a Docker registry except on PR
      # https://github.com/docker/login-action
      - name: Log into registry ${{ env.REGISTRY }}
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3.0.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
 
      - name: Install Q8S CLI
        run: python -m pip install q8s>=0.12.0
 
      - name: Prepare Q8S buildx cache and bake files
        run: q8sctl init
 
      - name: Build images with bake
        uses: docker/bake-action@v6
        with:
          workdir: .q8s_cache/
          source: "."
          push: true

Automation with pre-commit hooks

You can also automate the image building process using pre-commit hooks. By configuring a pre-commit hook to run the q8sctl init --images command on specific git actions (e.g., post-checkout), you can ensure that repository is in sync with the images build in CI. Here is an example configuration for the .pre-commit-config.yaml file:

.pre-commit-config.yaml
repos:
  - repo: https://github.com/qubernetes-dev/q8s-kernel
    rev: v0.11.0
    hooks:
      - id: q8sctl
        stages: [post-checkout]
        args: ["init", "--images"]
        always_run: true

Example repository

An repository containing a working example of quantum routines and the above GitHub Actions workflow can be found at: qubernetes-dev/example-with-ci.

Run programsOverview