A plain-language first look before any details.

Jenkins is a free, open-source automation server that builds, tests and delivers software. Its work is written as a pipeline, a recipe stored in a text file called the Jenkinsfile. A credential in Jenkins is a stored secret, such as a password, a token or a key, kept in a protected vault instead of inside the recipe.

Jenkins supports several kinds of credentials. Two are the focus of this guide.

Both types belong to the same family, they are stored the same way, and they are protected by the same permissions. The difference is in shape and delivery, and that difference decides how safe, how convenient and how reliable your pipeline will be.

The problem it solves and how the idea grew.

The problem: secrets in the wrong places

In the early days, teams put secrets wherever was easiest: typed into the job’s settings page, written in shell scripts, saved in files committed to the code repository. Each of these places has a flaw. Job settings pages are visible to many administrators. Scripts get copied into chat messages and tickets. Code repositories keep every version forever, so a secret removed today still lives in history, and anyone who ever cloned the code has it.

The idea: keep secrets apart from recipes

The credentials store separates two things that should never be mixed. The recipe says what to do. The vault says what secret to use. The recipe refers to a secret only by a nickname, called an ID. The real value is fetched from the vault at the moment it is needed, and only for the steps that need it.

A handful of small ideas that make everything else easy.

Controller and agent

Jenkins has a main server, the controller, which stores settings and schedules work. The machines that really run your commands are agents. Secrets live on the controller and travel to an agent only when a build needs them.

Credential ID

Every credential has an ID, a short unique label such as payments-deploy-token. Pipelines refer to the credential by this ID. Choose readable IDs, because you will see them in many pipeline files.

Scope

The scope says who may use the credential. Global scope means jobs across Jenkins may use it. System scope means only Jenkins itself, not jobs, may use it. Credentials can also be placed in a folder, so only the jobs inside that folder can see them.

Binding

To bind a credential means to attach it to a variable for a short time. Inside a bound block, the build can read the variable. When the block ends, the binding disappears.

Masking

Masking is Jenkins’ habit of replacing a known secret value with asterisks whenever it appears in the build log. It is a safety net, not a lock, and Chapter 12 explains exactly how far it goes.

Which parts of Jenkins take part when a secret is used.

A secret is used through a chain of cooperating parts. Understanding the chain explains almost every surprising behavior you will meet later.

flowchart LR
    ADM["Administrator adds credential"] --> VAULT["Credentials Store on Controller"]
    VAULT --> ENC["Encrypted at rest"]
    JF["Jenkinsfile asks for ID"] --> BIND["Credentials Binding"]
    BIND --> VAULT
    BIND -->|"secret text"| ENV["Environment variable on agent"]
    BIND -->|"secret file"| TMP["Temporary file on agent"]
    ENV --> TOOL["Tool or script"]
    TMP --> TOOL
    BIND --> MASK["Log masking"]
    TOOL --> LOG["Build log"]
    MASK --> LOG

Read the diagram from left to right. An administrator adds the credential to the store on the controller, where it is kept encrypted. When a build reaches a step that asks for an ID, the binding component fetches the value. For secret text it is placed in an environment variable. For secret file, Jenkins writes a temporary file on the agent and places its path in the variable instead. The tool uses the value or the file. Meanwhile the masking component watches the log and hides known secret values.

The simple one: a single private string.

Secret text stores one string of characters. When you create it, you type or paste the value into a single box, give it an ID and a description, and save. From then on, the value is never shown again on the page. You can replace it, but you cannot read it back.

What it is good for

• Access tokens for code hosting services, chat tools and quality-scanning tools.
• API keys for cloud and payment services.
• Webhook secrets used to check that incoming messages are genuine.
• Passwords that are used alone, without a user name.
• Short one-line values such as license keys or registration codes.

How it reaches the build

When bound, the text is placed in an environment variable with a name you choose. An environment variable is a named value that every program started by that step can read. The tool reads the variable, or the step passes it as an argument. When the bound block ends, the variable disappears from later steps.

Strengths

• Very simple to create and to use.
• No file left behind on the agent.
• Masking works reliably for ordinary one-line values.
• Tiny and fast to handle.

