We start with the simplest picture: what an artifact is, what a repository does, and what it means to connect the two to Jenkins.

Jenkins is a tool that automates building, testing, and delivering software. A typical pipeline fetches code, compiles it, runs tests, and produces output. That output is an artifact. Examples include a Java library packaged as a JAR file, a web application packaged as a WAR file, a Python wheel, a Node.js package, a Windows installer, a Helm chart, and a container image.

An artifact repository is a server that stores artifacts and dependencies, gives each one a name and version, and lets other systems upload and download them over the network. Well-known products in this space include JFrog Artifactory, Sonatype Nexus Repository, and the package registries offered by cloud and code-hosting platforms. Integration means teaching your Jenkins pipelines to talk to that repository: to publish what they build, to fetch what they depend on, and to record which build made which artifact.

flowchart LR
  A["Developer pushes code"] --> B["Jenkins builds and tests"]
  B --> C["Publish to the artifact repository"]
  C --> D["Deploy to test from the repository"]
  D --> E["Promote to the release repository"]
  E --> F["Deploy to production from the repository"]
    

Four jobs the integration does

To see why this integration matters, imagine delivering software without it, and follow what goes wrong.

The problem: the workspace is a temporary place

When Jenkins builds something, it works in a workspace, a folder on a build machine. Workspaces are cleaned, reused, and sometimes destroyed entirely, especially when agents are containers. If a team deploys by copying a file straight from a workspace to a server, several things can go wrong. The file may be overwritten by the next build a minute later. The machine may be gone by tomorrow. Nobody can tell which commit produced the file now running in production. And if the release fails, there is no old copy to put back.

The problem: rebuilding is not the same as re-running

Some teams rebuild the software at each stage: once for testing, again for staging, and again for production. But two builds of the same source code are not always identical. A dependency may have been updated between builds. A compiler may behave differently on another machine. The thing that was tested is then not the thing that ships. The safe rule is build once, deploy many: build a single artifact, store it, and deploy those same bytes to every environment.

The answer: a proper home for outputs

An artifact repository gives every build output a durable, versioned home with access control and a history. It also gives your builds a controlled source for dependencies, which speeds them up and makes them more reliable. Repository managers grew out of the Java world in the mid-2000s, where teams needed a shared place for Maven packages, and have since grown to serve almost every language and container format.

A handful of terms come up in every repository discussion. Learn them once here.

A few Jenkins words too

The controller is the main Jenkins server that plans the work. An agent is a worker machine or container that runs the commands. A pipeline is the ordered list of stages in a Jenkinsfile. A credential is a secret stored in Jenkins, such as the token that lets a pipeline upload to the repository. The repository is a separate system, often on its own servers, that both the controller and the agents can reach over the network.

Jenkins has some built-in ways to keep build outputs. They are useful, but they are not a replacement for a real repository.

Why the built-in tools are not enough

• They live and die with build history. When old builds are cleaned up to save space, their artifacts go too.
• They have no notion of versions or formats. A build tool cannot ask Jenkins for “library X, version 2.1”.
• They are tied to one Jenkins. Other tools and other servers cannot easily use them.
• They sit on the controller by default, which uses its disk and adds load to the most important machine in the system.
• They offer little access control per artifact, beyond who may view the build.

Almost every repository manager offers the same three building blocks, under slightly different names. Understanding them makes the rest of the topic easy.

flowchart TD
  A["Build tool asks the group repository"] --> B{"Is it in the hosted repository"}
  B -->|Yes| C["Return the internal artifact"]
  B -->|No| D{"Is it already cached in the proxy repository"}
  D -->|Yes| E["Return the cached copy"]
  D -->|No| F["Proxy fetches it from the public registry"]
  F --> G["Store a copy in the cache"]
  G --> E
    

Why the group is so useful

With a group repository, your build tools need to know only one address. Behind it, you can add, remove, or reorder repositories without changing any build. The order of members matters. If two members hold an artifact with the same name, the group usually answers from the first one that has it, and that behaviour has security consequences we return to in the security chapter.

Release and snapshot spaces

Many teams also split their hosted repositories by stage of maturity. A snapshot or development repository holds work in progress and may allow overwriting. A release repository holds finished versions and refuses to overwrite them. Splitting them means a mistake in a development build can never damage a published release.

There are many products that can play the repository role. Here is the general landscape, without favouring any of them.

What to look for

There is more than one way to connect Jenkins to a repository. Each has strengths, and many teams mix them.

Way one: the build tool does it

