Credential Scopes in Jenkins
A complete, plain-English guide to deciding who can see and use each password, token, and key in Jenkins: what the scopes are, how Jenkins finds a credential, and how to give every secret the smallest reach it needs.
Imagine a large office building with hundreds of keys. Some keys open the front door and are carried by everyone. Some open only the finance department. Some open the server room and are kept by two people. And a few belong to the building’s own machinery, like the lift and the alarm, and are never handed to any employee at all. If the building manager put every key in one open drawer, any visitor could walk off with the key to the safe. A good manager decides, for each key, exactly who may use it.
Jenkins holds keys too. They are called credentials: passwords, tokens, private keys, and certificates that let your pipelines log in to Git servers, cloud platforms, container registries, and production machines. Every one of them has a scope, which decides who and what inside Jenkins may use it. Getting scopes right is the difference between “a pipeline in one team can deploy only its own service” and “any pipeline in the company can deploy anything”. This guide explains the whole topic from zero, so you can give each secret the smallest reach it needs.
1What Is a Credential Scope?
We start with the simplest picture: what a credential is, and what it means to say that it has a scope.
Jenkins is a tool that automates building, testing, and delivering software. To do that, it must often prove who it is to other systems. A credential is a saved secret that Jenkins uses for that purpose. Examples include a password for a registry, a token for a cloud service, and an SSH key for a server. Instead of typing secrets into a Jenkinsfile, where everyone could read them, you store each one in Jenkins and refer to it by a short name called its ID.
A scope is a rule attached to a credential that says where in Jenkins it may be used. In plain words, scope answers the question: “Who is allowed to reach for this key?” The two main scopes are System, for keys that only Jenkins itself may use, and Global, for keys that jobs and pipelines may use. On top of these, Jenkins lets you place credentials inside folders, so that only the jobs in that folder can reach them, and there is also a personal user store.
Think of the key cabinet in a school. The caretaker’s cabinet holds the keys to the boiler room and the alarm. Only the caretaker uses them, and teachers never see them. The staff room board holds keys for shared rooms that every teacher may take. Each department has its own locked box for its own supplies. System scope is the caretaker’s cabinet. Global scope is the staff room board. Folder credentials are the department boxes.
The three questions a scope answers
Who can use it?
Only Jenkins itself, every job in the system, or only the jobs inside one folder.
Where is it visible?
Which dropdown lists, pipelines, and configuration screens will show it or accept its ID.
What damage can it do if misused?
The wider the reach, the more people and code could misuse it, on purpose or by accident.
Least reach
Give every credential the smallest scope that still lets its job get done.
Scopes are about who may use a secret. They are not about who may read it. Once a secret is stored, Jenkins never shows its value again on screen. The danger is not reading it in the web page, but using it inside a build and sending it somewhere else. The security chapter returns to this.
2Why Scopes Exist
To see why scopes matter, imagine Jenkins without them and follow what goes wrong.
The problem: one drawer for every key
Early Jenkins installations were small. One team, a handful of jobs, and a few secrets. Everyone trusted everyone, and storing all credentials in one shared place caused no trouble. Then Jenkins grew. A single server began to serve many teams, each with its own services, its own cloud accounts, and its own production systems. If every credential were visible to every job, then a developer on one team could, by writing one line in a Jenkinsfile, use another team’s production deploy key. No hacking is needed. They only need to guess or find the ID.
There is a second problem. Some secrets belong to Jenkins itself, such as the key it uses to connect to build agents, or the password for its email server. These should never be reachable from a pipeline at all, because a pipeline is code that many people can edit.
The answer: a small set of reach levels
Jenkins solves this with the Credentials plugin, which is part of almost every installation. It arranges credentials into stores, attaches a scope to each credential, and lets folders own their own stores. Together these give administrators a way to say, for every secret, how far it may reach.
A hospital does not give every nurse the pharmacy safe key. The ward nurse gets the ward cupboard key. The pharmacist holds the safe. The hospital’s building systems use their own codes that no clinician ever sees. Splitting access this way is not about distrust. It limits how much harm one mistake can do.
3Jenkins Basics You Need First
A few Jenkins words come up in every credential discussion. Learn them once here.
Controller
The main Jenkins server. It stores job settings, credentials, and build history, and decides what runs where.
Agent
A worker machine, virtual machine, or container that runs the commands of a build. The controller sends it work and, when needed, the secrets for that work.
Folder
A container for jobs, like a directory. Folders can be nested, and they can hold their own settings, permissions, and credentials.
Jenkinsfile and pipeline
A text file that describes a build as an ordered list of stages. It usually lives in the same Git repository as the code, so anyone who can change the repository can change it.
Permission
A right, such as “view”, “configure”, or “use credentials”, granted to a user or group.
Credential ID
The short name that pipelines use to refer to a credential. You choose it, or Jenkins generates a long random one.
Credentials versus environment variables
Both credentials and environment variables hand named values to your builds, but they serve different purposes. Environment variables are plain settings, such as an application name. Credentials are protected secrets, stored encrypted, masked in logs, and controlled by scope and permissions. Whenever a value is secret, it belongs in the credentials store, and the environment is used only as the delivery route into a shell command for the moment it is needed.
Before creating a credential, ask yourself: who will use this, and who must never use it? The answers tell you the scope before you touch a single setting.
4Anatomy: Stores, Domains, Scopes, and IDs
Four words describe where a credential lives and who can find it. Keep them apart in your head, and the rest of the topic gets easy.
| Term | What it is | Simple picture |
|---|---|---|
| Store | A place that holds credentials, owned by Jenkins itself, by a folder, or by a user | A cabinet |
| Scope | The rule on a credential saying where it may be used | A label on the key: staff only or caretaker only |
| Domain | A grouping inside a store that can limit a credential to certain web addresses or hosts | A drawer for keys that match one building |
| ID | The name a pipeline uses to ask for one credential | The number stamped on the key |
| Type | The kind of secret: text, username and password, file, key, certificate | The shape of the key |
How they fit together
Pick a store
The store is decided by where you create the credential. Creating it from the top-level Jenkins credentials page uses Jenkins’ own store. Creating it inside a folder uses that folder’s store.
Pick a domain
Most credentials go into the default domain. You can create extra domains to group credentials for particular hosts.
Pick a scope
System or Global at the top level. This is the choice with the biggest effect on who can reach the secret.
Choose a type and enter the secret
Match the type to the step that will use it, and enter the value once. Jenkins encrypts it and never shows it again.
Give it an ID and a description
A clear ID such as a team, a system, and a purpose helps everyone, and a description says who owns it and what it is for.
Filing a document in an office: you choose the building (the store), the drawer (the domain), the confidentiality stamp (the scope), and the file name (the ID). Each choice narrows down who can find it and who is allowed to open it.
The exact screens and wording differ between Jenkins versions and plugin versions. The ideas in this guide stay the same, but always confirm the labels on your own server before making changes to a live system.
5System Scope in Depth
System scope is the most private level. It is for secrets that belong to Jenkins itself and should never be reachable from a pipeline.
A credential with System scope can be used only by Jenkins and its plugins for their own background work. It is not available to the steps of a running job. If a pipeline asks for it by ID, Jenkins behaves as if the credential does not exist.
Typical uses
Connecting to agents
The SSH key or password the controller uses to log in to a build agent. A pipeline never needs it.
Cloud plugins
Credentials that let Jenkins create and remove elastic agents in a cloud or a cluster.
System notifications
Login details for the email server or chat service that Jenkins uses to send its own notices.
Scanning source control
Some setups keep the credential used to scan a repository for branches in a form that builds cannot use, so a Jenkinsfile cannot borrow it. Details depend on the job type and plugin.
The building’s own control room has a master code for the lifts and the fire alarm. The people who work in the building never receive it. The machinery uses it privately. System scope is that private code.
Why it matters so much
A pipeline is code, and code can be edited by many people, including people who have no business near your agent keys. If an agent’s private key had Global scope, any pipeline could load it, print it in a disguised form, or send it to an outside server. With System scope, that whole class of attack is closed, since the pipeline cannot obtain the key in the first place.
Strengths of system scope
- Hidden from every pipeline and build step.
- Protects infrastructure keys from being borrowed.
- Limits the damage of a malicious Jenkinsfile.
Limits of system scope
- Useless for anything a build needs to use.
- Still readable by people with high administrative rights.
- Easy to forget: teams often put infrastructure keys in Global scope by habit.
A quick audit: list every credential and ask, “does any pipeline really use this?” If the answer is no, and the credential is used only for agents, clouds, or notifications, it should be System scope.
6Global Scope in Depth
Global scope is the default choice for most credentials. Its name is easy to misread, so let us be careful.
A credential with Global scope can be used anywhere in that Jenkins: by any job, any pipeline, any folder, and by system tasks as well. It is the scope you pick when a pipeline needs the secret, for example a registry login or a cloud deployment token.
The misleading name
“Global” does not mean “public to the internet”, and it does not mean “visible to everyone who can log in”. It means global inside this Jenkins installation. Every job running on this controller can use it, provided the person who wrote or configured the job has the right to use credentials. In a small company with one team, that may be fine. In a large one, it may be far too wide.
A “company-wide” parking pass is valid for every car park the company owns. It is not valid on the public street. But any employee who finds one can use it in any of those car parks. That is how Global scope behaves: wide inside the company, and only inside the company.
When global scope is reasonable
- Read-only access to shared resources, such as a token that lets every build download packages from a company-wide mirror.
- Low-risk credentials, where misuse would do little harm and be easy to detect.
- A small, trusted Jenkins, where everyone who can edit pipelines is allowed to use everything.
When it is a bad choice
- Production deployment keys that only one team should ever use.
- Credentials with write access to shared systems such as a main code repository or a company package registry.
- Any secret that a single team owns. That secret should live with that team.
| Question | System scope | Global scope |
|---|---|---|
| Can a pipeline use it? | No | Yes, any pipeline on this Jenkins |
| Can Jenkins plugins use it for background work? | Yes | Yes |
| Good for agent connection keys? | Yes | Not recommended |
| Good for a deployment token used by many teams? | No, builds cannot use it | Only if low risk |
| Good for one team’s private secret? | No | No, use a folder |
Global scope is the easy choice, which is exactly why it is overused. Every credential that sits in Global scope out of convenience quietly widens the number of people who can misuse it. Treat “global” as something you must justify, not as the default.
7Folder-Level Credentials
Folders are the most practical tool for narrowing scope. They let each team keep its own secrets, close to its own jobs.
A folder in Jenkins can hold jobs, and it can also hold its own credentials store. A credential created inside a folder is visible only to jobs in that folder and in the folders nested below it. Jobs in a sibling folder, or at the top level, cannot see it. This gives you team-sized scopes without any special setup beyond arranging your jobs into folders that match your teams.
flowchart TD
A["Jenkins controller"] --> B["System scope store for Jenkins itself"]
A --> C["Global scope store visible to all jobs"]
A --> D["Folder Payments"]
A --> E["Folder Search"]
D --> F["Payments folder credentials"]
D --> G["Pipeline jobs in Payments"]
E --> H["Search folder credentials"]
E --> I["Pipeline jobs in Search"]
How visibility flows downward
A job can use credentials from its own folder, from every parent folder above it, and from the Global scope at the top. It cannot look sideways or downward into other folders. So a credential placed high in the tree is seen by a lot of jobs, and one placed low in the tree is seen by few. Choosing the folder is choosing the audience.
In a large company, the CEO’s notice board is read by everyone. A department’s board is read only by that department. A team’s whiteboard is read only by the team. A message posted on the CEO’s board reaches everybody, and a message on the team whiteboard reaches only the team. Folder depth works in the same way.
What you gain
Team isolation
One team cannot use another’s secrets, by accident or on purpose.
Delegated ownership
With the right permissions, a team lead can manage the folder’s credentials without touching anyone else’s.
Smaller blast radius
If a folder’s credential leaks, only that team’s systems are at risk, not the whole company’s.
Cleaner lists
Dropdowns in the folder show only the credentials that folder can use, so people choose correctly.
Same ID in two places
The same ID may be used in different folders for different secrets. A job asking for the ID gets the closest one, starting from its own folder and moving upwards. This lets every team use a common name such as “deploy-key” for its own key, with a pipeline template that works for everyone. It also means a folder credential can hide a global one with the same ID. That is useful when it is done on purpose and confusing when it happens by accident.
Folder credentials are only as private as the folder’s permissions. If everyone can configure jobs in a folder, everyone can also write a pipeline that uses its credentials. Match your folder permissions to your team boundaries.
8User Credentials and Personal Stores
Jenkins also has a personal store for each user. It is narrower than a folder, and it works differently.
Each Jenkins user can, if enabled, keep credentials in their own user store. These belong to one person. They are not visible to other users, and they are not offered to jobs in general. The idea is that a person may keep a personal token, for example for their own account on some service, and use it in a build that they start themselves, without sharing it with the whole team.
How it differs from the others
| Store | Who owns it | Who can use it | Typical purpose |
|---|---|---|---|
| System scope in the Jenkins store | The Jenkins administrators | Jenkins itself only | Agents, clouds, notifications |
| Global scope in the Jenkins store | The Jenkins administrators | Every job on this Jenkins | Shared secrets of low risk |
| Folder store | The folder’s managers | Jobs in that folder and below | Team secrets |
| User store | One user | That user’s own actions, where enabled | Personal tokens |
An employee has a personal locker at work. Only they have the key, and they keep their own things there. The company does not use it, and other staff cannot open it. The user store is that locker.
Things to know
- Availability depends on plugins and settings. Some installations do not expose a user store at all.
- They only work when a build runs as that user. Builds started by timers or by other people cannot use them. Where the build runs as someone else, the personal secret is not available.
- They are not a substitute for team credentials. Nightly jobs and deployments must use folder or global credentials, not personal ones.
- Personal tokens leave with the person. If someone leaves the company and a pipeline depends on their personal token, the pipeline breaks.
Use personal credentials sparingly. Anything that a shared pipeline depends on should belong to the team, not to one person’s account.
9Credential Domains
A domain is another way to narrow where a credential is offered. It works by matching the address that the credential is meant for.
A domain is a named group inside a store. Its most useful feature is that you can attach a specification to it, such as a hostname, a web address scheme, a port, or a path. Jenkins plugins that talk to a certain server, for example a Git host, use the domain to choose which credentials to offer. If a domain says “hostname: git.example.com”, then a plugin working with a different host will not be offered those credentials in its dropdown.
A key ring for a building has labelled tags: “front door”, “garage”, “storeroom”. You do not try every key on every door. You look at the tag that matches the door in front of you. A domain is the tag that says which server a credential is meant for.
What domains do and do not do
What domains are good for
- Keeping dropdown lists short and relevant.
- Avoiding sending a credential to the wrong server by accident.
- Organising many credentials by the system they belong to.
What domains are not
- They are not a strong security wall. A pipeline that asks for a credential by ID may still be able to obtain it.
- They do not replace scope or folders.
- Not every plugin uses them in the same way.
Think of a domain as good housekeeping and scope as the real lock. Use domains to tidy and to prevent honest mistakes, and use scope and folders to prevent dishonest ones.
10Credential Types
Every credential has a type, which decides what kind of secret it holds and how a build receives it. Scope is separate from type, and any type can be given any scope.
| Type | What it holds | How a build usually receives it |
|---|---|---|
| Secret text | A single secret string, such as an API token | As the value of a variable |
| Username with password | A login name and a password | As a combined value, and often as separate username and password variables |
| Secret file | A whole file, such as a configuration or certificate file | As the path to a temporary copy on the agent |
| SSH username with private key | A username and a private key, possibly with a passphrase | As the path to a temporary key file, plus the username |
| Certificate | A certificate and its private key, often in a keystore file | As a keystore file with a password |
| Plugin-provided types | Cloud keys, application tokens, and so on | Depends on the plugin that provides the type |
Choosing the right type
The step that uses a credential expects a particular type. A Git checkout step wants a username and password, or an SSH key. A step that calls a web service may want secret text. If you offer the wrong type, the step will not list the credential in its dropdown, and a pipeline that names it by ID will fail with a message that the credential is of the wrong type. When a credential seems to be missing from a list, the type is one of the first things to check.
A padlock takes a key, a combination lock takes a number, and a swipe door takes a card. Giving a key to a card reader does nothing. Each door expects its own kind of credential, no matter how trusted the person holding it.
Prefer narrow tokens over full passwords. A token that can only read one repository is a much smaller risk than an account password that can do everything. Scope inside Jenkins and scope inside the target system work together.
11How Jenkins Finds a Credential Internally
This chapter lifts the lid. Knowing the lookup order explains almost every surprise around missing or wrong credentials.
Lookup starts from the item and moves upward
When a build asks for a credential by ID, Jenkins does not search every store in the system. It starts from the context, which is the job or folder where the build is running, and looks in that place first. If it finds a match visible to that context, it uses it. If not, it moves up to the parent folder, then the next parent, and finally to the top-level Jenkins store, where Global scope credentials live. System scope credentials are not offered to build steps, so the search does not end there.
sequenceDiagram
participant P as Pipeline Build
participant R as Credentials Resolver
participant F as Folder Store
participant G as Global Store
participant S as Secret Storage
P->>R: Request a credential by ID for this build
R->>F: Look in the job folder and its parents
F-->>R: No match found
R->>G: Look in the global scope
G-->>R: Match found
R->>S: Decrypt the secret value
S-->>R: Secret value
R-->>P: Deliver the secret for this build only
You lose a pen at work. You check your own desk first, then your team’s shared drawer, then the department cupboard, and finally the company stationery store. The first place that has a pen wins. A credential lookup checks the nearest store first in the same way.
The closest match wins
If two stores hold credentials with the same ID, the closer one is the one used. A folder credential named “registry” hides a global credential also named “registry” for the jobs in that folder. That behaviour is handy when each team wants its own “registry” login under a shared name. It is also a source of confusion when a person edits the global one and wonders why a folder’s jobs did not change.
What the resolver also checks
- The type. The credential must be of the type the step expects.
- The domain. Where a domain limits hostnames, the target must match.
- The identity. The user or system on whose behalf the build runs must be allowed to use the credential, for scopes and stores that check this.
- The scope. System-scoped credentials are not offered to builds at all.
Delivery to the agent
The secret is decrypted on the controller and sent to the agent only for the build that needs it. For secret files and keys, the agent writes a temporary file, and removes it when the block using it ends. Jenkins also adds the value to a list of things to hide, so that the exact value is replaced by stars if it appears in the build log.
Details of the internal lookup vary between plugin versions, and some credential providers, such as external secret managers, use their own rules for which items may see which secrets. The nearest-first principle is the safe way to think about it.
12Using Credentials in a Pipeline
Scope decides which credentials a job may reach. The way you use them in the Jenkinsfile decides how long each secret stays in play.
There are three usual ways to bring a credential into a pipeline. They all respect scope, and they differ in how long the secret is available and how easily it can leak.
| Method | How it works | Lifetime of the secret | Best for |
|---|---|---|---|
Environment block with the credentials() helper | Loads the secret into named variables for a whole pipeline or stage | The whole pipeline, or the stage it sits in | Secrets needed in many steps of one stage |
The withCredentials step | Wraps a small block of steps and binds the secret only inside it | Only the wrapped steps | Secrets needed for one or two commands |
A credentialsId setting on a plugin step | Hands the ID to a plugin, such as a Git checkout, which fetches the secret itself | Only while that step runs | Steps designed to take credentials directly |
You can lend a colleague your office key for the whole week, for one afternoon, or just hold the door while they walk through. All three are allowed by the rules, but the shorter the loan, the less can go wrong. The three methods are a week, an afternoon, and holding the door.
The shortest loan is the safest
A secret that lives for the whole pipeline is available to every step, including steps you did not write, such as tools that print their settings when they fail. A secret that lives inside a two-line wrapper block is available only to those two lines. So the habit to build is: keep the binding as narrow as the work allows, and bind it inside the stage that needs it, not at the top of the file.
Scope and lifetime work together
Scope decides if the pipeline may reach the credential at all
A folder credential is out of reach for jobs in other folders.
The method decides how long the secret stays in the build
A narrow binding limits how many steps can touch it.
The quote style decides where the value is substituted
Single quotes let the shell read the secret from its environment. Double quotes let Groovy paste it into the command on the controller, which Jenkins warns against.
Masking is the last safety net
Jenkins hides the exact value in logs, but altered forms of the value, such as an encoded copy, are not recognised.
The dropdown lists of credentials in the Jenkins screens are a convenience, not a lock. In a Jenkinsfile, anyone who can commit code can type any ID they know or can guess. Real protection comes from the scope and the folder structure, not from hiding a name from a menu.
13Permissions: Who Can Use, See, and Change Credentials
Scope decides where a credential can be reached. Permissions decide which people may manage it and which may use it.
Jenkins separates several kinds of rights around credentials. The exact names may differ between versions, but the ideas are stable.
| Right | What it allows | Who usually holds it |
|---|---|---|
| View | See that a credential exists, with its ID and description, but never its value | People who manage or audit credentials |
| Create | Add new credentials to a store | Team leads and administrators |
| Update | Change an existing credential, such as replacing a rotated secret | The owners of the credential |
| Delete | Remove a credential | The owners of the credential |
| Manage domains | Create and edit domains in a store | Administrators and team leads |
| Use item | Pick and use the credentials of a folder or job when configuring jobs | Developers who configure jobs in that folder |
| Use own | Use one’s own personal credentials | Individual users |
The “use” right is the powerful one
It surprises many people that the right to use a credential is more dangerous than the right to view it. Viewing shows only a name. Using lets a pipeline put the real secret into a running command. Anyone who can edit a job or a Jenkinsfile in a scope and is allowed to use that scope’s credentials can, in effect, have the secret placed in their hands, inside a build they control.
A librarian may let you look at the catalogue card for a rare manuscript. That does no harm. Letting you take the manuscript to a reading room and photograph every page is a much bigger matter, though the card looked harmless. Viewing the credential entry is the card. Using the credential is taking the manuscript away.
Matching permissions to folders
Permissions can be granted per folder using authorisation plugins such as matrix-based or role-based ones. A typical plan is:
- Administrators manage the system-level and global stores.
- Each team lead manages the credentials of that team’s folder.
- Developers may use their folder’s credentials in jobs, but cannot create or delete them.
- Auditors may view the list of credentials, with no right to use them.
Write down a simple table for your organisation: roles on one side, rights on the other. Fill it in once, review it every quarter, and apply it through groups instead of naming individuals.
Full administrators can run scripts on the controller through the script console, and can therefore obtain the plain value of any stored credential. Keep the number of administrators small, and treat administrator accounts as the most sensitive accounts in the company.
14How Credentials Are Stored and Protected
Where does the secret actually sit on disk? Knowing this helps you back it up, protect it, and recover it.
Encrypted at rest
Jenkins keeps its data in a folder called the Jenkins home. Credentials are saved in a configuration file there, but the secret values inside are encrypted. The keys used to encrypt them are stored in a separate secrets folder inside the same home. A person who reads only the credentials file sees scrambled text. A person who also has the secrets folder can decrypt it. So the two belong together, and both must be protected.
The credentials configuration
Holds the list of credentials, their IDs, scopes, and encrypted values. Folder credentials are kept with the folder’s own configuration.
The secrets folder
Holds the master key material. Anyone who can read it, together with the credentials file, can decrypt the secrets.
Both or neither
A backup with the credentials file but not the keys cannot restore the secrets, and a backup with both is itself highly sensitive.
Operating system permissions
Restrict the Jenkins home to the Jenkins service account, and protect disk snapshots and backup copies.
A locked briefcase is only as safe as where the key is kept. If the key is taped to the lid, the lock does nothing. Keeping the encrypted file and its key in the same unprotected place gives a false sense of safety. Guard the whole home folder like a vault.
What the encryption does not protect against
- Anyone who can run code on the controller. Code running there can ask Jenkins to decrypt secrets.
- Any build allowed to use the credential. The value must be decrypted for the build, and the build can then misuse it.
- Leaked backups. A stolen backup that includes the keys is a full leak.
- Weak downstream secrets. Encryption inside Jenkins does not help if the token itself is over-powerful.
Test your restore process, not only your backup. A backup that cannot be restored, for example because the keys were left out, is a nasty surprise on the worst possible day.
15Security Considerations
Scopes reduce risk, but they do not remove it. These are the main ways secrets escape, and how to close each door.
Editing the Jenkinsfile
Anyone who can change the pipeline file can add a line that sends a bound secret to an outside address. Control who can change pipelines that touch valuable credentials.
Pull requests from strangers
A build from an outside contributor may run their version of the pipeline. Configure multibranch jobs to trust only known contributors, and keep secrets away from untrusted builds.
Over-wide scope
A global credential is reachable from every job, including experiments and abandoned ones. Shrink the reach.
Shared libraries
Pipeline code loaded from shared libraries runs with the credentials of the job that calls it. Review library code as carefully as production code.
Log leaks
Masking hides only the exact value. Encoded, split, or transformed copies can appear in the log unmasked.
Long-lived secrets
A key that never changes has years to leak. Rotate on a schedule and after any suspicion of exposure.
Habits that protect you
- Least reach. System for infrastructure, folders for teams, global only when you can justify it.
- Least power in the target system. A token limited to one repository or one environment does far less damage if it leaks.
- Separate credentials per environment. Never use the same token for testing and production.
- Narrow bindings in pipelines. Bind secrets only inside the stage or block that uses them.
- Review pipeline changes. Treat a change to a Jenkinsfile that touches credentials like a change to production code.
- Rotate and expire. Prefer short-lived tokens where the target system supports them.
- Keep Jenkins updated. Jenkins and its plugins publish security advisories regularly, and credential handling is a frequent subject.
A hotel gives each guest a key card that opens only their room and stops working at check-out. If a card is lost, the damage is one room for one night. A master key that opens every room and never expires would turn one lost card into a hotel-wide disaster. Narrow scope, narrow power, and short life are the card, not the master key.
16External Secret Managers and Scope
Many organisations keep their secrets in a dedicated vault outside Jenkins. Scope still matters there, but it is expressed differently.
Dedicated secret managers, such as vault-style servers and the secret services offered by cloud providers, store secrets centrally, control access with fine-grained policies, keep audit records, and can rotate values automatically. Jenkins plugins can connect to many of them. Depending on the plugin, the external secrets can appear inside Jenkins as ordinary credentials, or be fetched on demand by the pipeline at the moment they are needed.
Where scope lives in this arrangement
| Question | Credentials stored in Jenkins | Secrets kept in an external manager |
|---|---|---|
| Where is the secret kept? | Encrypted in the Jenkins home | In the external service |
| What decides who can use it? | Store, scope, folder, and Jenkins permissions | Policies in the external service, often tied to paths, tags, or roles |
| How is rotation handled? | Manually, by updating the credential | Often automatic, sometimes with short-lived values |
| Where is the audit trail? | Jenkins logs and usage records | The external service’s own audit log |
| What is the extra cost? | Little | Another system to run, secure, and connect |
Keeping keys in a locked drawer at each department is simple. Keeping them in a central bank vault, where each borrowing is signed for and logged, is stronger but takes more effort. Some companies prefer the vault, especially for the keys that matter most.
Good habits with external managers
- Map folders to policies. A team’s Jenkins folder should be allowed to fetch only that team’s secret paths.
- Prefer short-lived secrets. A token that expires in an hour shrinks the value of a leak.
- Authenticate Jenkins narrowly. The identity Jenkins uses to reach the vault should itself have limited rights.
- Do not copy secrets back into Jenkins. That defeats the point and creates a second, forgotten copy.
If you adopt an external manager, keep using Jenkins scopes for the small things that stay in Jenkins, and write down clearly which secrets live where. A missing map is the biggest source of confusion in mixed setups.
17Monitoring, Auditing, and Troubleshooting
When a credential goes missing, or when you need to know who used what, here is where to look.
What Jenkins can show you
- The credentials pages. List every credential that a store holds, with its scope, type, ID, and description, but never its value.
- Usage tracking. The Credentials plugin can record a fingerprint when a credential is used, so a credential’s page can show which jobs and builds have used it. Availability depends on your version.
- Build logs. Show when a credential was bound, with the value masked.
- Audit plugins. Record who created, changed, or deleted credentials and jobs, so you can trace a change back to a person.
- System logs. Show authentication and authorisation problems that block credential lookup.
flowchart TD
A["Credential not found or not usable"] --> B{"Does the ID match exactly"}
B -->|No| C["Fix the ID including case and spaces"]
B -->|Yes| D{"Is the credential in a store the job can reach"}
D -->|No| E["Move it to the job folder or to global scope"]
D -->|Yes| F{"Is it system scope"}
F -->|Yes| G["System scope is hidden from builds so create a global or folder credential"]
F -->|No| H{"Is the type correct for the step"}
H -->|No| I["Use a credential of the type the step expects"]
H -->|Yes| J["Check permissions and any domain restrictions"]
Common symptoms and causes
| Symptom | Likely cause | What to do |
|---|---|---|
| Error that a credential cannot be found | Wrong ID, wrong folder, or System scope | Check the ID, the folder, and the scope |
| Credential missing from a dropdown | Different scope, wrong type, or a domain that does not match | Compare type and domain to what the step expects |
| Build uses the wrong secret | A folder credential shadows a global one with the same ID | List credentials in each level, and rename to avoid clashes |
| Error that the credential is of the wrong type | A text secret offered where a username and password is needed | Create the right type |
| Works for one person and fails for another | Permissions differ, or a personal credential is in use | Move team secrets to a folder and grant the use right |
| Secret shows in a log | The value was changed before printing, so masking missed it | Rotate the secret, and stop printing derived forms |
| Restore from backup cannot read credentials | The secrets folder was not restored with the configuration | Restore both together, and test the process regularly |
Signals worth reviewing regularly
Once a quarter, list every credential and ask four questions. Is it still used? Is its scope as narrow as it can be? Does it have a named owner? When was it last rotated? Credentials that fail these questions should be shrunk, handed to an owner, renewed, or deleted. Unused credentials are pure risk with no benefit.
18Design Patterns and Anti-patterns
Patterns are habits that keep secrets under control. Anti-patterns are habits that slowly turn a tidy Jenkins into an open drawer.
A simple way to choose a scope
flowchart TD
A["New credential to store"] --> B{"Used only by Jenkins itself such as agent connections"}
B -->|Yes| C["Use system scope"]
B -->|No| D{"Used by one team or one folder only"}
D -->|Yes| E["Store it in that folder"]
D -->|No| F{"Used by many teams and low risk"}
F -->|Yes| G["Use global scope with a clear ID and named owner"]
F -->|No| H["Split into per team credentials or use an external secret manager"]
Patterns that help
Folder per team
Arrange jobs into folders that match teams, and keep each team’s secrets in its own folder.
Infrastructure keys in system scope
Agent keys, cloud plugin secrets, and notification logins are hidden from every pipeline.
Naming convention
IDs that show team, target system, and purpose, for example “payments-registry-push”, so anyone can tell what a credential is for.
One credential per purpose
Separate tokens for reading and writing, and for testing and production, so a leak has a small reach.
Owner and expiry in the description
Every credential names its owner and next rotation date, so nothing is forgotten.
Narrow bindings
Bind secrets in the smallest block that needs them, and use single quotes for commands that read them.
Anti-patterns to avoid
Context
Every credential is created at the top level in Global scope, because that is the default and it always works.
What goes wrong
Every job in the company can use every secret. A developer experimenting in a personal job can deploy to production with a key they were never meant to hold, and nobody notices until something breaks.
Better decision
Move team secrets into team folders, infrastructure keys into System scope, and keep Global for the few shared, low-risk items.
Context
One shared, powerful administrator token is stored once and used by every pipeline for every purpose.
What goes wrong
A single leak exposes every system. Rotating it breaks every pipeline at once, so it is never rotated, and it grows older and riskier every year.
Better decision
Create narrow tokens per team, environment, and purpose. Rotation then affects one pipeline at a time.
Context
A pipeline binds all its secrets at the top of the file, so that every stage and every tool receives them.
What goes wrong
A build tool that prints its settings on failure shows the secrets. A careless debug step exposes them. Untrusted code inside a test suite can read them from the environment.
Better decision
Bind each secret only inside the stage or block that needs it, and release it as soon as that work is done.
Context
Credentials have generated random IDs and blank descriptions, and nobody knows who created them.
What goes wrong
Nobody dares delete anything, in case something depends on it. Old secrets stay for years, and audits cannot tell which are live.
Better decision
Use meaningful IDs, and write an owner and a purpose in every description. Delete what has no owner after a fair warning period.
19Advantages, Trade-offs, Best Practices, and Common Mistakes
A balanced view of the scope model, and the habits that keep it working for you.
Advantages
- Simple set of reach levels that anyone can learn.
- System scope keeps infrastructure keys away from pipelines.
- Folders give team-sized isolation with little setup.
- Secrets are encrypted, masked in logs, and never shown again.
- Lookup is predictable: nearest match wins.
- Works with permission plugins and external secret managers.
Disadvantages and trade-offs
- The Global name suggests more safety than it gives.
- Anyone who can edit a pipeline in scope can use the secret.
- Administrators can decrypt everything.
- Masking is weak against altered values.
- Folder layouts must match team boundaries to be useful.
- Rotation and cleanup need human discipline.
Best practices in one place
- Choose the smallest scope that works. System first, then a folder, then global.
- Put infrastructure secrets in System scope, so no pipeline can reach them.
- Organise folders by team, and store team secrets in the team folder.
- Match permissions to folders. Only the right people may create, update, and use each store.
- Give each credential one purpose, one environment, and the least power that works.
- Name credentials clearly, with an owner and a rotation date in the description.
- Bind secrets narrowly, and use single quotes for commands that read them.
- Review who can change pipelines that touch valuable secrets.
- Rotate on a schedule, and immediately after any suspected exposure.
- Audit quarterly, and remove credentials that nobody owns or uses.
- Protect the Jenkins home and backups, and test restoring them.
The mistakes seen most often
Mistake 1: agent keys in global scope
The SSH key used to connect to agents is stored as a Global credential. Any pipeline can now load it. The fix is to move it to System scope, and rotate it, since it may already have been exposed.
Mistake 2: trusting the dropdown
A team believes a secret is safe because it does not appear in their credential dropdown. But a Jenkinsfile can name any ID that is in scope. The fix is to rely on folders and scope, not on hidden menus.
Mistake 3: shadowing by accident
A folder credential has the same ID as a global one. After the global secret is rotated, the folder’s jobs still use the old value and fail. The fix is unique, meaningful IDs.
Mistake 4: personal tokens in shared pipelines
A pipeline depends on one developer’s personal token. When they leave, the pipeline breaks. The fix is a team-owned credential in the team folder.
Mistake 5: one token for every environment
The same deployment token opens testing and production. A mistake in a test job can change production. The fix is one credential for each environment.
20Worked Scenario: Untangling a Shared Jenkins
Let us take one imaginary company and tidy its credentials step by step.
The starting point
A company runs one Jenkins for three teams: Payments, Search, and Mobile. Over three years, everyone created credentials at the top level in Global scope. There are forty of them, with names such as “key1” and “deploy-new”. Nobody is sure which are still used. Last month, a Search developer testing a pipeline accidentally pushed a test build to the Payments staging system, because the Payments deploy key was visible to every job.
Take an inventory
List every credential with its type, scope, and ID. Use usage records and job configurations to find out what uses each one. Note the ones that nothing uses.
Classify each credential
Infrastructure only, one team only, or truly shared. Of the forty, six are agent and cloud keys, twenty-four belong to a single team, four are shared read-only tokens, and six have no user at all.
Create folders and move team secrets
Jobs are arranged into Payments, Search, and Mobile folders. New credentials with clear names are created in each folder and the pipelines are updated to use them.
Move infrastructure keys to System scope
The six agent and cloud keys become System credentials, hidden from pipelines. Because they were exposed before, they are also rotated.
Rotate and delete
Every old global team credential is rotated, since it was widely visible, and the old versions are deleted. The six unused credentials are removed after a warning period.
Set permissions and a review habit
Each team lead manages their own folder’s credentials. Developers may use, but not create or delete. A quarterly review keeps the list clean.
| Group | Count | Before | After |
|---|---|---|---|
| Agent and cloud keys | 6 | Global scope, reachable by any pipeline | System scope, rotated |
| Team deployment and registry secrets | 24 | Global scope, visible to all teams | In each team’s folder, rotated |
| Shared read-only tokens | 4 | Global scope | Global scope, with clear IDs and an owner |
| Unused credentials | 6 | Global scope, no owner | Deleted |
Tidying a shared office key cupboard follows the same steps. Count the keys, label them, give each department its own box, move the building’s master keys to the caretaker’s safe, change the locks on anything that was left in the open, and throw away the keys nobody can identify.
The numbers here are made up to show the pattern. Do the migration in small steps, one folder at a time, and test each pipeline after moving its credentials. Rotating everything in a single evening is a recipe for a very long night.
21Real-World Usage Patterns
Here is how credential scopes tend to be arranged in real Jenkins installations. 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 large engineering organisations have publicly described running it for many teams at once. What tends to be common is a habit of separating infrastructure secrets from pipeline secrets, giving teams their own folders, and moving the most valuable secrets into dedicated secret managers. The patterns below show that habit in practice.
Pattern: a small team with a simple setup
A team of eight keeps a handful of global credentials for its registry and its cloud account, and one System credential for its agents. Everyone can use everything, and the risk is accepted knowingly because the group is small and trusted.
Pattern: a platform team serving many product teams
A platform team runs Jenkins for the company. Each product team gets a folder with its own credentials and its own permissions. The platform team alone manages System and Global scopes.
Pattern: production secrets in a vault
A company keeps production deployment secrets in an external secret manager. Jenkins fetches short-lived tokens when a release stage starts, and the folder for each team can reach only its own secret paths.
Pattern: separate credentials for pull requests
An open project builds outside contributions with a harmless test token, and only builds from trusted branches receive credentials that can publish packages.
Pattern: several controllers for several trust levels
An organisation with strict rules runs one Jenkins for experimental work and another for production releases. Secrets for production never exist on the experimental server at all.
Jenkins is often used together with Docker, Kubernetes, and cloud platforms, each of which has its own way of scoping access. The best results come when Jenkins scopes and target-system permissions are both narrow, so that a mistake in one layer is caught by the other.
22Frequently Asked Questions
withCredentials step around only those commands. The secret is then available only inside that block, which is safer than binding it for a whole pipeline.23Summary and Key Takeaways
Key Takeaways
- A scope decides who can reach a credential. System scope is for Jenkins itself, Global scope is for every job on that Jenkins, and folders narrow the reach to one team’s jobs.
- Global does not mean safe. It means wide inside Jenkins, so anyone who can write a pipeline in scope can use the secret in a build.
- Infrastructure keys belong in System scope. Agent connections, cloud plugins, and notification logins should never be reachable from a pipeline.
- Use folders to give teams their own secrets. Match folder permissions to team boundaries, so a leak or a mistake stays small.
- Lookup goes from the nearest store outward. The closest match wins, so keep IDs unique and meaningful to avoid shadowing surprises.
- Bind narrowly and protect the storage. Use the shortest binding that works, single quotes for secret-using commands, and guard the Jenkins home and its backups like a vault.
- Review, rotate, and delete. Give every credential an owner and a rotation date, review the list each quarter, and remove what nobody uses.