Limits

• Awkward for anything long, structured or spanning many lines.
• Special characters can break commands if quoting is careless.
• Environment variables can be read by every process in the step, and appear in diagnostic output if someone prints them.
• Cannot hold binary data.

The flexible one: a complete private file.

Secret file stores an uploaded file. When you create it, you choose a file from your computer, give it an ID and a description, and save. Jenkins keeps the contents encrypted and remembers the file’s name. Like secret text, the contents cannot be viewed again through the page.

What it is good for

• Cluster configuration files that tell a tool how to connect to a container platform.
• Service account key files in structured formats, given by cloud providers.
• Signing keystores used to sign mobile apps or packages, which are binary.
• Certificates and key bundles for secure connections.
• Environment or settings files containing many values that a tool loads by path.
• Long multi-line secrets such as private keys in text form.

How it reaches the build

When bound, Jenkins writes the file into a temporary folder on the agent, sets restrictive permissions so that only the build’s user can read it, and puts the file’s location into the variable you named. The tool is given the location, not the contents. When the bound block ends, Jenkins deletes the temporary file.

Strengths

• Handles binary data and very large secrets.
• Preserves line breaks and special characters exactly.
• Matches how many tools want to receive their configuration.
• The value itself never sits in an environment variable or on a command line.

Limits

• The secret exists as a real file on the agent, even if briefly.
• Masking of the contents in logs is not something to rely on if the file is printed.
• If a step copies the file elsewhere, the copy may outlive the bound block.
• Slightly more setup and cleanup thinking is required.

The two types compared across everything that matters.

Two rows deserve special attention. The row about what the variable holds explains why the two types are not interchangeable: a tool that expects a token will fail if given a file path, and a tool that expects a file will fail if given the token itself. The row about masking explains why secret file needs extra care in what steps you allow to touch it.

A short set of questions that gives the right answer almost every time.

flowchart TD
    S["I have a secret to store"] --> Q1{"Is it binary data?"}
    Q1 -->|"Yes"| F["Use secret file"]
    Q1 -->|"No"| Q2{"Does the tool want a file path?"}
    Q2 -->|"Yes"| F
    Q2 -->|"No"| Q3{"Is it more than one line or structured?"}
    Q3 -->|"Yes"| F
    Q3 -->|"No"| Q4{"Is it a user name plus password?"}
    Q4 -->|"Yes"| UP["Use username with password type"]
    Q4 -->|"No"| T["Use secret text"]

What you fill in, and what each field means.

In the Jenkins web page you open the credentials area, choose the store and domain, and add a new credential. From the list of kinds you choose secret text or secret file. The form is short.

A naming convention that scales

Choose IDs that answer three questions: which team, which purpose, which environment. For example, payments-registry-token-prod tells you everything at a glance. In a crowded credentials list, vague IDs such as token1 lead to mistakes, like using a production secret in a test job.

Two ways to request a secret, and what each gives you.

A pipeline asks for a credential by its ID and says which variable should carry it. There are two common ways, and both work for both types.

The environment block helper

In the declarative environment section you can assign a variable from a credential ID. For secret text the variable holds the text. For secret file the variable holds the path to a temporary file. Because the variable exists for the whole stage or pipeline, any step, including ones that do not need the secret, can read it. That is convenient but broader than necessary.

The withCredentials step

The withCredentials step wraps a small group of steps. Inside it you list bindings. The one for secret text is called string, and the one for secret file is called file. Each binding names the credential ID and the variable. Outside the wrapped group, the secret does not exist. This is the tighter and usually safer choice.

Other binding types exist for other credential kinds, for example a combined one for user name and password, one for SSH keys and one for certificates. Their names differ, but the principle is identical: name the ID, name the variable, keep the block small.

What happens, in order, for each type.

