Using a Jenkinsfile page - injection via interpolation section unclear

[pascal-eberhard]

trafficstars

Problem with the Using a Jenkinsfile page, source file

Hi, see [https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#injection-via-interpolation], search "Credential mangling", the section, starting with this text and the next section.

The main goal is clear, (better) always use single quotes for variable output. But the correct way part is somewhat weird, (bat 'echo %SECRET_VALUE%').

• Why is the variable name here enclosed by "%" instead of using the '${VAR_NAME}' syntax?
• And why SECRET_VALUE, the variable is never defined.

thanks

[dduportal]

Hello @pascal-eberhard , thanks for reporting.

The answer to your first question is because it's a Windows's environment variable: https://ss64.com/nt/syntax-variables.html. Powershell effectively allows a Unix shell's variable interpolation syntax with the $ sign as prefix, but it's not the default shell called by the Jenkins Pipeline keyword's bat.

Your second question is a good one which underlines an issue in the code snippet: unless I'm mistaken it should be

bat 'echo %EXAMPLE_KEY%'

If it answers your question, would you be willing to contribute to fixing this issue (since you reported it first and understood it correctly)?

[pascal-eberhard]

Ah, ok. The %VAR_NAME% is than something Windows shell specific, ok.

Is this something general, or has it something todo that in the example, the variable value itself contains a '%'? So, if the secret value would contain another special char, instead of '%', it would also be the %VAR_NAME% syntax to escape it in windows?

Thx

[dduportal]

Yes, you totally understand the "why" of this example: the previous example shows an sh extrapolation with the case of a Unix environment variable with a $ in the value, and then the bat example for Windows, so with the % in the value as well.

If you feel like that a sentence could be added to explain this goal, along with the typo fix, do not hesitate to propose a change, that could help future readers and users. I'm asking because I find it harder, as a regular user of this, to explain it clearly, why it seems that you are in the process of fully understanding it right now by reading the doc, which makes you a perfect target for the change :)

[pascal-eberhard]

Ehm, I think there would be a bit more to change.

The section starting with text "Credential mangling ". "Secret value is 'sec%ret'", so contains a "%", OK.

But in the above Unix example, I assume you refer to the first two sections of the "Injection via interpolation" chapter. If so, neigther do I see a "$" in the variable default value, nor a comment like "The value is ..", or do I miss something?

Sure, the "$" is in the list of problematic special chars "contains special characters (e.g. / \ $ & % ^ > < | ;)", but not in the code examples.

[dduportal]

Oh good point, my initial reading was too quick. WDYT starting by fixing the code snippet with something like this?

pipeline {
  agent any
  environment {
    EXAMPLE_KEY = credentials('example-credentials-id') // Secret value is 'se$cr%et'
  }
  stages {
    stage('Example') {
      steps {
          /* WRONG! */
          sh "echo ${EXAMPLE_KEY}"
          bat "echo %EXAMPLE_KEY%"
      }
    }
  }
}

pipeline {
  agent any
  environment {
    EXAMPLE_KEY = credentials('example-credentials-id') // Secret value is 'se$cr%et'
  }
  stages {
    stage('Example') {
      steps {
          /* CORRECT */
          sh 'echo ${EXAMPLE_KEY}'
          bat 'echo %EXAMPLE_KEY%'
      }
    }
  }
}

[zbynek]

The typo was fixed in #5082 . There is already one Linux and one Windows example of injection, maybe this issue can be closed.