Most build tools already know how to publish and fetch. A Java build tool can deploy a package to a repository address. A JavaScript tool can publish to a registry. A Python tool can upload a wheel. A container tool can push an image. In this style, Jenkins only runs the command, and the tool does the talking. You need to give the tool the repository address and a credential. Jenkins provides the credential through its protected store and hands it to the command only for the moment it is needed.

Way two: a Jenkins plugin

Several repository vendors publish Jenkins plugins. A plugin can add pipeline steps such as “upload these files”, “download these files”, or “publish build information”, and can attach a build record to the artifact so that anyone looking at the repository can find the Jenkins build behind it. Plugins can also give you screens, links, and policy checks. The cost is one more plugin to install, secure, and keep updated.

Way three: plain web calls

Almost every repository accepts uploads and downloads over ordinary web requests. A pipeline step can call the repository’s interface directly, using a command-line web client and a credential. This works with any product and needs no plugin, but you must write and maintain the calls yourself, including error handling.

Let us walk through a typical pipeline, from a commit to a published artifact, and see where the repository fits.

Only publish what passed

A key rule is to publish only after the build and its tests have succeeded. Otherwise, the repository fills with broken artifacts that people might use by mistake. A second rule is to publish only from trusted branches. A build from an experimental branch or an outside contribution should not be able to write into your main development or release repository.

The repository is not only where builds end. It is also where they begin, by supplying the libraries a build needs.

Modern software depends on many outside libraries. A single project may pull in hundreds of packages, directly and indirectly. Without a repository, every build on every agent would download all of them from the public internet, again and again. With a proxy repository in between, each package is downloaded from outside once, cached, and then served locally to everyone.

Benefits of resolving through your own repository

How the build tool is pointed at it

Each build tool has a setting for where to fetch packages. You point it at the group repository’s address, and give it a credential if the repository needs one. Teams often keep this setting in a shared configuration file, provided to the agents through Jenkins, so that nobody has to edit each project. Jenkins can supply such a file through a config file feature, and can fill in the credential from its protected store.

Read access should be cheap and wide, write access narrow

Pull requests and feature branches need to read dependencies but must never publish. Give read-only access to the whole build fleet, and give write access only to the pipelines that publish. Repository products let you create separate tokens for these two purposes.

A repository is only as useful as the labels on its contents. Good versions and names make everything else easier.

Snapshots and releases

Many ecosystems distinguish two kinds of versions. A snapshot or development version is a moving target, meaning “the latest work towards version 2.4”. It may be overwritten by each new build. A release version is a fixed point, such as 2.4.0, and must never change. If a release version could be replaced with different contents, nobody could trust it, so good repositories refuse to overwrite it.

Semantic versioning in one paragraph

A popular convention, known as semantic versioning, uses three numbers: major, minor, and patch. A change to the major number signals changes that may break users. A change to the minor number adds features in a compatible way. A change to the patch number fixes bugs. Following such a rule lets consumers guess how risky an upgrade is, just by reading the number.

Tying versions to builds

Many pipelines build a version from the base version plus the Jenkins build number, for example 2.4.17, where 17 is the seventeenth build of that line. Others append the short commit id. Either way, the aim is that the version alone lets you find the exact build and the exact commit. Some teams also store the commit id, the build URL, and the branch name as properties on the artifact in the repository.

Naming conventions that pay off

• Use a company namespace in every package name, so your names cannot clash with public ones.
• Use lowercase and dashes consistently, so names are easy to type and search.
• Separate repositories by format and by maturity, such as one for release packages and one for snapshots.
• Avoid moving labels in production. A tag such as “latest” points at different contents on different days, which makes rollbacks and audits confusing.

Promotion is the idea that makes the whole integration worth having. An artifact earns its way to production by passing checks, without ever being rebuilt.

A promotion moves or copies an artifact from one repository to another, for example from staging to release, after it has passed a set of checks. The file itself is not rebuilt. Its contents do not change by a single byte. Only its location, and often a status label such as “tested” or “approved”, changes. The promotion is recorded in the repository’s history, so you can see who promoted what, and when.

sequenceDiagram
  participant J as Jenkins Pipeline
  participant S as Staging Repository
  participant Q as Quality Checks
  participant R as Release Repository
  participant D as Deployment Stage
  J->>S: Upload the build output with build information
  J->>Q: Run tests and security scans on the staged artifact
  Q-->>J: Results of the checks
  J->>R: Promote the same artifact if all checks passed
  D->>R: Download the promoted artifact
  D->>D: Deploy the exact same bytes
    

What promotion gives you

Who is allowed to promote