flowchart TD
    subgraph TXT["Secret text"]
        T1["Step reaches bound block"] --> T2["Controller sends value to agent"]
        T2 --> T3["Value placed in environment variable"]
        T3 --> T4["Masking registered for log"]
        T4 --> T5["Tool reads variable"]
        T5 --> T6["Block ends and variable removed"]
    end
    subgraph FIL["Secret file"]
        F1["Step reaches bound block"] --> F2["Controller sends contents to agent"]
        F2 --> F3["Temporary file created with restricted access"]
        F3 --> F4["Variable holds the file path"]
        F4 --> F5["Tool opens the file"]
        F5 --> F6["Block ends and file deleted"]
    end

The exposure window is the heart of secret safety. A good pipeline makes that window as short and as small as possible, and makes sure that nothing inside the window copies the secret somewhere that outlives it.

A helpful safety net that is easy to overtrust.

When a secret is bound, Jenkins remembers its exact value. If that exact value shows up in the build log, Jenkins replaces it with a row of asterisks before anyone sees it. This is what stops an accidental print statement from publishing your token to everyone who can read the log.

What masking does well

• Hides an exact, unchanged copy of a bound secret text value in the console log.
• Works automatically, with no extra steps from you.
• Protects against simple accidents, such as a tool that echoes its own settings.

What masking cannot do

• Changed values slip through. If a script converts the secret to another encoding, reverses it, splits it into pieces or adds spaces between letters, the changed version no longer matches, and is shown in full.
• File contents are not a masked string. The variable that holds a file path is masked, but if a step prints the contents of the file, whatever is inside appears in the log.
• It works only on the log. Files, artifacts, test reports and chat messages built from secret values are not protected.
• It cannot undo. Once a secret has appeared in a log without masking, it stays there until the log is deleted, and may already have been copied elsewhere.
• It cannot stop a determined insider. Someone who can edit the pipeline can transform the value before printing it.

The single most common way secret text is mishandled.

Pipelines are written in a language called Groovy. In Groovy, text written inside double quotes can contain placeholders that are filled in by Jenkins itself before the command is run. This is called string interpolation. Text in single quotes is passed through untouched, so the placeholder is filled in later by the shell on the agent.

Why the difference matters for secrets

With double quotes, the secret becomes part of the command line itself. Other programs running on the same machine may be able to see command lines. Error messages that quote the failing command can reveal it. Jenkins prints a warning in the log when it detects a secret passed this way, and that warning should never be ignored.

The safe habit

• Write shell commands that use secrets inside single quotes, so the shell, not Jenkins, reads the variable.
• Prefer tools that read secrets from an environment variable or a file, not from a command-line argument.
• If a tool insists on a command-line argument, pass it via the environment variable and let the shell expand it at run time.

Where secret file clearly wins.

Some secrets are not one neat line. A private key in text form spans many lines and includes header and footer lines. A service account key is a structured document full of quotation marks and braces. A certificate bundle may be binary. These are exactly the cases where beginners try secret text and run into trouble.

Why the file type fixes these

A file keeps every byte exactly as uploaded. There is no escaping, no lost line breaks and no encoding problem. The tool simply opens the file. In addition, most tools that need structured or multi-line credentials already know how to read them from a path, so the workflow fits naturally.

A special case: SSH keys

Jenkins has a dedicated credential type for SSH user names with private keys, and it has built-in support in the source control steps. When a tool speaks SSH, use that dedicated type instead of storing the key as text or file. It handles the details, such as passphrases and agents, for you.

Deciding who can reach a secret in the first place.

flowchart TD
    J["Jenkins root store"] --> SYS["System scope: Jenkins internal use only"]
    J --> GL["Global scope: usable by jobs everywhere"]
    J --> F1["Folder: payments team"]
    J --> F2["Folder: search team"]
    F1 --> C1["payments-registry-token-prod"]
    F1 --> C2["payments-signing-keystore"]
    F2 --> C3["search-index-api-key"]
    GL --> C4["shared-chat-notify-token"]

Domains

Within a store, a domain groups credentials and can restrict them to certain web addresses or host names. A domain limited to one server address means the credential will be offered only when talking to that server. This helps stop a secret being used by accident against the wrong system.

Why folder scope is the default choice

Global credentials are easy but broad. Anyone who can create or edit a job on the server can potentially reference them. Folder credentials narrow that circle to the team that owns the secret. As a habit, start at the narrowest scope and widen only with a reason.

