Chapter 15Lesson 03~115 minutes

Credentials Store, Secret Text, Files, SSH Keys, Username/Password, Binding, and Secret Hygiene: Configuration, Design Choices, and Tradeoffs

Choose credential stores, scopes, domains, types, binding patterns, and external-provider boundaries according to trust, portability, auditability, and rotation needs.

Design choicesFolder scopeExternal providersDomainsRotationLeast privilege

Learning objectives

Choose root System, root Global, folder, and user credential contexts intentionally.
Use credentials domains for selection metadata without mistaking them for authorization boundaries.
Select secret text, username/password, file, or SSH-key types according to the consuming tool.
Compare Jenkins-stored credentials with external secret providers and environment binding with tool-native helpers.
Design rotation and audit ownership so a stable credential ID does not become a permanently unmanaged secret.

1. Start with the trust boundary, not the convenience of the dropdown

A credential design should begin with five questions: who owns the secret, which Jenkins items must use it, which agents may receive it, which external service accepts it, and how it is rotated/revoked. Only then choose store, scope, domain, type, and binding method.

The easiest UI choice—root global credential plus a Pipeline-wide environment variable—often creates the widest exposure. Least privilege is achieved by reducing both where the ID resolves and how long the resolved value exists.

2. System, Global, user, and folder contexts

Context	Good fit	Main risk	Evidence to keep
Root System	Controller/system functions such as specific agent launch or system integration	Using it for ordinary jobs confuses system and build trust	System function, owner, credential ID
Root Global	Credential legitimately shared by many item contexts	Large blast radius	Authorized consumer inventory
Folder store	Team/application/environment jobs under one folder	Folder permissions or descendant trust may still be too broad	Folder path + expected descendants
User store	User-specific operations where plugins honor user credentials	Automation ownership tied to individual accounts	User/context and intended action

Folder scope is especially useful for separating ordinary CI credentials from deployment/signing credentials. But if untrusted PR code can configure or execute a descendant job on a privileged agent, folder storage alone does not make the secret safe.

3. Domains improve selection; contexts enforce access

A domain can describe service requirements, for example host=registry.lab.invalid and scheme=https. Consumers that provide compatible requirements can filter out unrelated credentials. This reduces operator error and improves semantic organization.

Critical distinction: Jenkins Credentials domains are not intended to prevent a credential from being used against another service. A plugin may not provide enough requirements for filtering, and global-domain credentials always match. Use folder/context boundaries and permissions for restriction.

4. Secret text versus file/SSH key versus username/password

Prefer the most specific type the tool understands. This minimizes glue code and transformation:

Type	Use when	Avoid
Secret text	Opaque API/OAuth-like token	Writing it to disk just to satisfy a custom script
Username/password	Protocol/tool expects separate user and password	Manual `user:pass` concatenation in Groovy/logs
Secret file	Tool natively consumes config/cert/file	Binding inside browsable subdirectory or archiving copies
SSH private key	SSH/Git/remote tool expects key material	Printing key, disabling host verification, reusing personal key

5. Jenkins-stored secret versus external provider

Jenkins' built-in credential storage is operationally simple and integrates broadly. Its encrypted values and decryption key material are part of the controller security/recovery boundary, so controller filesystem compromise and backups matter. An external provider can centralize rotation, short-lived leases, revocation, and access logs, but adds availability, plugin, provider identity, network, and policy dependencies.

Do not switch merely because “external is more secure.” Define the provider trust chain: how Jenkins authenticates, how a job is authorized, whether secrets are fetched on the controller or agent, lease duration, failure behavior, audit trail, and what happens during controller restore. Chapter 16 goes deeper into those provider patterns.

6. Environment binding versus tool-native helper

Environment variables are portable but inherited by child processes and may be inspectable by other local processes under the same OS security context. Secret files have filesystem lifetime and permission concerns. A tool-native credential helper or dedicated Jenkins integration can sometimes pass the secret more narrowly or avoid exposing it to generic shell code.

Prefer the narrowest supported integration. If a shell is necessary, bind immediately around the exact command, disable tracing, avoid Groovy interpolation, validate the destination, and end the binding before artifact/report/archive operations.

7. Worked scenario: trusted release folder plus untrusted PR builds

Suppose app-ci/ handles untrusted pull requests and app-release/ publishes signed releases. The release credential should not be root-global simply because both folders build the same repository.

Decision	Choice	Prerequisite/evidence
Release token location	`app-release` folder store	Folder permissions reviewed; no untrusted items beneath it
PR builds	No release credential resolution	Expected denial test
Agent pool	Dedicated trusted release label	Node/launcher/image inventory
Binding	Only around publish command	No token in pipeline-level environment
Artifact	Promote exact already-tested digest	Build/source/digest evidence from Chapter 14
Rotation	Service owner + scheduled/incident rotation	Owner and last rotation date; no value in audit record

8. Decision matrix

Choice	Maintainability	Least privilege	Portability/audit	Operational cost
Root Global	Simple	Weak if few consumers	Easy but broad	Low initial cost
Folder credential	Clear ownership	Better contextual boundary	Good if folder structure is stable	Moderate governance
External provider	Central lifecycle	Can enable short-lived identity	Strong provider audit possible	Provider/plugin/network complexity
Pipeline-wide env	Easy	Long exposure window	Easy to misuse	Low
Step-scoped binding	Explicit	Shorter exposure	Good code review signal	Slightly more verbose

9. Rotation is part of the credential contract

A stable credential ID is useful because consumers do not need source changes when the underlying secret rotates. That stability can also hide neglect. Record a non-secret owner, external account/service identity, expiry or lease policy, rotation trigger, emergency revocation procedure, and expected consumer test.

When rotating, test the narrowest disposable consumer first, then verify the external service audit/response. Do not keep an old broad credential “just in case” without an explicit rollback window and revocation deadline.

Next lesson

Diagnostics, Failure Modes, Security, and Performance

Trace real exposure paths: Groovy interpolation, shell tracing, transformed output, secret files under workspaces, broad credential contexts, and untrusted agents.

Knowledge check

When should System scope be used instead of Global scope?

Why are credential domains useful even though they are not security boundaries?

When is a secret file preferable to secret text?

What is the main tradeoff between Jenkins-stored credentials and an external secret provider?

Why prefer a tool-native credential helper over a long-lived environment variable when available?

Official references and version notes

Jenkins Handbook — Using credentials — credential kinds, system/global scope, IDs and controller-side encrypted storage.
Jenkins Handbook — Credentials security — limit access, protect secrets, and treat credential use as a trust-boundary decision.
Using a Jenkinsfile — Handling credentials — Pipeline credential helpers and safe binding patterns.
Credentials Binding step reference — current withCredentials bindings and file-placement cautions.
Credentials plugin — version 1511.v2e3cb_0008ef0 in this lab baseline.
Credentials Binding plugin — version 728.v902a_273b_8947.
SSH Credentials plugin — version 372.va_250881b_08cd.
Folders plugin — version 6.1106.v3a_d9a_6d2465e; provides per-folder credential stores when used with Credentials.
Jenkins LTS changelog and Java support policy — lab baseline Jenkins 2.568.3 LTS, Java 21; 2.568.3 is tested with Java 21 and 25.

Assumption timestamp: 2026-09-17. Recheck core/plugin security advisories and minimum-core requirements before reproducing this lab later.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.