Migrating from Jenkins to LocalCI

Jenkins is deprecated and will be removed in Artemis 11, planned for March 2027 (see Planned removals in Artemis 11). This guide describes how to move an installation that runs Jenkins with LocalVC to LocalCI with LocalVC, the Integrated Code Lifecycle. Do the migration on a 10.x release, and upgrade to Artemis 11 only afterwards, so that you never change the build system and the major version in one step.

⚠️

Warning:

This guide is derived from the Artemis source code and the existing documentation. It has not yet been validated by migrating a production installation. Rehearse every step on a copy of your database and a staging server first, and keep the backups described below.

What changes and what stays

LocalVC is the version control system of both setups. Only the build system changes, so the migration is much smaller than it looks.

Stays as it is	Changes
Git repositories, their URLs and access rules (LocalVC)	Builds run on Artemis build agents in Docker containers, no longer on Jenkins
Users, courses, exercises, participations, results and feedback	How an exercise is built: from the exercise's build phases and Docker image, no longer from a stored Jenkinsfile
Authentication, including LDAP, SAML2 and OIDC	How build agents authenticate to the repositories: per-build clone tokens or SSH keys, no longer a shared username and password
Exam and course configuration	Where instructors edit the build: the structured build plan editor, no longer a pipeline script

Jenkins also kept a copy of the users and a build plan per participation. LocalCI has neither, so there is nothing to synchronize and no Jenkins user to maintain.

Before you start

1. Read the Integrated Code Lifecycle setup and the security guide on repository authentication. Plan the build agent capacity with the scaling guide. Builds that took one Jenkins node can need several build agents with LocalCI, and the build queue is shared state, so a multi-node installation also needs a distributed data provider.
2. Check feature parity for your languages in the language table and the feature support table. LocalCI supports every language that Jenkins supports and more. Sequential test runs for Kotlin and static code analysis for Swift, which used to exist only with Jenkins, are available with LocalCI from the release that contains them. Check the feature table of your target version before you migrate.
3. Find customizations. These do not carry over automatically:
   • Instructors who edited the pipeline script of an exercise in the script-based build plan editor. LocalCI ignores a stored Jenkinsfile and runs the build phases of the exercise. Such an exercise needs its script rebuilt as build phases, see Step 4.
   • Overridden Jenkins templates under src/main/resources/templates/jenkins, and changes to the pipeline for network access. LocalCI uses the build phases templates and the Docker flags of the exercise instead.
   • Custom Docker images used by Jenkins agents. LocalCI runs the Docker image configured for the exercise on the build agents. Such an image must be available to the build agents in a registry or loaded on each Docker build agent, built for the architecture of the build agents (artemis.continuous-integration.image-architecture, amd64 by default), and contain all build dependencies. A Docker build agent that runs in a container needs registry credentials that the container can read, because a login on the host does not reach the container by default. The Kubernetes runner needs an entry in image-pull-secrets for a private registry, see build runners.
4. Choose the time. Migrate between teaching periods, never during an exam or in the days before a deadline.
5. Take backups of the Artemis database, the Artemis configuration and the LocalVC repository directory. Keep the Jenkins server untouched until the end of the migration.

Migration steps

1. Prepare the LocalCI infrastructure

• Provision the hosts for the build agents. A build agent needs Docker, access to your Artemis nodes through the distributed data provider, and network access to the registry that serves the images. Start Artemis nodes with the buildagent profile for dedicated build agents, or let the core nodes build too.
• Pull the Docker images for your languages on the build agents so that the first builds do not wait for downloads. Builds fail when a build agent cannot reach the registry.
• Choose the distributed data provider. A single node can use the local provider. Several nodes need Hazelcast or Redis.

2. Rehearse on staging

1. Restore a copy of your production database on a staging server and start it with the new configuration of Step 3.
2. Complete Steps 3 to 5 on staging. Keep notes of every exercise that needed manual work, since you repeat that in production.

3. Change the configuration

Change these on every Artemis node. The profile names are the Spring profiles in spring.profiles.active.

