Handling Build Artifacts in Jenkins

In continuous integration and continuous delivery (CI/CD) pipelines, building your source code is only half the battle. Once your code compiles and passes its tests, it produces deployable files such as JARs, WARs, ZIP files, or Docker images. These compiled outputs are known as build artifacts. Managing, archiving, and retrieving these artifacts efficiently is a core responsibility of any robust Jenkins pipeline.

This guide explains how to handle build artifacts in Jenkins from the ground up. You will learn how to archive artifacts locally within Jenkins, follow industry best practices, and avoid common pitfalls that can crash your Jenkins server due to disk space exhaustion.

What are Build Artifacts?

An artifact is a file generated during the build step of your software development lifecycle. Examples of artifacts include:

• Java Applications: .jar or .war files.
• Web Applications: Compiled HTML, CSS, and JavaScript bundles (often zipped).
• Mobile Apps: .apk or .ipa files.
• Reports: Test coverage reports, security scan results, and API documentation.

Without artifact management, these files remain inside the temporary Jenkins workspace. When a new build starts, or when the workspace is cleaned, these valuable files are permanently deleted. Archiving ensures they are saved securely outside the workspace for deployment, testing, or historical auditing.

The Artifact Archiving Workflow

The diagram below illustrates how Jenkins processes and stores build artifacts during a pipeline execution:

[ Source Code Repository ]
       │
       ▼ (Step 1: Checkout Code)
[ Jenkins Workspace (Temporary) ]
       │
       ▼ (Step 2: Build - e.g., "mvn package")
[ Compiled Artifact (target/app.jar) ]
       │
       ▼ (Step 3: archiveArtifacts Step)
[ Jenkins Controller Storage ] (Stored securely per build)
       │
       ▼ (Step 4: Optional Release)
[ External Repository (Nexus / Artifactory / S3) ]

How to Archive Artifacts in Jenkins Pipelines

Jenkins provides a built-in step called archiveArtifacts to preserve files. This step is typically executed in the post section of a Declarative Pipeline, ensuring that artifacts are only saved if the build succeeds.

Declarative Pipeline Example

Below is a complete, production-ready Jenkins Declarative Pipeline demonstrating how to compile a Java application using Maven and archive the resulting JAR file:

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                // Code checkout happens here automatically
                p { "Checking out source code..." }
            }
        }

        stage('Build & Package') {
            steps {
                // Compile and package the Java application
                sh 'mvn clean package -DskipTests'
            }
        }
    }

    post {
        success {
            // Archive the generated JAR file
            archiveArtifacts artifacts: 'target/*.jar', fingerprint: true, onlyIfSuccessful: true
        }
        always {
            // Clean up workspace to save disk space
            cleanWs()
        }
    }
}

Understanding the archiveArtifacts Parameters

• artifacts: A Ant-style path pattern specifying which files to archive. For example, target/*.jar archives all JAR files in the target directory. You can also use double asterisks for recursive searches: **/*.war.
• fingerprint: When set to true, Jenkins generates an MD5 checksum of the archived files. This allows you to track where this specific artifact is used across other downstream Jenkins jobs.
• onlyIfSuccessful: Ensures that Jenkins only archives artifacts if the build completes successfully. This prevents broken or incomplete builds from wasting storage space.

Real-World Use Cases

1. Multi-Stage Pipelines (Build once, deploy many)

In professional CI/CD pipelines, you build your artifact once in the "Build" stage, archive it, and then copy it into subsequent stages (like "Staging" and "Production") for deployment. This guarantees that the exact same binary tested in staging is deployed to production, eliminating environmental inconsistencies.

2. Generating Downloadable Release Assets

QA teams, product managers, and clients often need access to the latest build without digging into command-line tools. Archiving artifacts makes them directly downloadable from the Jenkins build dashboard GUI.

Common Mistakes and How to Avoid Them

1. Archiving Everything

The Mistake: Using wildcard patterns like **/* to archive the entire workspace, including intermediate compiler files, node_modules, or temporary build caches.

The Solution: Be highly specific with your patterns. Only archive target binaries, such as target/my-app.jar or dist/index.html.

2. Running Out of Disk Space

The Mistake: Keeping every single artifact from every historical build forever. This will quickly fill up the Jenkins controller's hard drive, leading to system crashes.

The Solution: Configure "Discard Old Builds" in your job settings or pipeline options. Limit the number of builds and artifacts to keep (e.g., keep only the last 10 builds).

options {
    // Keep only the last 10 builds and their artifacts
    buildDiscarder(logRotator(numToKeepStr: '10', artifactNumToKeepStr: '10'))
}

3. Using Jenkins as a Long-term Binary Repository

The Mistake: Treating Jenkins as a permanent storage system for production releases.

The Solution: Jenkins is an automation engine, not a storage engine. Use Jenkins to archive artifacts temporarily. For long-term storage and production release management, publish your artifacts to dedicated repository managers like Sonatype Nexus, JFrog Artifactory, or AWS S3.

Interview Notes for DevOps Engineers

• Question: What is the difference between archiving artifacts inside Jenkins and publishing them to a repository manager like Nexus?
• Answer: Jenkins archiving is local to the Jenkins controller, designed for temporary storage, build history tracking, and passing files between build stages. Nexus/Artifactory are dedicated artifact repositories designed for high-availability, dependency management, versioning, and secure distribution to production environments.
• Question: How do you prevent Jenkins from running out of disk space due to build artifacts?
• Answer: Implement a strict log and artifact rotation policy using the buildDiscarder option in pipelines, use workspace cleanup steps (cleanWs()) post-build, and offload production-ready artifacts to external object storage (like AWS S3) immediately after creation.
• Question: What is artifact fingerprinting in Jenkins?
• Answer: Fingerprinting records the MD5 checksum of an artifact. Jenkins tracks this checksum across different jobs, making it easy to see which pipeline produced the artifact and which downstream pipeline deployed it.

Summary

Handling build artifacts correctly is vital for maintaining a clean, efficient, and reliable CI/CD infrastructure. By using the archiveArtifacts step in your declarative pipelines, restricting archived files to essential binaries, and enforcing strict build discarding policies, you can ensure your team always has access to the correct deployable files without compromising your Jenkins server's performance.

In the next topic, we will explore how to integrate Jenkins with external artifact repositories like Sonatype Nexus and JFrog Artifactory to establish a production-grade deployment pipeline.