CI Templates API Reference

Alpine templates

.fdo.container-build@alpine

Checks for a pre-existing alpine container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-alpine-image:
  extends: .fdo.container-build@alpine
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is alpine:latest and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@alpine template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/alpine/latest:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@alpine template to access or use this image.

.fdo.container-build@alpine@x86_64

Alias to .fdo.container-build@alpine.

This template is deprecated, no need to specify the architecture anymore.

.fdo.container-build@alpine@aarch64

Checks for a pre-existing alpine container image for the aarch64 processor architecture and builds it if it does not yet exist.

This template requires runners with the aarch64 tag.

See .fdo.container-build@alpine for details.

This template is deprecated. It is best if users use the non architecture specific variant and define themselves the tags to chose the runner.

.fdo.distribution-image@alpine

alpine template that pulls the alpine image from the registry based on FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@alpine.

This template sets image: to the generated image. You may override this.

Example:

my-alpine-test:
  extends: .fdo.distribution-image@alpine
  variables:
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@alpine.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “alpine”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@alpine instead.

.fdo.suffixed-image@alpine

alpine template that pulls the alpine image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@alpine.

This template sets image: to the generated image. You may override this.

Example:

my-alpine-test:
  extends: .fdo.distribution-image@alpine
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@alpine.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@alpine.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “alpine”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@alpine instead.

Arch templates

.fdo.container-build@arch

Checks for a pre-existing arch container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-arch-image:
  extends: .fdo.container-build@arch
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is arch:rolling and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@arch template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/arch/rolling:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@arch template to access or use this image.

.fdo.container-build@arch@x86_64

Alias to .fdo.container-build@arch.

This template is deprecated, no need to specify the architecture anymore.

.fdo.distribution-image@arch

arch template that pulls the arch image from the registry based on FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@arch.

This template sets image: to the generated image. You may override this.

Example:

my-arch-test:
  extends: .fdo.distribution-image@arch
  variables:
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@arch.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “arch”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@arch instead.

.fdo.suffixed-image@arch

arch template that pulls the arch image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@arch.

This template sets image: to the generated image. You may override this.

Example:

my-arch-test:
  extends: .fdo.distribution-image@arch
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@arch.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@arch.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “arch”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@arch instead.

CentOS templates

.fdo.container-build@centos

Checks for a pre-existing centos container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-centos-image:
  extends: .fdo.container-build@centos
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_VERSION: '7'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The centos version to build, e.g. ‘7’, ‘8’

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is centos:$FDO_DISTRIBUTION_VERSION and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@centos template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/centos/$FDO_DISTRIBUTION_VERSION:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@centos template to access or use this image.

.fdo.container-build@centos@x86_64

Alias to .fdo.container-build@centos.

This template is deprecated, no need to specify the architecture anymore.

.fdo.distribution-image@centos

centos template that pulls the centos image from the registry based on FDO_DISTRIBUTION_VERSION and FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@centos.

This template sets image: to the generated image. You may override this.

Example:

my-centos-test:
  extends: .fdo.distribution-image@centos
  variables:
     FDO_DISTRIBUTION_VERSION: '7'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The centos version to build, e.g. ‘7’, ‘8’

The value supplied must be the same as supplied in .fdo.container-build@centos.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@centos.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “centos”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@centos instead.

.fdo.suffixed-image@centos

centos template that pulls the centos image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@centos.

This template sets image: to the generated image. You may override this.

Example:

my-centos-test:
  extends: .fdo.distribution-image@centos
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@centos.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@centos.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “centos”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@centos instead.

Debian templates

.fdo.container-build@debian

Checks for a pre-existing debian container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-debian-image:
  extends: .fdo.container-build@debian
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_VERSION: 'bullseye'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The debian version to build, e.g. ‘bullseye’, ‘buster’, ‘sid’, ‘stretch’

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is debian:$FDO_DISTRIBUTION_VERSION and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@debian template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/debian/$FDO_DISTRIBUTION_VERSION:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@debian template to access or use this image.

.fdo.container-build@debian@x86_64

Alias to .fdo.container-build@debian.

This template is deprecated, no need to specify the architecture anymore.

.fdo.container-build@debian@aarch64

