The credentials store is the built-in, encrypted safe inside Jenkins where secrets are kept, so that jobs can use them by name without ever seeing or printing them.

Start with the word credential. A credential is anything you use to prove who you are: a username and password, a secret token, a private key, or a certificate. When a person logs in to a website, they present a credential. When Jenkins logs in to a code repository or a server, it must present one too.

The credentials store is where Jenkins keeps these credentials. It comes from a core plugin called the Credentials plugin, which is installed with almost every Jenkins. The word “basic” in this guide’s title refers to the standard, built-in kind of store and the basic credential types that come with it, as opposed to advanced setups that connect Jenkins to an outside secrets service.

The big idea: use by name, not by value

When you save a secret in the store, you give it an ID, a short name such as “shop-deploy-key”. From then on, jobs never mention the secret itself. They only say, “Please use the credential called shop-deploy-key.” Jenkins looks up the real secret, hands it to the build at the right moment, and hides it from the log. The secret lives in one place, and everybody else only knows its nickname.

Without a safe, secrets leak. It is only a matter of time.

Think about what Jenkins does all day. It downloads private code, pushes finished packages to storage, deploys software to real servers, and sends messages through mail and chat services. Every one of these actions needs a secret. Before credentials stores existed, teams often pasted secrets directly into the places where they were needed. That caused several troubles.

The credentials store fixes all four. There is one encrypted home for every secret. Jobs refer to it by name. Jenkins hides the values in logs. And changing a secret means editing one entry, and every job that uses it picks up the new value automatically.

A handful of words unlock everything about the credentials store. Learn these and the rest feels natural.

Where do you find the store?

Administrators open the Jenkins menu called Manage Jenkins and choose Credentials, which sits among the security-related options. There you see the stores available, the domains inside them, and the credentials themselves. Each credential appears as a row with its name, kind, ID, and description. The secret value itself is never shown again after you save it. You may replace it, but you cannot read it back.

Not all secrets look alike. Jenkins offers a few basic shapes, each fitting a different need.

Understanding each type in plain words

Let us look at how the pieces fit together, from a saved secret to a running build.

Jenkins has one controller, the brain, and many agents, the workers. The credentials store lives on the controller. When an administrator saves a credential, the controller encrypts it and writes it to its storage folder, called JENKINS_HOME. When a build needs the credential, the controller decrypts it in memory, sends it to the agent for just that build, and the agent uses it and forgets it.

flowchart LR
  ADM["Administrator"] -->|"saves secret"| UI["Jenkins Web Interface"]
  UI --> CTRL["Jenkins Controller"]
  CTRL -->|"encrypt"| ENC["Encryption Keys in secrets folder"]
  CTRL -->|"write encrypted value"| STORE[("Credentials Store in JENKINS_HOME")]
  JOB["Job or Pipeline"] -->|"asks for credential by ID"| CTRL
  CTRL -->|"check permission and scope"| STORE
  STORE -->|"decrypt in memory"| CTRL
  CTRL -->|"temporary secret for one build"| AGT["Build Agent"]
  AGT -->|"uses secret"| TARGET["Repository, Server, or Service"]
  AGT -->|"masked log"| LOG["Build Log"]

Walking through the picture

An administrator saves a secret through the Jenkins web interface. The controller encrypts it using keys kept in a protected folder and writes only the encrypted form into the store. Later, a job asks for the credential by its ID. The controller checks that the job is allowed to use it, decrypts it in memory, and hands a temporary copy to the agent running that build. The agent uses the secret to reach the target, such as a repository or server, and Jenkins masks the value in the build log. When the build ends, the temporary copy is thrown away.

The three kinds of stores

Not every secret should be usable everywhere. Scopes and domains draw the boundaries.

Scope: who may use the credential?

Every credential has a scope that decides where it can be used. The two basic scopes are described below.

This split matters. The password that Jenkins uses to send emails or to connect to an agent should not be something a random job can grab. By giving such credentials system scope, you keep them out of reach of pipeline scripts, so a careless or malicious job cannot read them.

Domains: matching secrets to places

A domain is a group of credentials tied to a certain service or website. For example, you may create a domain for one particular code host, and place its credentials inside. Jenkins then offers those credentials only where a matching address is used. Domains keep long lists tidy and prevent accidentally sending a secret to the wrong service.

Creating a credential takes only a minute. Here is the journey in plain steps.

