The pipeline library supports the loading of Jenkins credential references from json files by using the Pipeline Utility Steps Plugin
These references can be used to auto lookup credential ids based on patterns. This can be useful to provide automatic ssh keys for test servers or credentials for scm checkouts.
Based on the rules for writing libraries these json files must be places below the resources folder.
💡 The library only works with references/ids so your credentials remain safe in the Jenkins instance.
💡 See Extending with Shared Libraries for more information
In order to parse the files correctly they must be in the following format:
[
{
"pattern": "git@git-ssh\.domain\.tld",
"id": "ssh-git-credentials-id",
"comment": "ssh-git-credentials-comment",
"username": "name-of-the-user"
},
{
"pattern": "https:\/\/git-http\.domain\.tld",
"id": "https-git-credentials-id",
"comment": "https-git-credentials-comment"
"username": "name-of-the-user"
}
]The properties pattern and id are mandatory, the comment and
username properties are optional and can be omitted.
💡 When configuring credentials for the
transferScp the username should be set!
In order to use credentials inside your pipeline script you have to
- load
- parse and
- search for a credential based on a pattern
💡 The pattern is treated as regular expression
The Example is based on the checkoutScm step.
This step loads a json from resources/credentials/scm/credentials.json
and matches the incoming scm url against the entries to find the
credential id to use for checkout
Credential autoLookupSCMCredentials(String scmUrl) {
// load the json
JsonLibraryResource jsonRes = new JsonLibraryResource((DSL) this.steps, CredentialConstants.SCM_CREDENTIALS_PATH)
JSON credentialJson = jsonRes.load()
// parse the credentials
CredentialParser parser = new CredentialParser()
List<Credential> credentials = parser.parse(credentialJson)
// try to find matching credential and return the credential
PatternMatcher matcher = new PatternMatcher()
return (Credential) matcher.getBestMatch(scmUrl, credentials)
}💡 Refer to PatternMatching for more
information on how the getBestMatch algorithm works
If you have retrieved a
Credential
object stored in the variable foundCredential you can use this for example in the
following ways:
withCredentials([usernamePassword(credentialsId: foundCredential.id, passwordVariable: 'passwordVar', usernameVariable: 'usernameVar')]) {
// some block
}checkout(
[$class: 'GitSCM',
branches: [[name: '*/master']],
doGenerateSubmoduleConfigurations: false,
extensions: [],
submoduleCfg: [],
userRemoteConfigs: [[credentialsId: foundCredential.id, url: '[email protected]:group/project.git']]])
sshagent([foundCredential.id]) {
ssh "${foundCredential.host}@localhost" 'pwd'
}