Checks for a pre-existing debian container image for the aarch64 processor architecture and builds it if it does not yet exist.

This template requires runners with the aarch64 tag.

See .fdo.container-build@debian for details.

This template is deprecated. It is best if users use the non architecture specific variant and define themselves the tags to chose the runner.

.fdo.qemu-build@debian@x86_64

Checks for a pre-existing debian container image usable on KVM-enabled runners and builds it if it does not yet exist.

This template requires runners with the kvm tag.

The final images provide an /app/vmctl helper to start and stop the VM and execute commands on the VM. The script installs the vm alias for SSH operations:

Example:

my-debian-test:
  extends: .fdo.distribution-image@debian
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - /app/vmctl start
    # copy workdir to the vm
    - |
      scp -r $PWD vm:
    - /app/vmctl exec meson builddir
    # copy build results back to the container image
    - scp vm:$CI_PROJECT_NAME/builddir .
    - /app/vmctl stop

See .fdo.container-build@debian for details.

.fdo.distribution-image@debian

debian template that pulls the debian image from the registry based on FDO_DISTRIBUTION_VERSION and FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@debian.

This template sets image: to the generated image. You may override this.

Example:

my-debian-test:
  extends: .fdo.distribution-image@debian
  variables:
     FDO_DISTRIBUTION_VERSION: 'bullseye'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The debian version to build, e.g. ‘bullseye’, ‘buster’, ‘sid’, ‘stretch’

The value supplied must be the same as supplied in .fdo.container-build@debian.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@debian.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “debian”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@debian instead.

.fdo.suffixed-image@debian

debian template that pulls the debian image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@debian.

This template sets image: to the generated image. You may override this.

Example:

my-debian-test:
  extends: .fdo.distribution-image@debian
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@debian.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@debian.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “debian”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@debian instead.

Fedora templates

.fdo.container-build@fedora

Checks for a pre-existing fedora container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-fedora-image:
  extends: .fdo.container-build@fedora
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_VERSION: '35'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The fedora version to build, e.g. ‘35’, ‘34’

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is fedora:$FDO_DISTRIBUTION_VERSION and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@fedora template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/fedora/$FDO_DISTRIBUTION_VERSION:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@fedora template to access or use this image.

.fdo.container-build@fedora@x86_64

Alias to .fdo.container-build@fedora.

This template is deprecated, no need to specify the architecture anymore.

.fdo.container-build@fedora@aarch64

Checks for a pre-existing fedora container image for the aarch64 processor architecture and builds it if it does not yet exist.

This template requires runners with the aarch64 tag.

See .fdo.container-build@fedora for details.

This template is deprecated. It is best if users use the non architecture specific variant and define themselves the tags to chose the runner.

.fdo.qemu-build@fedora@x86_64

Checks for a pre-existing fedora container image usable on KVM-enabled runners and builds it if it does not yet exist.

This template requires runners with the kvm tag.

The final images provide an /app/vmctl helper to start and stop the VM and execute commands on the VM. The script installs the vm alias for SSH operations:

Example:

my-fedora-test:
  extends: .fdo.distribution-image@fedora
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - /app/vmctl start
    # copy workdir to the vm
    - |
      scp -r $PWD vm:
    - /app/vmctl exec meson builddir
    # copy build results back to the container image
    - scp vm:$CI_PROJECT_NAME/builddir .
    - /app/vmctl stop

See .fdo.container-build@fedora for details.

.fdo.distribution-image@fedora

fedora template that pulls the fedora image from the registry based on FDO_DISTRIBUTION_VERSION and FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@fedora.

This template sets image: to the generated image. You may override this.

Example:

my-fedora-test:
  extends: .fdo.distribution-image@fedora
  variables:
     FDO_DISTRIBUTION_VERSION: '35'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The fedora version to build, e.g. ‘35’, ‘34’

The value supplied must be the same as supplied in .fdo.container-build@fedora.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@fedora.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “fedora”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@fedora instead.

.fdo.suffixed-image@fedora

fedora template that pulls the fedora image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@fedora.

This template sets image: to the generated image. You may override this.

Example:

my-fedora-test:
  extends: .fdo.distribution-image@fedora
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@fedora.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@fedora.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “fedora”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@fedora instead.

openSUSE templates