Setting	Jenkins with LocalVC	LocalCI with LocalVC
Profiles	jenkins, localvc	localci, localvc, and buildagent on nodes that build
jenkins.*	Jenkins URL, credentials and tokens	Remove the whole block
artemis.version-control.build-agent-git-username and build-agent-git-password	The shared credential pair for Jenkins	Remove both. A node that runs LocalCI refuses to start while either is set.
Jenkins-specific keys under artemis.continuous-integration	Used, for example the build timeout	Remove them. They are marked as Jenkins specific in application-artemis.yml.
Build agent authentication	The shared credential pair above	Per-build clone tokens or SSH keys, see Build agent authentication
Distributed data	Not needed on a single node	Set artemis.distributed-data.provider to Hazelcast, Redis or Local, see distributed data

The remaining LocalCI options (concurrent builds, Docker flags, the maximum build duration and the bulk trigger limits) are described in Configure Build Management.

Start one node and check the log. The startup fails early and with a clear message when a profile or a credential does not match. Open the administration area and confirm that the build agents appear and that the build queue is empty.

4. Check every exercise

LocalCI reads the build phases and the Docker image from the build configuration of the exercise. When an exercise has none, LocalCI uses the defaults of its programming language and project type, which is what a new exercise gets. Therefore most exercises that used the default Jenkins template need no change, and exercises with a customized pipeline do.

For each course that you migrate:

1. Open the exercise's build plan editor and look at the phases and the Docker image. Compare them with what the old pipeline did.
2. Rebuild customized pipelines as build phases. A phase has a name, a script, an inclusion condition (Always or After due date), a toggle that says whether tests are expected, the paths of its result files, and a toggle to run it at the end even after a failure. See Adapt Build Phases.
3. Trigger the template and the solution build of the exercise. The template should fail its tests and the solution should pass them, exactly as before.
4. Push a change to a student repository of a test account and confirm that the result arrives, including the feedback and, where you use it, static code analysis.

Ask the instructors of the affected courses to do this for their exercises, since they know what the pipeline was meant to do. There is currently no list of the exercises that had a customized Jenkins pipeline, see the open points below.

5. Verify under load

On staging, trigger the builds of one large exercise (bulk builds) and watch the build queue, the build agent utilization and the failure rate. Adjust the number of build agents and the concurrent builds per agent until the queue drains at an acceptable speed.

6. Cut over production

1. Announce a maintenance window to instructors.
2. Stop the nodes, back up the database, and start them with the configuration of Step 3.
3. Run the checks of Steps 4 and 5 on a few exercises that instructors prepared.
4. Keep Jenkins running and read-only for as long as you need the old build logs and plans. Do not delete anything there yet.

Existing results, feedback and grades stay unchanged. New pushes are built by LocalCI.

7. Decommission Jenkins

Wait until a full term has run on LocalCI without a rollback, then:

1. Disable the Jenkins jobs and the Server Notification Plugin webhook.
2. Remove the Jenkins server, its reverse proxy entry, its credentials and its users.
3. Remove the leftover Jenkins configuration and the Jenkins nginx and firewall rules.

Rolling back

Until you upgrade to Artemis 11 you can go back, because Artemis 10 still supports Jenkins:

1. Stop all nodes and restore the backups of the database, the configuration and the repositories.
2. Start the nodes with the old profiles and the old configuration.

⚠️

Warning:

Restoring the backups discards everything that happened after they were taken: new exercises, results, feedback, student commits and every other change in the database and the repositories. Announce the data loss to instructors and students before you do it, and take a fresh backup of the current state first, so that nothing is lost for good.

What instructors need to know

• The build of an exercise is a list of phases with a Docker image, edited with Edit build plan on the exercise detail page. There is no pipeline script.
• Builds run in Docker containers on build agents, so a test that needs a package or a tool needs a Docker image that contains it.
• Builds of exams run with the highest priority in the build queue.

Open points for the maintainers

These need a decision or a check before this guide is final.

• Validate the whole procedure with a copy of a production database that has Jenkins exercises, including old student participations.
• Decide whether Artemis should migrate customized Jenkinsfiles to build phases automatically, or only report which exercises have one. The guide currently makes this manual.
• Decide what happens to old Jenkins build logs and build plan links on results created before the migration.
• Add an administration view or a query that lists the exercises with a stored Jenkinsfile, so that operators do not have to find them by hand.