Access to secrets is a set of separate rights, not one switch.

Jenkins separates several actions on credentials. Being clear about which people need which action keeps the vault safe without blocking real work.

The uncomfortable truth about use

A person who can write a pipeline that binds a credential can, in principle, make the pipeline do anything with it, including sending it somewhere. Masking will not stop a deliberate leak. So the ability to run pipelines that can see a secret is, in practice, the ability to know the secret. This is why the scope of a credential and the control of who may change the pipeline file matter so much.

What sits on the controller’s disk and how it is protected.

The controller keeps its data in a folder called the Jenkins home. Credentials are saved in a configuration file inside it. The secret values in that file are not written as plain text. They are encrypted, both for secret text and for the contents of secret files.

What this protects against, and what it does not

• Protects: someone who sees only the configuration file, for example in a stray copy or a screenshot, cannot read the secrets from it.
• Does not protect: someone who obtains both the configuration file and the keys can decrypt everything. Backups typically contain both. Treat backups of the Jenkins home as highly sensitive.
• Does not protect: administrators with the right to run scripts on the controller, who can ask Jenkins itself to decrypt credentials.

Because everything is stored inside the controller, controller security is the foundation. Keep it updated, restrict who can log in as an administrator, and limit network access to it.

Knowing the exits is the first step to closing them.

flowchart LR
    S["Bound secret"] --> A["Printed by a step"]
    S --> B["Changed then printed"]
    S --> C["Passed in a double quoted command"]
    S --> D["Copied to workspace"]
    S --> E["Written into an archived artifact"]
    S --> F["Sent to another service by a pipeline"]
    S --> G["Read from process environment by another program"]
    A --> LOG["Build log"]
    B --> LOG
    C --> LOG
    D --> ART["Artifacts and later builds"]
    E --> ART
    F --> EXT["Outside systems"]
    G --> EXT

Notice how many exits involve people, not machines: a debug line added in a hurry, a copy made for convenience, a log pasted into a ticket. Good habits and reviews matter as much as good settings.

A short list of habits that prevent most incidents.

Secrets age. Plan for their replacement from the start.

Rotation means replacing an old secret with a new one, and revoking the old. It limits how long a stolen secret stays useful and reduces the risk from people who once had access and no longer should.

flowchart LR
    R1["Owner creates new secret at the service"] --> R2["Update Jenkins credential with new value"]
    R2 --> R3["Run a test build that uses it"]
    R3 --> R4{"Build works?"}
    R4 -->|"Yes"| R5["Revoke the old secret"]
    R4 -->|"No"| R6["Fix and retry, old secret still valid"]
    R5 --> R7["Record date and next rotation"]
    R6 --> R3

Rotating each type

The most valuable feature for rotation is that pipelines refer to the ID, not the value. Because you replace the value under the same ID, no pipeline files change. Rotation becomes a quick, low-risk maintenance task rather than a project.

When the Jenkins vault is not the only vault.

Large organizations often keep secrets in a dedicated secret manager, such as HashiCorp Vault or the secret services offered by cloud providers. Jenkins plugins can read from these systems and present the secrets as ordinary Jenkins credentials, including secret text and secret file. Pipelines then use the same binding steps they always did, while the real storage, rotation and auditing happen in the specialized system.

Mapping to the two types

A text secret in the external system typically appears as secret text in Jenkins. A binary or file-like secret appears as secret file. So the guidance in this guide about choosing between the two still applies, even when the store is somewhere else.

What happens on the machine where the build really runs.

The agent is where secrets are actually used, so its safety matters. For secret text, the exposure is an environment variable in a running process. For secret file, the exposure is a real file on the agent’s disk for the length of the block.

Shared agents

If many teams share the same long-lived agent, one build may be running next to another. Temporary files are protected by permissions, but a shared machine with many users widens the risk, and a crash may leave a file behind. Keep secrets away from shared agents where you can.

Containers and disposable agents

Running builds in containers or on machines that are created for one build and destroyed afterwards limits exposure sharply. Even if a temporary file is left behind, it disappears when the container does. Disposable agents are the strongest practical defense for secret file use.

