Credentials Store, Secret Text, Files, SSH Keys, Username/Password, Binding, and Secret Hygiene: Guided Hands-On Workflow and Core Operations

1. Lab boundary and preflight

This lab is deliberately local/disposable. Use Jenkins 2.568.3 LTS with Java 21, one trusted disposable agent labeled trusted-cred-lab, and the plugin versions listed in the references. Do not use production credentials, employer repositories, a production controller, or a multi-tenant agent.

# Agent-side, read-only preflight
java -version
git --version
id
pwd
umask

On the controller, record the core/Java/plugin baseline. Confirm that routine builds do not execute on the built-in controller node. The lab should use a dedicated disposable folder named cred-lab.

2. Create four fake credentials in the folder store

Create cred-lab, open Credentials → Folder, and add these lab-only values. The descriptions should say DISPOSABLE TRAINING ONLY.

Generate the disposable SSH key outside SCM and upload it to the folder credential. Never paste the private key into chat, logs, lesson evidence, or source control.

mkdir -p ./cred-lab-input && chmod 700 ./cred-lab-input
printf '%s\n' 'profile=lab-only' > ./cred-lab-input/client.conf
chmod 600 ./cred-lab-input/client.conf
ssh-keygen -t ed25519 -f ./cred-lab-input/id_ed25519 -N '' -C 'jenkins-cred-lab'
ssh-keygen -lf ./cred-lab-input/id_ed25519.pub

3. Bind values narrowly without printing them

Create cred-lab/binding-demo as a Pipeline job. The Pipeline deliberately does not contact any external service. It proves only that Jenkins can resolve the IDs and that the agent receives the correct binding forms.

pipeline {
  agent { label 'trusted-cred-lab' }
  options { skipDefaultCheckout(true); timestamps() }
  stages {
    stage('Identity') {
      steps {
        sh '''
          set -eu
          printf 'job=%s build=%s node=%s workspace=%s\\n' \
            "$JOB_NAME" "$BUILD_NUMBER" "$NODE_NAME" "$WORKSPACE"
        '''
      }
    }
    stage('Bounded credential use') {
      steps {
        withCredentials([
          string(credentialsId: 'lab-secret-text', variable: 'LAB_TOKEN'),
          usernamePassword(credentialsId: 'lab-basic-auth',
                           usernameVariable: 'LAB_USER', passwordVariable: 'LAB_PASS'),
          file(credentialsId: 'lab-secret-file', variable: 'LAB_CONFIG'),
          sshUserPrivateKey(credentialsId: 'lab-ssh-key',
                            keyFileVariable: 'LAB_SSH_KEY', usernameVariable: 'LAB_SSH_USER')
        ]) {
          sh '''
            set -eu
            set +x
            test -n "$LAB_TOKEN"
            test -n "$LAB_USER"
            test -n "$LAB_PASS"
            test -f "$LAB_CONFIG"
            test -f "$LAB_SSH_KEY"
            printf 'credential bindings are present; values intentionally not printed\\n'
            printf 'secret-file-parent=%s\\n' "$(dirname "$LAB_CONFIG")"
            printf 'ssh-key-parent=%s\\n' "$(dirname "$LAB_SSH_KEY")"
            stat -c 'secret-file mode=%a owner=%U size=%s' "$LAB_CONFIG"
            stat -c 'ssh-key mode=%a owner=%U size=%s' "$LAB_SSH_KEY"
            ssh-keygen -lf "$LAB_SSH_KEY"
          '''
        }
      }
    }
  }
}

4. Understand secret-file placement before changing directories

The Credentials Binding documentation warns about binding a file from inside a nested dir. The following pattern can place the temporary file under the browsable workspace subtree:

// RISKY pattern — use only with fake lab data for analysis, not real secrets
dir('subdir') {
  withCredentials([file(credentialsId: 'lab-secret-file', variable: 'FILE')]) {
    sh 'set +x; test -f "$FILE"'
  }
}

Prefer binding outside the nested directory so the secret-file temporary directory is outside that subdirectory, or use an isolated workspace strategy designed for secret-bearing work:

withCredentials([file(credentialsId: 'lab-secret-file', variable: 'FILE')]) {
  dir('subdir') {
    sh 'set +x; test -f "$FILE"; ./consume-lab-config "$FILE"'
  }
}

Do not archive or stash the workspace while the binding is active. A secret copied into another file is no longer protected by the binding cleanup.

5. Prove folder context without broadening it

Create a second disposable Pipeline job credential-outsider at the Jenkins root or in a different folder. Attempt to resolve only the ID lab-secret-text. The expected result is that Jenkins cannot find an accessible credential with that ID in the outsider context. Preserve the resulting error as scope evidence.

pipeline {
  agent { label 'trusted-cred-lab' }
  stages {
    stage('Expected denial') {
      steps {
        withCredentials([string(credentialsId: 'lab-secret-text', variable: 'X')]) {
          sh 'set +x; test -n "$X"'
        }
      }
    }
  }
}

6. Expected observations and evidence

• cred-lab/binding-demo resolves all four IDs and runs only on trusted-cred-lab.
• The console shows no credential values; it shows only non-secret metadata.
• Secret-file and SSH-key paths exist only while their binding block executes.
• The outsider job fails before it can use the folder credential.
• No workspace artifact, stash, report, or archive contains credential values or temporary credential files.

7. Small challenge: choose the correct layer

A job inside cred-lab can resolve lab-secret-text, but an SSH command fails host-key verification. Which layer should you change?

Answer after investigation: not the credential scope. Credential resolution already succeeded. Diagnose the SSH client/known-host trust configuration on the agent. Never disable host-key verification to make the command pass.

8. Cleanup and rollback

1. Delete the outsider job and cred-lab folder after recording non-secret evidence.
2. Confirm the four lab credential IDs no longer appear in the folder store.
3. Delete ./cred-lab-input from the machine where the fake input files were created.
4. Stop/remove only the disposable agent/controller resources created for this course lab.
5. Never delete unrelated credentials, folders, nodes, or build history.

Knowledge check

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.