Naming credential IDs well

A good ID answers three questions at a glance: what service, what purpose, and what level of access. For example, “codehost-readonly-token” tells you much more than “cred1”. Consistent names across the company let people find the right credential without asking, and reduce the risk of picking the wrong one.

Saving a secret is only half the story. The other half is lending it to a build safely.

Three common ways a job uses a credential

The feature that makes binding possible comes from the Credentials Binding plugin. It lets a job say, “For these steps only, make this credential available as a variable.” When the steps end, the variable disappears.

What binding looks like for each type

sequenceDiagram
  participant J as Pipeline
  participant C as Jenkins Controller
  participant S as Credentials Store
  participant A as Build Agent
  participant T as Target Service
  J->>C: Use credential by ID
  C->>S: Check permission and scope
  S-->>C: Return decrypted secret in memory
  C->>A: Send secret for this block only
  A->>T: Log in or call service with secret
  A-->>C: Return output with secret masked
  C->>A: Remove temporary secret after block ends

The lending is short and narrow

Notice the pattern: the secret exists on the agent only for the small block of work that needs it. This is the principle of least exposure. Wrap the credential around only the steps that truly need it, not the whole pipeline. If a build has ten stages and only the last one deploys, only the last one should ever see the deployment password.

Encryption is the heart of the store’s safety. Let us see how it works in simple terms.

When you save a secret, Jenkins does not write the readable value to disk. It first scrambles the value using an encryption key. Only someone who holds the right key can unscramble it. Jenkins keeps its encryption keys in a protected folder, called the secrets folder, inside JENKINS_HOME. The scrambled credentials themselves are kept in a separate settings file.

So there are two ingredients that must be together to recover a secret: the encrypted data, and the keys. An attacker who steals only one of them learns almost nothing. An attacker who steals both can read every secret.

flowchart LR
  SECRET["Plain Secret"] -->|"encrypt with key"| ENC["Encrypted Value"]
  KEYS[("Encryption Keys in secrets folder")] --> ENC
  ENC --> FILE[("Credentials Settings File")]
  FILE -->|"read at build time"| DEC["Decrypt in Memory"]
  KEYS --> DEC
  DEC --> USE["Short Loan to One Build"]

What masking does, and what it does not

While a build runs, Jenkins watches its log. If a bound secret appears in the output, Jenkins replaces it with stars. This is masking, and it prevents the most common accidental leak: a command echoing its own password to the log.

But masking is a safety net, not a guarantee. It works by recognizing the exact secret text. If a secret is changed in some way before it is printed, such as being split into pieces, converted to another form, or embedded inside a longer encoded string, the mask may not recognize it. Also, a careless step can send a secret somewhere other than the log, for example to a file that is later saved as an artifact. So the rule is: never print secrets on purpose, and do not rely on masking as your only protection.

Protecting the keys themselves

Because the keys unlock everything, the secrets folder deserves special care. Restrict file permissions on the controller so only the Jenkins service account can read it. Do not include it in casual backups that many people can access. And never copy it into a code repository or a chat message.

A safe with no rules about who can open it is not much of a safe. Jenkins lets you decide exactly who may see, use, and change credentials.

Permissions in Jenkins are handled by an authorization setting, which decides what each person may do. For credentials, the important permissions are as follows.

A sensible split of duties

Every secret has a life story, from creation to retirement. Managing that whole story is what keeps a store healthy.

Rotation: changing secrets on purpose

Rotation means replacing a secret with a fresh one regularly. Even if a secret was quietly copied by an attacker, rotation makes the stolen copy useless after a while. The credentials store makes rotation easy: edit one entry, and every job that refers to its ID uses the new value from the next build onward. This is a big advantage over secrets copied into many places.

flowchart LR
  A["Issue New Secret at Source"] --> B["Save in Credentials Store under Same ID"]
  B --> C["Jobs Use New Value Automatically"]
  C --> D["Revoke Old Secret at Source"]
  D --> E["Confirm Builds Still Pass"]

The credentials store is only as safe as the habits around it. These rules make it much stronger.

Rules for the secrets themselves

• Least privilege. Give each secret only the powers it needs. A token that only reads code should not also be able to delete repositories.
• Prefer tokens and keys to personal passwords. They can be narrow, expire, and be revoked without affecting a human account.
• Use machine identities. Do not use a real person’s login. When that person leaves, automation must not break, and the account must not stay powerful.
• One secret per purpose. Do not reuse one token for ten different tasks. If it leaks, everything is exposed together.
• Rotate regularly, and immediately after any suspicion of leak.

