Skip to content
These docs are still under construction and may contain outdated references to Earthly and/or broken links.
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Jenkins

Overview

Jenkins has multiple modes of operation, and each of them require some consideration when installing EarthBuild. These modes include:

  • Standalone, dedicated runners

  • Ephemeral cloud runners

Compatibility

EarthBuild has been tested with Jenkins in a standalone runner configuration, and using the Docker Cloud provider.

Resources

Setup (Standalone)

This should not differ in any meaningful way from the steps outlined in the overview.

Setup (Docker Cloud)

Assuming you are following the steps outlined in the overview, here are the additional things you need to configure:

Dependencies

Ensure that the Docker Cloud provider is installed and has a Docker daemon available. The Cloud provider does not provide a daemon.

Installation

You'll need to create your own runner image. Heres an example of what this might look like, when basing your runner off our earthbuild/earthbuild image:

VERSION is the version of the Jenkins runner to install.

Configuration

Set DOCKER_HOST to point at a Docker daemon. This can easily be passed through by checking "Expose Docker Host" in the runner template configuration.

Additional Notes

earth misinterprets the Jenkins environment as a terminal. To hide the ANSI color codes, set NO_COLOR to 1.

Example

To try this locally you need a Jenkins server, a Docker daemon for the Docker Cloud plugin to schedule agents on, and a repository containing an Earthfile and a Jenkinsfile.

A local Jenkins server

Create a network, start a Docker-in-Docker daemon on it, then start Jenkins:

Then get the unlock password, and install the docker-plugin and docker-workflow plugins through the setup wizard:

Configure the Docker Cloud to point at tcp://docker:2375, using the runner image from Installation above as the agent template.

A pipeline to run

Add a Jenkinsfile alongside your Earthfile. A minimal starting point:

Configuring the build

Jenkins Dashboard with "New Item" highlighted
  • Choose "Pipeline", give it a name (we chose "test"), and click "OK".

Setting up a new build named test, configured as a Jenkins pipeline
  • Scroll down to the "Pipeline" section.

  • Make the following changes:

  • Choose "Pipeline script from SCM" for the Definition

  • Choose "Git" as the SCM, once the option appears

  • Set the repository URL to your own repository, the one containing the Earthfile and Jenkinsfile

  • Set the branch specifier to */main

Configuring all the SCM options for the build
  • Once those changes are made, click "Save". Jenkins will navigate to the Pipelines' main page. Once there, click "Build Now"

Jenkins Dashboard for the example build, with "Build Now" highlighted
  • Find the build in your build history, and watch it go!

Console output in Jenkins from the test build

Notes

To tear the environment down and start over:

TLS

The example purposely runs a Docker-In-Docker (DIND) container without TLS for simplicity. This is not a recommended configuration. Configuring TLS inside Docker.

To allow the docker client to access a daemon protected with TLS, you will need to add Jenkins credentials. Add the client key, certificate, and the server CA certificate as a credential. In our example, using the Docker Cloud provider, you can add them by choosing "Manage Jenkins", then "Manage Nodes and Clouds", and finally "Configure Clouds". Then, choose the cloud to configure for TLS, and click the "Add" button here:

Configuring Docker credentials in Jenkins

Also, ensure that you are using the correct port for TLS. In this image of our example cloud, we are using port 2375, which is traditionally the insecure port for a docker daemon. In a TLS environment, docker expects port 2376.

If you are using an external earth-buildkitd with Jenkins, you should be using mTLS. You will need to add the keys and certificates used there as credentials too.

Last updated