.fdo.container-build@opensuse

Checks for a pre-existing opensuse container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-opensuse-image:
  extends: .fdo.container-build@opensuse
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_VERSION: 'tumbleweed'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The opensuse version to build, e.g. ‘tumbleweed’

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is opensuse:$FDO_DISTRIBUTION_VERSION and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@opensuse template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/opensuse/$FDO_DISTRIBUTION_VERSION:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@opensuse template to access or use this image.

.fdo.container-build@opensuse@x86_64

Alias to .fdo.container-build@opensuse.

This template is deprecated, no need to specify the architecture anymore.

.fdo.container-build@opensuse@aarch64

Checks for a pre-existing opensuse container image for the aarch64 processor architecture and builds it if it does not yet exist.

This template requires runners with the aarch64 tag.

See .fdo.container-build@opensuse for details.

This template is deprecated. It is best if users use the non architecture specific variant and define themselves the tags to chose the runner.

.fdo.distribution-image@opensuse

opensuse template that pulls the opensuse image from the registry based on FDO_DISTRIBUTION_VERSION and FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@opensuse.

This template sets image: to the generated image. You may override this.

Example:

my-opensuse-test:
  extends: .fdo.distribution-image@opensuse
  variables:
     FDO_DISTRIBUTION_VERSION: 'tumbleweed'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The opensuse version to build, e.g. ‘tumbleweed’

The value supplied must be the same as supplied in .fdo.container-build@opensuse.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@opensuse.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “opensuse”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@opensuse instead.

.fdo.suffixed-image@opensuse

opensuse template that pulls the opensuse image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@opensuse.

This template sets image: to the generated image. You may override this.

Example:

my-opensuse-test:
  extends: .fdo.distribution-image@opensuse
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@opensuse.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@opensuse.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “opensuse”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@opensuse instead.

Ubuntu templates

.fdo.container-build@ubuntu

Checks for a pre-existing ubuntu container image and builds it if it does not yet exist.

If an image with the same version or suffix exists in the upstream project’s registry, the image is copied into this project’s registry. If no such image exists, the image is built and pushed to the local registry.

Example:

my-ubuntu-image:
  extends: .fdo.container-build@ubuntu
  variables:
     FDO_DISTRIBUTION_PACKAGES: 'curl wget gcc valgrind'
     FDO_DISTRIBUTION_VERSION: '21.04'
     FDO_DISTRIBUTION_TAG: '2020-03-20'

Reserved by this template:

image: do not override
script: do not override

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The ubuntu version to build, e.g. ‘21.04’, ‘20.04’

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

FDO_UPSTREAM_REPO: The GitLab project path to the upstream project

FDO_REPO_SUFFIX: The repository name suffix to use, see below.

FDO_DISTRIBUTION_PACKAGES: Packages to install as a space-separated single string, e.g. “curl wget”. These packages must be available in the default distribution repositories; use FDO_DISTRIBUTION_EXEC followed by the distribution-specific command(s) to enable additional repositories and/or install additional packages.

FDO_DISTRIBUTION_EXEC: An executable run after the installation of the FDO_DISTRIBUTION_PACKAGES

FDO_FORCE_REBUILD: If set, the image will be built even if it exists in the registry already

FDO_BASE_IMAGE: By default, the base image to start with is ubuntu:$FDO_DISTRIBUTION_VERSION and all dependencies are installed on top of that base image. If FDO_BASE_IMAGE is given, it references a different base image to start with. This image usually requires the full registry path, e.g. registry.freedesktop.org/projectGroup/projectName/repo_suffix:tag-name

FDO_EXPIRES_AFTER: If set, enables an expiration time on the image to aid the garbage collector in deciding when an image can be removed. This should be set for temporary images that are not intended to be kept forever. Allowed values are e.g. 1h (one hour), 2d (two days) or 3w (three weeks).

FDO_CACHE_DIR: If set, the given directory is mounted as /cache when FDO_DISTRIBUTION_EXEC is run. This can allow for passing of cache values between build jobs (if run on the same runner). You should not usually need to set this, it defaults to /cache from the host and thus enables cache sharing by default.

