Credential scoping (global, folder) in Jenkins - Commands & Configuration

Introduction

Jenkins uses credentials to store secrets like passwords or tokens safely. Credential scoping controls where these secrets can be used, either everywhere (global) or only in specific folders, helping keep secrets secure and organized.

When you want a secret to be available to all jobs in Jenkins, like a global API key.

When you want to limit a secret to only jobs inside a specific folder to reduce risk.

When you have multiple teams using the same Jenkins instance and want to separate their secrets.

When you want to avoid accidental use of sensitive credentials outside their intended scope.

When you want to organize credentials by project or team using folder-level scoping.

Commands

This command adds a credential with global scope to Jenkins using an XML file. Global scope means the credential is available to all jobs and folders.

Terminal

jenkins-cli create-credentials-by-xml system::system::jenkins _ < global-credentials.xml

Expected Output

Created credentials with ID 'global-api-key'

→

system::system::jenkins - Specifies the Jenkins system scope for global credentials

This command adds a credential scoped only to the folder named 'my-folder'. Only jobs inside this folder can use this credential.

Terminal

jenkins-cli create-credentials-by-xml folder:my-folder _ < folder-credentials.xml

Expected Output

Created credentials with ID 'folder-db-password'

→

folder:my-folder - Specifies the folder scope for the credential

Lists all credentials with global scope in Jenkins so you can verify the global credentials exist.

Terminal

jenkins-cli list-credentials system::system::jenkins

Expected Output

[global-api-key]

Lists all credentials scoped to the folder 'my-folder' to verify folder-level credentials.

Terminal

jenkins-cli list-credentials folder:my-folder

Expected Output

[folder-db-password]

Key Concept

If you remember nothing else from this pattern, remember: global credentials are accessible everywhere, but folder-scoped credentials limit access to only jobs inside that folder for better security.

Common Mistakes

Adding sensitive credentials with global scope when they should be limited to a folder.

This exposes secrets to all jobs, increasing security risks.

Use folder-scoped credentials to restrict access only to jobs that need them.

Trying to use a folder-scoped credential in a job outside that folder.

The job cannot access the credential and will fail authentication.

Ensure the job is inside the folder where the credential is scoped or use a global credential.

Not verifying credential scope after creation.

You might think a credential is available when it is not, causing build failures.

Use list-credentials commands to confirm the credential scope.

Summary

Use global scope for credentials needed by all jobs in Jenkins.

Use folder scope to limit credentials to specific folders and improve security.

Verify credential creation and scope with Jenkins CLI list commands.