Rules for using them in builds

• Bind narrowly. Wrap a credential around only the steps that need it.
• Never print secrets. Do not echo them, and do not write them into files that get archived.
• Use the right quoting in pipelines, so that secrets are not exposed in ways masking cannot catch.
• Do not use secrets in untrusted builds. Pull requests from strangers should build without access to any secret.
• Keep secrets out of parameters. Ordinary text parameters are shown in history. Use a hidden password parameter or a stored credential.

Rules for the platform

• Run builds on agents, not on the controller, so build code cannot reach the encryption keys.
• Restrict who can edit pipelines and jobs. Whoever can change a script that uses a credential can often extract it.
• Protect the secrets folder and back it up securely, together with the credentials settings.
• Keep Jenkins and plugins updated. Security fixes for the credentials feature arrive through updates.
• Use HTTPS so secrets typed into the web page are not readable in transit.
• Audit changes. Record who created, changed, or deleted a credential and when.

What happens if the controller disk dies, or you move Jenkins to a new machine? The secrets must survive, without becoming easier to steal.

Because a credential is stored as encrypted data and can only be read with the matching keys, a good backup must include both: the credentials settings and the secrets folder that holds the keys. If you back up only the encrypted settings, then after a disaster you will have scrambled data with no key, and every stored secret is lost. If you carelessly back up the keys together with the data in a place many people can read, you have handed out the whole safe.

When something goes wrong with a credential, a few clues quickly point to the cause.

Common problems and their meanings

Watching for trouble

The console output of a build shows whether a credential was found and bound, and any errors from the target. The Jenkins system log records events from the credentials plugins. The target system, such as the code host or the cloud provider, usually keeps its own log showing which secret was used and whether the attempt succeeded.

The basic credentials store is simple and effective, but it has limits worth knowing.

Basic store versus an external secrets service

Large organizations often connect Jenkins to a dedicated secrets service, such as a vault product or a cloud provider’s secrets manager. In that model, the real secrets live outside Jenkins, Jenkins asks for them only when needed, and they can be short-lived and rotated automatically. The basic store is simpler and perfectly good for small and medium setups. External services add strength and automation, at the cost of more moving parts.

A pattern is a proven habit. An anti-pattern is a tempting shortcut that usually hurts later.

Patterns that work

Anti-patterns to avoid

These habits separate a safe Jenkins from a leaky one.

Best practices

1. Put every secret in the credentials store, and refer to it only by ID.
2. Choose the right type: secret text for tokens, username with password for logins, SSH key for servers, secret file for whole files, certificate for certificate login.
3. Use clear IDs and descriptions that say what the credential is for, who owns it, and when it expires.
4. Use system scope for Jenkins’ own infrastructure secrets, and global scope only for what builds truly need.
5. Keep team secrets in folder stores so teams cannot use each other’s credentials.
6. Use narrow, machine-owned tokens instead of personal passwords, with expiry dates.
7. Bind credentials only around the steps that need them.
8. Never print secrets, and do not rely on masking alone.
9. Do not expose credentials to untrusted pull requests.
10. Limit who can edit pipelines and manage credentials, using role-based permissions.
11. Rotate on a schedule, and immediately after any suspected leak.
12. Back up the credentials settings and the secrets folder together, in a tightly protected place, and practice a restore.
13. Run builds on agents, not on the controller.
14. Audit and clean up regularly, deleting unused credentials and revoking them at the source.
15. Keep Jenkins and its plugins updated to receive security fixes.

Common mistakes

The credentials store sits behind almost every real Jenkins job. Here are common ways teams use it.

A typical growth story

A small team begins by pasting a repository password into a job. After a colleague accidentally posts a log in a chat, they move that password into the credentials store and use it by name. Next they replace the personal password with a limited token owned by an automation account, then give every credential a clear ID and description. As the company grows, each team gets its own folder store, infrastructure secrets move to system scope, and rotation becomes a monthly habit. Finally, the biggest deployments start fetching short-lived secrets from an outside secrets service. At each step the change was small, and the team never had to start over.

You started in a hotel with a locked key cabinet and finished with a full picture of how Jenkins keeps its secrets and lends them safely.