Shared Libraries

## What a shared library is A Jenkins shared library is an ordinary SCM repository — nearly always Git — containing Groovy code that pipelines load at build time. It is not a plugin and nothing about it is automatic. A Jenkins administrator first registers it: a **name** (`utils`), a **retrieval method** (the repo URL and credentials), and a **default version**. The name in the annotation is that registered name, not a URL and not a package. ## What the annotation actually triggers When a build starts, before any stage runs, Jenkins resolves each requested library, checks out the requested version into a workspace on the controller, compiles the Groovy, and puts it on the pipeline's classpath. Two things become reachable: - every file in the library's `vars/` directory becomes a global variable, and if it defines a `call` method it can be invoked as if it were a built-in step; - classes under `src/` can be imported or referenced by fully-qualified name. Because resolution happens up front, a typo in the library name or a version that does not exist fails the build immediately — you get no stages at all, which is a useful diagnostic: the failure is in loading, not in your pipeline logic. ## The part after the @ ```groovy @Library('[email protected]') _ // a tag @Library('utils@main') _ // a branch @Library('utils@0f3a1b2c9d') _ // a commit SHA @Library('utils') _ // the configured default version ``` For a Git-backed library, anything the SCM can resolve to a revision works. A tag or a SHA is immutable and therefore reproducible; a branch means the build gets whatever that branch pointed at the moment the build started, which is how a library change reaches many pipelines at once. A library configuration has a checkbox controlling whether Jenkinsfiles are permitted to name a version at all. If overriding the default version is not allowed, `@Library('[email protected]')` fails with an error saying the override is not permitted — a very common first encounter with shared libraries. ## Why the underscore Groovy annotations cannot float on their own; they must be attached to a declaration or statement. The idiomatic target is an import: ```groovy @Library('utils') import com.acme.Deployer ``` When you only want the library's `vars/` steps, there is no import to annotate, so the convention is to attach the annotation to `_`, a bare no-op statement that does nothing else. It is not special syntax — any statement would do; `_` is simply the community convention and what the Jenkins documentation uses. ## Loading more than one, and loading at runtime The annotation accepts a list: ```groovy @Library(['[email protected]', 'security-scans']) _ ``` There is also a `library` step that loads a library while the pipeline is already running: ```groovy def lib = library '[email protected]' ``` That form is useful when the version is computed at runtime, but it cannot be combined with `import` statements, and classes are reached through the returned object rather than by import. For the overwhelmingly common case — a fixed library at a fixed version — the annotation is the right tool. ## Placement in Declarative pipelines Declarative pipelines forbid arbitrary code outside the `pipeline` block, but the library annotation is explicitly allowed at the top of the file. It must come before `pipeline {`; put it lower and the file will not even parse as Declarative. ## Practical notes Library names live in a flat namespace per controller, and so do the global variables the libraries provide — two libraries that each define `vars/deploy.groovy` collide, so prefix var names when several teams publish libraries. And because loading a library means running someone else's Groovy inside your build, which library you load and who can merge to it is a security decision, not just a convenience.