Configure Runtime Image and Toolchain

Applicable Scenarios

When the pre-installed toolchain on the hosted Runner does not meet the project requirements—such as needing a specific language version, specialized dependencies, or a complete build environment—a custom Docker image can be specified using the container field.

Configuration Instructions

Basic Usage of the container Field

# Configure Runtime Image and Toolchain
stages:
  - 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:
  - 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 registry, referencing a 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:
  - 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