Promotion is a powerful action, since it decides what may reach production. Give the right to write into the release repository only to the promotion step, and let that step run only in a controlled pipeline, often behind a human approval. Ordinary build pipelines should not be able to write to the release repository at all.

Container images are the most common artifact today. They follow the same ideas, with a few special features of their own.

A container image is a packaged file system plus instructions for running an application. A registry is the repository that stores images. Many general-purpose repository managers also work as image registries, and there are registries designed only for images.

How a pipeline works with images

Points that are special to images

• Images are made of layers, so repeated pushes are fast when most layers are unchanged, and storage grows more slowly than file sizes suggest.
• Old layers pile up, and cleanup needs a garbage collection step in the registry.
• Base images matter. Pull them through a proxy, choose trusted ones, and rebuild regularly to pick up fixes.
• Agents need the container tooling, and Docker-in-Docker or similar setups deserve careful security review.
• Rate limits on public registries can break builds that pull base images directly. A proxy avoids this.

This chapter lifts the lid. Knowing what happens during an upload and a download makes many puzzling errors easy to explain.

What happens on an upload

When an agent uploads an artifact, it opens a network connection to the repository, proves who it is with a credential, and sends the file together with its address. The repository checks that the credential has the right to write to that repository. It then checks the rules for that repository, for example whether overwriting is allowed. It computes checksums as the file arrives and compares them to any checksums the client sent. If everything matches, it stores the file, records its details in an index, and updates any metadata files that describe the available versions. The pipeline receives a success answer only after all of this is done.

What happens on a download

A build tool asks for an artifact by its address. The repository looks it up. If the address points at a group, the repository checks each member in order. If a proxy member holds a cached copy, that copy is returned. Otherwise the proxy fetches the file from the outside registry, checks it, caches it, and returns it. The client normally verifies the checksum after download.

The role of checksums

A checksum is a short value calculated from the exact contents of a file. Change one byte, and the checksum changes. The repository stores checksums beside each artifact, and clients check them after download. This catches corrupted transfers and helps show that a file has not been tampered with in storage or in transit. Stronger protection uses digital signatures, where a trusted key vouches for the file.

Where the credential comes from

• Jenkins stores the repository token in its protected credentials store, with a scope that limits which jobs can reach it.
• When the pipeline reaches the publishing step, Jenkins decrypts the token on the controller and sends it to the agent only for that block.
• The agent gives it to the build tool, usually through an environment variable or a temporary configuration file.
• When the block ends, the temporary file is removed, and the token leaves the agent’s environment.

Build information and fingerprints

To connect an artifact to its build, a pipeline can attach properties to the upload, or use a vendor plugin to publish a record of the build. In addition, Jenkins can compute a fingerprint for the file, so that its own pages can show which other jobs used it. Together these give traceability in both directions: from the build to the artifact, and from the artifact back to the build.

A repository can make builds much faster, or much slower, depending on how it is set up. This chapter shows where the time and money go.

Where the time goes

In a pipeline that uses a repository, time is spent in three places: downloading dependencies at the start, uploading artifacts at the end, and downloading artifacts again when deploying. Each of these depends on the size of the files, the speed of the network path between the agent and the repository, and how busy the repository is.

The numbers above are only an illustration. Without a proxy, sixty builds times three hundred megabytes is eighteen gigabytes fetched from the public internet each day. With a warm proxy cache, the outside download happens roughly once, about three hundred megabytes, and the remaining traffic stays inside your own network.

Ways to keep it fast

Storage cost and retention

Storage grows quietly. Suppose each build produces an eighty-megabyte package and the team does sixty builds a day. That is 4.8 gigabytes a day, or about 144 gigabytes over a thirty-day retention window for snapshots. Release versions are usually kept far longer, and container images add layers of their own. Without cleanup rules, storage cost only ever rises.

Once every build depends on the repository, the repository becomes part of your delivery infrastructure. It must be dependable.

A new single point of failure

Before the integration, a build needed only Jenkins and the internet. Now it needs Jenkins, the repository, and the network between them. If the repository is down, builds cannot fetch dependencies, and deployments cannot fetch artifacts. A repository that is slow or unreachable can stop the whole company from shipping.

Pipeline habits that help

• Retry with limits. A short retry, with a few attempts, smooths over brief network problems. Endless retries hide real outages.
• Timeouts. Give every upload and download a maximum time, so a stuck transfer cannot hold an executor for hours.
• Safe reruns. Uploading the same version twice should either succeed harmlessly or fail clearly, never leave a half-state.
• Fail early. Check the repository is reachable at the start of a pipeline, so developers learn about a problem in seconds, not after twenty minutes of building.
• Verify after publishing. Confirm the file is present and its checksum matches, before telling later stages to fetch it.

