Setup your CI

Setting up your CI

Your CI is your "source of truth" for successful builds. Your goal: Everyone trusts a "green" CI build is solid.

Typically your CI runs on a devops platform such as ADO, GitHub, GitLab, or similar offerings. Your CI build pipeline most commonly uses features of the platform (such as "actions" for GitHub), but you may prefer other options such as Jenkins, and similiar.

Configuring your build in CI

When using GitHub, a simple starting point is ci-earthly-gradle.yml or ci-earthly-maven.yml This project includes a workflows for Gradle and Maven in the Earthly container.

If you use GitLab, read about the equivalent pipelines in GitLab CI/CD, or for Jenkins in Pipeline.

When publishing your project, consider Publishing Java packages with Maven for GitHub, or equivalent for other CI systems. Do not publish from local builds. Seriously, relying on local publishing of artifacts will lead to headaches and problems, and back to it worked on my machine issues.

For GitHub, note the limitations of Download from Github Package Registry without authentication.

Working with your devops platform

Several devops platforms provides tooling for remote work without leaving the command line, or helpful in scripts such as GitHub's "Pages" feature (which uses the gh tool in your CI pipeline):

Some examples:

• ADO — az
• GitHub — gh
• GitLab — glab

What does a devops platform do when you push code changes? It varies depending on platform features and your project configuration. A good example is this discussion from GitHub.

Save your CI artifacts

It is helpful to preserve your build artifacts from CI, for example, to download built jars from different CI runs for comparing their behavior between commits without needing to rebuild locally, and also to confirm that your local build makes the same jars as CI does.

The "Build with Gradle" and "Build with Maven" CI workflows each provide a download named "jars", and the Maven build a "site" download.

There are services to provide links to the most recent build artifacts. One example is nightly.link (this is not an endorsement). You can use these links in your README.md or share as makes sense. An example is downloading the Maven-built jar from this project.

Tips

• Ignore edits to README.md and similar files in our code repository. This is a simple edit to your CI workflow file:
  • GitHub

    on:
      push:
        paths-ignore:
          # Note the double asterisk; a single asterisk does not suffice
          - '**.md'

  • GitLab is more complex but you can also ignore README.md changes to avoid unnecessary CI runs.
• To disable ASCII colorizing printing as control sequences in CI, or Gradle trying to overwrite lines (control sequences make for hard-to-read CI logs), a simple approach is to use an environment setting:

  TERM=dumb

  This does not make sense for local builds, and your CI system (eg, GitHub) may manage this problem already
• With Gradle, use the --warning-mode=all flag for CI: this shows all warnings Gradle generates, not just a summary. See Showing or hiding warnings for details
• With Maven, use the --no-transfer-progress flag for CI: this avoids spamming CI logs with download progress messages

Going further

TODO: Placeholder section