Practical cautions

• Do not copy the secret file into the workspace. The workspace is often kept, archived or shared between later builds.
• Do not archive the whole workspace in a build where secrets were handled. Choose specific paths instead.
• Clean the workspace at the end of builds that touched sensitive data, using the post section’s cleanup.
• Mind containers inside builds. If a build runs a container and mounts the secret file into it, remember that the container can read it too.

How to know who uses what, and how to keep the vault tidy as it grows.

Knowing where a credential is used

Before changing or deleting a credential, you need to know which jobs depend on it. Jenkins can track usage of credentials in some setups, and searching your pipeline files for the ID is a simple fallback. Keep a habit of putting the owner and purpose in the description, so a quick look at the list answers most questions.

Auditing

Jenkins audit and logging plugins record who created, changed or deleted a credential and when. Keep those records long enough to answer questions after an incident. An external secret manager typically adds a record of every read as well.

Scale

Credential lookup is quick, so a few hundred entries cause no performance trouble. The real cost of scale is human: people cannot tell which of five hundred entries is safe to change. Use a naming convention, folder-level ownership, and a regular review to remove what is unused. Some teams keep a yearly cleanup day where every owner confirms or retires their credentials.

Reliable ways of arranging secrets in pipelines.

Habits that look fine at first and hurt later.

A checklist to apply to any Jenkins setup today.

Mistakes people make when they are new

Using the wrong type. Giving a tool a token when it wants a path, or a path when it wants a token, produces errors that look like login failures. Read what the tool expects.

Trailing whitespace. A pasted token with a hidden line break at the end fails authentication in ways that are hard to spot. Trim values when you paste.

Forgetting the file’s format. Uploading a file with the wrong line endings or an extra extension can break tools that are strict about it. Upload the file exactly as the provider issued it.

Wrong ID or scope. A typo in the ID, or a credential in a folder the job cannot reach, gives a “could not find credentials” error.

Ignoring warnings. The interpolation warning is real. Fix it the first time it appears.

An honest look at each type.

Trade-offs to weigh

There is no universally right answer. Match the type to the tool, the scope to the team and the storage to your risk. Then write down why, so the next person understands your choices.

How the two types show up in the kinds of teams that run Jenkins at scale.

flowchart TD
    PR["Pull request build"] --> NS["No credentials bound: build and test only"]
    MB["Main branch build"] --> T1["Build and test with no secrets"]
    T1 --> B1["Bind secret text: registry token"]
    B1 --> PUB["Publish package"]
    T1 --> B2["Bind secret file: cluster config"]
    B2 --> DEP["Deploy to cluster"]
    PUB --> CL["Cleanup workspace"]
    DEP --> CL

Follow one imaginary team through a release.

A team owns a booking service. They keep two credentials in their team folder: a secret text called booking-registry-token-prod, used to publish packages, and a secret file called booking-cluster-config-prod, used to deploy. Only release managers can change them, and both are rotated every ninety days.

At no point did a secret appear in code, in a log, or in a place where it lasted longer than needed. The team did not need heroic effort. They chose the right type for each secret, kept the bound blocks small, and followed a few habits.

Symptoms, likely causes and calm fixes.

A calm debugging routine

1. Check the ID in the pipeline against the one in the credentials list, character by character.
2. Check the scope and whether the job’s folder can see the credential.
3. Check the type against what the tool expects: value or path.
4. Check that the variable is used inside the block and not after it ends.
5. Test without printing the secret. Confirm that a file exists or a variable is not empty, never its contents.

Every important word in this guide in one place.

Short answers to the questions that come up most often.

The whole story in a few lines.

Secret text and secret file are two shapes of the same idea: keep the secret in the Jenkins vault, name it by an ID, and attach it to a build only for as long as needed. Secret text delivers a value through a variable and leaves nothing on the disk. Secret file delivers a temporary file and suits anything long, structured or binary. The right choice follows from what the tool expects. The safe use follows from a few habits: small bound blocks, single-quoted commands, narrow scope, no printing, no copying, no secrets for untrusted code, and regular rotation.