FDO_USER: If set, the given unix username is used when running containers based on this image instead of root. If the username is not created by the FDO_DISTRIBUTION_EXEC script, it will be created automatically. Note that $HOME will be set to /home/$FDO_USER, if the user is created manually by FDO_DISTRIBUTION_EXEC script it is important to ensure that directory is created as well and writable by the user.

The resulting image will be pushed to the local registry.

If FDO_REPO_SUFFIX was specified, the image path is $CI_REGISTRY_IMAGE/$FDO_REPO_SUFFIX:$FDO_DISTRIBUTION_TAG. Use the .fdo.suffixed-image@ubuntu template to access or use this image.

If FDO_REPO_SUFFIX was not specified, the image path is $CI_REGISTRY_IMAGE/ubuntu/$FDO_DISTRIBUTION_VERSION:$FDO_DISTRIBUTION_TAG. Use the .fdo.distribution-image@ubuntu template to access or use this image.

.fdo.container-build@ubuntu@x86_64

Alias to .fdo.container-build@ubuntu.

This template is deprecated, no need to specify the architecture anymore.

.fdo.container-build@ubuntu@aarch64

Checks for a pre-existing ubuntu container image for the aarch64 processor architecture and builds it if it does not yet exist.

This template requires runners with the aarch64 tag.

See .fdo.container-build@ubuntu for details.

This template is deprecated. It is best if users use the non architecture specific variant and define themselves the tags to chose the runner.

.fdo.qemu-build@ubuntu@x86_64

Checks for a pre-existing ubuntu container image usable on KVM-enabled runners and builds it if it does not yet exist.

This template requires runners with the kvm tag.

The final images provide an /app/vmctl helper to start and stop the VM and execute commands on the VM. The script installs the vm alias for SSH operations:

Example:

my-ubuntu-test:
  extends: .fdo.distribution-image@ubuntu
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - /app/vmctl start
    # copy workdir to the vm
    - |
      scp -r $PWD vm:
    - /app/vmctl exec meson builddir
    # copy build results back to the container image
    - scp vm:$CI_PROJECT_NAME/builddir .
    - /app/vmctl stop

See .fdo.container-build@ubuntu for details.

.fdo.distribution-image@ubuntu

ubuntu template that pulls the ubuntu image from the registry based on FDO_DISTRIBUTION_VERSION and FDO_DISTRIBUTION_TAG. This template must be provided the same variable values as supplied in .fdo.container-build@ubuntu.

This template sets image: to the generated image. You may override this.

Example:

my-ubuntu-test:
  extends: .fdo.distribution-image@ubuntu
  variables:
     FDO_DISTRIBUTION_VERSION: '21.04'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_DISTRIBUTION_VERSION

This variable is required

The ubuntu version to build, e.g. ‘21.04’, ‘20.04’

The value supplied must be the same as supplied in .fdo.container-build@ubuntu.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@ubuntu.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “ubuntu”

Note

If you used FDO_REPO_SUFFIX when building the container, use .fdo.suffixed-image@ubuntu instead.

.fdo.suffixed-image@ubuntu

ubuntu template that pulls the ubuntu image from the registry based on FDO_REPO_SUFFIX. This template must be provided the same variable values as supplied in .fdo.container-build@ubuntu.

This template sets image: to the generated image. You may override this.

Example:

my-ubuntu-test:
  extends: .fdo.distribution-image@ubuntu
  variables:
     FDO_REPO_SUFFIX: 'some/path'
     FDO_DISTRIBUTION_TAG: '2020-03-20'
  script:
    - meson builddir
    - ninja -C builddir test

Variables:

FDO_REPO_SUFFIX

This variable is required

The repository name suffix.

The value supplied must be the same as supplied in .fdo.container-build@ubuntu.

FDO_DISTRIBUTION_TAG

This variable is required

String to identify the image in the registry.

The value supplied must be the same as supplied in .fdo.container-build@ubuntu.

FDO_DISTRIBUTION_IMAGE

This variable is set by this template and should be treated as read-only

Path to the registry image

FDO_DISTRIBUTION_NAME

This variable is set by this template and should be treated as read-only

Set to the string “ubuntu”

Variables provided by this template should be considered read-only.

Note

If you did not use FDO_REPO_SUFFIX when building the container, use .fdo.distribution-image@ubuntu instead.