Protecting the repository itself

Treat the repository like a production system. Back up its data and configuration, test the restore, monitor its disk and response time, and keep it patched. Because it holds the only copy of past releases, losing it can be more painful than losing a source code server, since source can be rebuilt, but builds rebuilt long afterwards may differ.

A repository sits right in the middle of your software supply chain. Whatever it serves ends up inside your products, so its security matters a great deal.

Habits that protect you

• Least privilege. Read-only tokens for building and testing. Write tokens only for the publishing step. Promotion rights only for the promotion step.
• Use Jenkins credential scopes. Store repository tokens in the team’s folder, so other teams’ pipelines cannot use them.
• Defend against dependency confusion. Use company namespaces for internal packages, and configure the group so that internal names are resolved only from your hosted repositories, never from a public proxy.
• Make releases immutable. Turn off overwriting in release repositories.
• Scan on the way in and on the way out. Check downloaded dependencies and your own artifacts for known vulnerabilities and licence problems.
• Record and sign. Attach build information to each artifact, keep a list of what is inside it, often called a software bill of materials, and sign artifacts where your process demands it.
• Deploy by checksum or digest. Make the deployment stage verify what it downloaded.
• Protect the repository server. Patch it, restrict its network exposure, and log all administrative actions.

When an upload fails or a download is slow, here is how to find the cause calmly.

What to watch

• Jenkins build logs. Show the exact command, the error message, and the exit status, with secrets masked.
• Repository logs and audit records. Show who tried what, and why it was refused.
• Repository health. Disk space, response time, error rate, and queue of requests.
• Transfer sizes and durations. A sudden jump often means a package changed shape, or a cache went cold.
• Build information links. From an artifact in the repository, jump back to the Jenkins build that made it.

flowchart TD
  A["Upload or download fails"] --> B{"Is it an authentication or permission error"}
  B -->|Yes| C["Check the Jenkins credential and its scope, and the token permissions"]
  B -->|No| D{"Is it a not found error"}
  D -->|Yes| E["Check the repository name, the coordinates, and the group members"]
  D -->|No| F{"Is the overwrite refused"}
  F -->|Yes| G["A release version already exists so use a new version"]
  F -->|No| H{"Is it a timeout or a slow transfer"}
  H -->|Yes| I["Check the network path, the proxy, the file size, and repository load"]
  H -->|No| J["Read the repository log and the full response message"]
    

Common symptoms and causes

Numbers worth tracking over time

Track the time of dependency resolution and of publishing in each pipeline. Track the cache hit rate of proxy repositories. Track storage growth per repository, and the number of failed uploads and downloads per week. A weekly look at these charts turns surprises into planned changes.

Patterns are habits that keep delivery calm. Anti-patterns are habits that keep causing incidents.

Patterns that help

Anti-patterns to avoid

A balanced view of repository integration, and the habits that keep it working for you.

Best practices in one place

1. Build once and promote. Never rebuild between test and production.
2. Publish only after success, and only from trusted branches.
3. Deploy from the repository, by exact version or digest, never from a workspace.
4. Make release versions immutable. A fix is always a new version.
5. Resolve everything through a group repository with proxies, so builds are fast and policy is central.
6. Defend against dependency confusion with namespaces and repository routing rules.
7. Use narrow tokens, one per purpose, stored in the right Jenkins credential scope and bound only where needed.
8. Attach build information and checksums to every artifact, and sign where required.
9. Set retention and cleanup rules from the start, and watch storage growth.
10. Add timeouts and limited retries to every upload and download.
11. Back up the repository and test restoring it, since it holds your release history.

The mistakes seen most often

Let us follow one imaginary team as it replaces file copying with a repository, one step at a time.

The starting point

A team of twelve builds a web service. Their Jenkins pipeline compiles the code, runs tests, and then copies the packaged file from the workspace to the test server, and later to the production server, using a secure copy command. The team does about sixty builds a day, and each build downloads roughly three hundred megabytes of dependencies from public registries. When a bad release reaches production, the team rebuilds the previous commit, which takes about twenty-five minutes and does not always produce the same result. Nobody can say for sure which commit is running on the test server.

Here is how repositories tend to be arranged in real delivery pipelines. These are illustrative patterns in general terms, not claims about the private setups of any particular company.

Jenkins is one of the most widely used automation servers, and repository managers are a common companion to it in organisations of every size. What tends to be common is a habit of building once, routing all dependencies through one gate, and keeping release history safe. The patterns below show that habit in practice.