Configure Runtime Image and Toolchain

This document introduces how to specify a custom Docker image in a Job using the container field to meet requirements for specific language versions or specialized toolchains.

When the pre-installed toolchain on the hosted Runner does not meet project needs—such as requiring a specific language version, specialized dependencies, or a complete build environment—it is possible to specify a custom Docker image using the container field.

Configuration Instructions

Basic Usage of the container Field

# .gitcode/workflows/java-build.yml
stages:
  build:
    name: Build
    jobs:
      name: maven-build
      runs-on: [ubuntu-24, x64, medium]
      container:
        image: maven:3.9-eclipse-temurin-21     # Use Maven + JDK21 image
      steps:
        - run: mvn clean package

Full Configuration of the container Field

jobs:
  custom-env:
    name: custom-env
    runs-on: [ubuntu-24, x64, medium]
    container:
      image: myregistry.example.com/myapp-builder:2.0
      credentials:
        username: ${{ secrets.REGISTRY_USERNAME }}
        password: ${{ secrets.REGISTRY_PASSWORD }}
      env:
        BUILD_MODE: release
        JAVA_HOME: /usr/lib/jvm/java-21
      volumes:
        - /data/cache:/cache
      options: --hostname builder-node --memory 12g
    steps:
      - run: make release

Field	Description
image	Full name of the Docker image (including tag)
credentials	Authentication for private image repository, referencing Secret
env	Environment variables inside the container
volumes	Mounted volumes (Host → Container)
options	Additional Docker run parameters

Custom Image Building

If public images cannot meet the requirements, you can build your own image and push it to the image repository:

# Dockerfile.ci
FROM ubuntu:24.04

RUN apt-get update && apt-get install -y \
    build-essential cmake git \
    python3.12 python3-pip \
    nodejs npm \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install pytest black mypy

WORKDIR /workspace

docker build -t myregistry.example.com/ci-builder:1.0 -f Dockerfile.ci .
docker push myregistry.example.com/ci-builder:1.0

# .gitcode/workflows/custom.yml
jobs:
  full-build:
    name: full-build
    runs-on: [ubuntu-24, x64, medium]
    container:
      image: myregistry.example.com/ci-builder:1.0
      credentials:
        username: ${{ secrets.REGISTRY_USERNAME }}
        password: ${{ secrets.REGISTRY_PASSWORD }}
    steps:
      - run: pytest
      - run: make build