6 JenkinsSetup

Itms edited this page 2024-08-20 18:40:42 +02:00

Table of Contents

• Overview
• Jenkins job settings
• Machines
• Jenkins host
• Linux autobuilder
• Windows autobuilder
• macOS autobuilder
• BSD autobuilder

We use Jenkins as our CI/CD platform. This page documents the modern version of its setup.

Overview

We use Jenkins Pipelines (https://www.jenkins.io/doc/book/pipeline/) to orchestrate our builds. All our pipelines are versioned under build/jenkins/pipelines. Extending and improving pipelines can be done through PRs, which allows the new version of the updated pipeline to be tested without breaking the existing CI.

However, new pipelines are not automatically detected: a new job must be manually created by a Jenkins administrator for each new pipeline file.

Jenkins job settings

The pipeline jobs are configured as follows.

• CI builds are Multibranch Pipelines. We have one Build pipeline for each supported platform, and extra analysis pipelines (static analysis, performance testing, ...).
• CD builds are Pipelines pointing to a specific branch (usually the main branch during the development cycle, and the upcoming release branch before a new release).
• We hold archived jobs for Phabricator CI, those are outdated and correspond to deleted Jenkinsfiles.

For CI builds:

1. Create a Multibranch Pipeline job.
2. For the Branch Source, use the Gitea repository, use the Jenkins token for access.
3. In Behaviours, Discover Only branches that are also not filed as PRs, and use Use the current pull request revision for PRs. Set Trust to Contributors for fork PRs.
4. Set Build Configuration mode to By Jenkinsfile, and specify the path for the pipeline script.
5. Add a periodic watch of 8 hours, just in case.
6. Use the default folder icon for a consistent appearance.
7. Expand Health Metrics and set Health of the primary branch as the only metric.

For the CD builds:

1. Create a Pipeline job.
2. Setup the build triggers depending on your use case. For the Nighlty Build, choose a @midnight periodic build.
3. In Pipeline, select Pipeline script from SCM. Use the git repository (unless you want to build from the nightly build, for instance in the Bundles Generation job).
4. Specifiy the branch to build with explicit syntax (e.g. refs/heads/future).
5. Set the Script Path to the pipeline script path.

Machines

Here are public details about the VMs our CI/CD runs on.

Jenkins host

The Jenkins host runs on Debian stable. Jenkins is provided through Jenkins official APT repository.

Needed plugins include (non-exhaustive):

• Pipeline + Docker Pipeline + Pipeline Graph View + Pipeline Stage View
• File Parameter
• Git Forensics
• Gitea
• JUnit
• Subversion
• Warnings as well as their dependencies.

Linux autobuilder

The Linux agent runs on Debian stable. It acts as a Docker host. The client that runs the Jenkins agent service has Docker capabilities.

Needed packages include:

• Headless JRE packages
• Docker packages

In Jenkins, the Linux build machine is labeled LinuxAgent. It is limited to 1 executor. It is run by launching a command (TODO: test SSH launch provided by plugin).

Windows autobuilder

The Windows agent runs on Windows Server.

Needed software include:

• Java
• TortoiseSVN (with tools added to PATH during install)
• Git for Windows (with Git LFS and tools added to PATH during install)
  • run git lfs install --system --skip-smudge after install
  • set core.eol to lf and core.autocrlf to input system-wide
• Python3 (with tools added to PATH during install)
• Visual Studio
• Vulkan SDK
• Transifex Client

In Jenkins, the Windows build machine is labeled WindowsAgent. It is limited to 1 executor. It has a dedicated data drive in which the distant workspace must be set. It is run by connecting it to the controller. It needs to set the environment variable JAVA_HOME to the latest installed jre directory under Program Files.

macOS autobuilder

The macOS agent is kindly provided by MacStadium as part of their Open-Source program. We thank them for their support. It runs on the oldest macOS version on which building the game is supported (High Sierra 10.13 at the time of writing).

Needed software include:

• Homebrew
• Subversion
• XCode
• Command Line Tools
• CMake
• ...

In Jenkins, the macOS build machine is labeled MacAgent. It is limited to 1 executor. It is run by launching a command (TODO: test SSH launch provided by plugin).

BSD autobuilder

We do not have a BSD builder yet, thus BSD support should be considered experimental.