Upload folder using huggingface_hub

.gitignore

@@ -1 +1 @@
-model_cache/
+model_cache/

Dockerfile

@@ -1,18 +1,10 @@
-FROM python:3.13-slim
+FROM python:3.10-slim
 
 WORKDIR /app
 
-# System deps (important for faiss & torch)
-RUN apt-get update && apt-get install -y \
-    build-essential \
-    git \
-    && rm -rf /var/lib/apt/lists/*
-
-COPY requirements.txt .
-
-RUN pip install --upgrade pip \
-    && pip install --no-cache-dir -r requirements.txt
-
 COPY . .
 
+RUN pip install --upgrade pip
+RUN pip install -r requirements.txt
+
 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,14 +1,3 @@
----
-title: Jenkins Error Explainer
-emoji: 🛠️
-colorFrom: blue
-colorTo: green
-sdk: docker
-sdk_version: "latest"
-app_file: main.py
-pinned: false
----
-
 # Jenkins Error Explainer
 
 A documentation-grounded system that explains Jenkins pipeline errors using official Jenkins documentation.

app.py

@@ -0,0 +1,9 @@
+# app.py - Entry point for HuggingFace Spaces
+import sys
+sys.path.insert(0, ".")
+
+from main import app
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

cli.py

@@ -1,47 +1,47 @@
-# cli.py
-
-import sys
-from explain_error import explain_error
-
-def main():
-    if len(sys.argv) != 2:
-        print("Usage: python cli.py <path_to_jenkins_error_log>")
-        sys.exit(1)
-
-    log_path = sys.argv[1]
-
-    try:
-        with open(log_path, "r", encoding="utf-8") as f:
-            log_text = f.read()
-    except FileNotFoundError:
-        print(f"Error: File not found -> {log_path}")
-        sys.exit(1)
-
-    result = explain_error(log_text)
-
-    if result["error_category"] == "unknown":
-        print(
-            "Warning: This error is not currently supported by the explainer. "
-            "The explanation may be incomplete.\n"
-        )
-
-    print("\n=== Jenkins Error Explanation ===\n")
-    print(f"Error Category:\n{result['error_category']}\n")
-
-    print("Error Summary:")
-    print(result["summary"], "\n")
-
-    print("Likely Causes:")
-    for cause in result["likely_causes"]:
-        print(f"- {cause}")
-    print()
-
-    print("Relevant Documentation:")
-    for ref in result["references"]:
-        print(f"- {ref}")
-
-    print("\n================================\n")
-
-
-if __name__ == "__main__":
-    main()
+# cli.py
+
+import sys
+from explain_error import explain_error
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python cli.py <path_to_jenkins_error_log>")
+        sys.exit(1)
+
+    log_path = sys.argv[1]
+
+    try:
+        with open(log_path, "r", encoding="utf-8") as f:
+            log_text = f.read()
+    except FileNotFoundError:
+        print(f"Error: File not found -> {log_path}")
+        sys.exit(1)
+
+    result = explain_error(log_text)
+
+    if result["error_category"] == "unknown":
+        print(
+            "Warning: This error is not currently supported by the explainer. "
+            "The explanation may be incomplete.\n"
+        )
+
+    print("\n=== Jenkins Error Explanation ===\n")
+    print(f"Error Category:\n{result['error_category']}\n")
+
+    print("Error Summary:")
+    print(result["summary"], "\n")
+
+    print("Likely Causes:")
+    for cause in result["likely_causes"]:
+        print(f"- {cause}")
+    print()
+
+    print("Relevant Documentation:")
+    for ref in result["references"]:
+        print(f"- {ref}")
+
+    print("\n================================\n")
+
+
+if __name__ == "__main__":
+    main()

data/docs/raw/git_scm.txt

@@ -1,206 +1,206 @@
-The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
-
-For a list of other such plugins, see the Pipeline Steps Reference page.
-
-scmGit
-scmGit
-The git plugin provides fundamental git operations for Jenkins projects. It can poll, fetch, checkout, and merge contents of git repositories.
-
-The scmGit parameter of the git plugin is used with the Pipeline SCM checkout step to checkout git repositories into Pipeline workspaces. The Pipeline Syntax Snippet Generator guides the user to select git plugin checkout options and provides online help for each of the options.
-
-Use the Pipeline Snippet Generator to generate a sample pipeline script for the checkout step. Examples of the checkout step include:
-
-Checkout step with defaults
-Checkout step with https and a specific branch
-Checkout step with ssh and a private key credential
-Checkout step with https and changelog disabled
-Checkout step with git protocol and polling disabled
-See the argument descriptions for more details.
-The scmGit parameter of the checkout step provides access to all the Pipeline capabilities provided by the git plugin:
-
-checkout scmGit(userRemoteConfigs: [
-                    [ url: 'https://github.com/jenkinsci/git-plugin' ]
-                ])
-NOTE: The checkout step with the scmGit parameter is the preferred SCM checkout method. For simpler cases that do not require all the capabilities of the git plugin, the git step can also be used.
-
-Use the Pipeline Snippet Generator to generate a sample pipeline script for the checkout step.
-
-The checkout step with the scmGit parameter can be used in many cases where the git step cannot be used. Refer to the git plugin documentation for detailed descriptions of options available to the checkout step. For example, the checkout step supports:
-
-SHA-1 checkout
-Tag checkout
-Submodule checkout
-Sparse checkout
-Large file checkout (LFS)
-Reference repositories
-Branch merges
-Repository tagging
-Custom refspecs
-Timeout configuration
-Changelog calculation against a non-default reference
-Stale branch pruning
-Example: Checkout step with defaults
-Checkout from the git plugin source repository using https protocol, no credentials, and the master branch.
-
-The Pipeline Snippet Generator generates this example:
-
-checkout scmGit(userRemoteConfigs: [
-                    [ url: 'https://github.com/jenkinsci/git-plugin' ]
-                ])
-Example: Checkout step with https and a specific branch
-Checkout from the Jenkins source repository using https protocol, no credentials, and a specific branch (stable-2.289).
-
-The Pipeline Snippet Generator generates this example:
-
-checkout scmGit(branches: [[name: 'stable-2.289']],
-                userRemoteConfigs: [
-                    [ url: 'https://github.com/jenkinsci/jenkins.git' ]
-                ])
-Example: Checkout step with ssh and a private key credential
-Checkout from the git client plugin source repository using ssh protocol, private key credentials, and the master branch. The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.
-
-The Pipeline Snippet Generator generates this example:
-
-checkout changelog: false,
-         scm: scmGit(userRemoteConfigs: [
-                         [ credentialsId: 'my-private-key-credential-id',
-                           url: 'git@github.com:jenkinsci/git-client-plugin.git' ]
-                     ])
-Example: Checkout step with https and changelog disabled
-Checkout from the Jenkins source repository using https protocol, no credentials, the master branch, and changelog calculation disabled. If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed. See the workflow scm step documentation for more changelog details.
-
-The Pipeline Snippet Generator generates this example:
-
-checkout changelog: false,
-         scm: scmGit(userRemoteConfigs: [
-                         [ url: 'https://github.com/jenkinsci/credentials-plugin' ]
-                     ])
-Example: Checkout step with git protocol and polling disabled
-Checkout from the command line git repository using git protocol, no credentials, the master branch, and no polling for changes. If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes. See the workflow scm step documentation for more polling details.
-
-The Pipeline Snippet Generator generates this example:
-
-checkout poll: false,
-         scm: scmGit(userRemoteConfigs: [
-                         [ url: 'git://git.kernel.org/pub/scm/git/git.git' ]
-                     ])
-Argument Descriptions
-userRemoteConfigs
-Specify the repository to track. This can be a URL or a local file path. Note that for super-projects (repositories with submodules), only a local file path or a complete URL is valid. The following are examples of valid git URLs.
-ssh://git@github.com/github/git.git
-git@github.com:github/git.git (short notation for ssh protocol)
-ssh://user@other.host.com/~/repos/R.git (to access the repos/R.git repository in the user's home directory)
-https://github.com/github/git.git
-
-If the repository is a super-project, the location from which to clone submodules is dependent on whether the repository is bare or non-bare (i.e. has a working directory).
-If the super-project is bare, the location of the submodules will be taken from .gitmodules.
-If the super-project is not bare, it is assumed that the repository has each of its submodules cloned and checked out appropriately. Thus, the submodules will be taken directly from a path like ${SUPER_PROJECT_URL}/${SUBMODULE}, rather than relying on information from .gitmodules.
-For a local URL/path to a super-project, git rev-parse --is-bare-repository is used to detect whether the super-project is bare or not.
-For a remote URL to a super-project, the ending of the URL determines whether a bare or non-bare repository is assumed:
-If the remote URL ends with .git, a non-bare repository is assumed.
-If the remote URL does NOT end with .git, a bare repository is assumed.
-Array / List of Nested Object
-url : String
-name : String
-refspec : String
-credentialsId : String
-branches
-List of branches to build. Jenkins jobs are most effective when each job builds only a single branch. When a single job builds multiple branches, the changelog comparisons between branches often show no changes or incorrect changes.
-Array / List of Nested Object
-name : String
-browser
-Defines the repository browser that displays changes detected by the git plugin.
-Nested Choice of Objects
-assembla
-$class: 'BacklogGitRepositoryBrowser'
-bitbucketServer
-bitbucket
-cgit
-fisheye
-gitblit
-$class: 'GitBucketBrowser'
-gitLab
-gitLabBrowser
-gitList
-gitWeb
-$class: 'GiteaBrowser'
-github
-gitiles
-$class: 'GitoriousWeb'
-gogs
-kiln
-phabricator
-redmine
-rhodeCode
-$class: 'ScmManagerGitRepositoryBrowser'
-jbSpace
-$class: 'Stash'
-teamFoundation
-$class: 'TracGitRepositoryBrowser'
-$class: 'TuleapBrowser'
-viewgit
-gitTool : String
-Name of the git tool to be used for this job. Git tool names are defined in "Global Tool Configuration".
-
-extensions
-Extensions add new behavior or modify existing plugin behavior for different uses. Extensions help users more precisely tune plugin behavior to meet their needs.
-
-Extensions include:
-
-Clone extensions modify the git operations that retrieve remote changes into the agent workspace. The extensions can adjust the amount of history retrieved, how long the retrieval is allowed to run, and other retrieval details.
-Checkout extensions modify the git operations that place files in the workspace from the git repository on the agent. The extensions can adjust the maximum duration of the checkout operation, the use and behavior of git submodules, the location of the workspace on the disc, and more.
-Changelog extensions adapt the source code difference calculations for different cases.
-Tagging extensions allow the plugin to apply tags in the current workspace.
-Build initiation extensions control the conditions that start a build. They can ignore notifications of a change or force a deeper evaluation of the commits when polling.
-Merge extensions can optionally merge changes from other branches into the current branch of the agent workspace. They control the source branch for the merge and the options applied to the merge.
-Array / List of Nested Choice of Objects
-authorInChangelog
-$class: 'BitbucketEnvVarExtension'
-$class: 'BuildChooserSetting'
-buildSingleRevisionOnly
-changelogToBranch
-checkoutOption
-cleanBeforeCheckout
-cleanAfterCheckout
-cloneOption
-$class: 'CodeCommitURLHelper'
-$class: 'DisableRemotePoll'
-$class: 'ExcludeFromChangeSet'
-$class: 'ExcludeFromPoll'
-$class: 'FallbackToOtherRepositoryGitSCMExtension'
-firstBuildChangelog
-$class: 'GitClientAuthenticatorExtension'
-lfs
-$class: 'GitSCMChecksExtension'
-$class: 'GitSCMStatusChecksExtension'
-$class: 'GitTagMessageExtension'
-$class: 'IgnoreNotifyCommit'
-localBranch
-$class: 'MessageExclusion'
-$class: 'PathRestriction'
-perBuildTag
-$class: 'PreBuildMerge'
-pretestedIntegration
-pruneStaleBranch
-pruneTags
-$class: 'RelativeTargetDirectory'
-$class: 'ScmName'
-sparseCheckout
-submodule
-$class: 'UserExclusion'
-$class: 'UserIdentity'
-$class: 'WipeWorkspace'
-doGenerateSubmoduleConfigurations : boolean (optional)
-Removed facility that was intended to test combinations of git submodule versions. Removed in git plugin 4.6.0. Ignores the user provided value and always uses false as its value.
-
-submoduleCfg (optional)
-Removed facility that was intended to test combinations of git submodule versions. Removed in git plugin 4.6.0. Ignores the user provided value(s) and always uses empty values.
-
-Array / List of Nested Object
-submoduleName : String
-Removed in git plugin 4.6.0.
-
-branches : Array / List of String
-Removed in git plugin 4.6.0.
-
+The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
+
+For a list of other such plugins, see the Pipeline Steps Reference page.
+
+scmGit
+scmGit
+The git plugin provides fundamental git operations for Jenkins projects. It can poll, fetch, checkout, and merge contents of git repositories.
+
+The scmGit parameter of the git plugin is used with the Pipeline SCM checkout step to checkout git repositories into Pipeline workspaces. The Pipeline Syntax Snippet Generator guides the user to select git plugin checkout options and provides online help for each of the options.
+
+Use the Pipeline Snippet Generator to generate a sample pipeline script for the checkout step. Examples of the checkout step include:
+
+Checkout step with defaults
+Checkout step with https and a specific branch
+Checkout step with ssh and a private key credential
+Checkout step with https and changelog disabled
+Checkout step with git protocol and polling disabled
+See the argument descriptions for more details.
+The scmGit parameter of the checkout step provides access to all the Pipeline capabilities provided by the git plugin:
+
+checkout scmGit(userRemoteConfigs: [
+                    [ url: 'https://github.com/jenkinsci/git-plugin' ]
+                ])
+NOTE: The checkout step with the scmGit parameter is the preferred SCM checkout method. For simpler cases that do not require all the capabilities of the git plugin, the git step can also be used.
+
+Use the Pipeline Snippet Generator to generate a sample pipeline script for the checkout step.
+
+The checkout step with the scmGit parameter can be used in many cases where the git step cannot be used. Refer to the git plugin documentation for detailed descriptions of options available to the checkout step. For example, the checkout step supports:
+
+SHA-1 checkout
+Tag checkout
+Submodule checkout
+Sparse checkout
+Large file checkout (LFS)
+Reference repositories
+Branch merges
+Repository tagging
+Custom refspecs
+Timeout configuration
+Changelog calculation against a non-default reference
+Stale branch pruning
+Example: Checkout step with defaults
+Checkout from the git plugin source repository using https protocol, no credentials, and the master branch.
+
+The Pipeline Snippet Generator generates this example:
+
+checkout scmGit(userRemoteConfigs: [
+                    [ url: 'https://github.com/jenkinsci/git-plugin' ]
+                ])
+Example: Checkout step with https and a specific branch
+Checkout from the Jenkins source repository using https protocol, no credentials, and a specific branch (stable-2.289).
+
+The Pipeline Snippet Generator generates this example:
+
+checkout scmGit(branches: [[name: 'stable-2.289']],
+                userRemoteConfigs: [
+                    [ url: 'https://github.com/jenkinsci/jenkins.git' ]
+                ])
+Example: Checkout step with ssh and a private key credential
+Checkout from the git client plugin source repository using ssh protocol, private key credentials, and the master branch. The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.
+
+The Pipeline Snippet Generator generates this example:
+
+checkout changelog: false,
+         scm: scmGit(userRemoteConfigs: [
+                         [ credentialsId: 'my-private-key-credential-id',
+                           url: 'git@github.com:jenkinsci/git-client-plugin.git' ]
+                     ])
+Example: Checkout step with https and changelog disabled
+Checkout from the Jenkins source repository using https protocol, no credentials, the master branch, and changelog calculation disabled. If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed. See the workflow scm step documentation for more changelog details.
+
+The Pipeline Snippet Generator generates this example:
+
+checkout changelog: false,
+         scm: scmGit(userRemoteConfigs: [
+                         [ url: 'https://github.com/jenkinsci/credentials-plugin' ]
+                     ])
+Example: Checkout step with git protocol and polling disabled
+Checkout from the command line git repository using git protocol, no credentials, the master branch, and no polling for changes. If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes. See the workflow scm step documentation for more polling details.
+
+The Pipeline Snippet Generator generates this example:
+
+checkout poll: false,
+         scm: scmGit(userRemoteConfigs: [
+                         [ url: 'git://git.kernel.org/pub/scm/git/git.git' ]
+                     ])
+Argument Descriptions
+userRemoteConfigs
+Specify the repository to track. This can be a URL or a local file path. Note that for super-projects (repositories with submodules), only a local file path or a complete URL is valid. The following are examples of valid git URLs.
+ssh://git@github.com/github/git.git
+git@github.com:github/git.git (short notation for ssh protocol)
+ssh://user@other.host.com/~/repos/R.git (to access the repos/R.git repository in the user's home directory)
+https://github.com/github/git.git
+
+If the repository is a super-project, the location from which to clone submodules is dependent on whether the repository is bare or non-bare (i.e. has a working directory).
+If the super-project is bare, the location of the submodules will be taken from .gitmodules.
+If the super-project is not bare, it is assumed that the repository has each of its submodules cloned and checked out appropriately. Thus, the submodules will be taken directly from a path like ${SUPER_PROJECT_URL}/${SUBMODULE}, rather than relying on information from .gitmodules.
+For a local URL/path to a super-project, git rev-parse --is-bare-repository is used to detect whether the super-project is bare or not.
+For a remote URL to a super-project, the ending of the URL determines whether a bare or non-bare repository is assumed:
+If the remote URL ends with .git, a non-bare repository is assumed.
+If the remote URL does NOT end with .git, a bare repository is assumed.
+Array / List of Nested Object
+url : String
+name : String
+refspec : String
+credentialsId : String
+branches
+List of branches to build. Jenkins jobs are most effective when each job builds only a single branch. When a single job builds multiple branches, the changelog comparisons between branches often show no changes or incorrect changes.
+Array / List of Nested Object
+name : String
+browser
+Defines the repository browser that displays changes detected by the git plugin.
+Nested Choice of Objects
+assembla
+$class: 'BacklogGitRepositoryBrowser'
+bitbucketServer
+bitbucket
+cgit
+fisheye
+gitblit
+$class: 'GitBucketBrowser'
+gitLab
+gitLabBrowser
+gitList
+gitWeb
+$class: 'GiteaBrowser'
+github
+gitiles
+$class: 'GitoriousWeb'
+gogs
+kiln
+phabricator
+redmine
+rhodeCode
+$class: 'ScmManagerGitRepositoryBrowser'
+jbSpace
+$class: 'Stash'
+teamFoundation
+$class: 'TracGitRepositoryBrowser'
+$class: 'TuleapBrowser'
+viewgit
+gitTool : String
+Name of the git tool to be used for this job. Git tool names are defined in "Global Tool Configuration".
+
+extensions
+Extensions add new behavior or modify existing plugin behavior for different uses. Extensions help users more precisely tune plugin behavior to meet their needs.
+
+Extensions include:
+
+Clone extensions modify the git operations that retrieve remote changes into the agent workspace. The extensions can adjust the amount of history retrieved, how long the retrieval is allowed to run, and other retrieval details.
+Checkout extensions modify the git operations that place files in the workspace from the git repository on the agent. The extensions can adjust the maximum duration of the checkout operation, the use and behavior of git submodules, the location of the workspace on the disc, and more.
+Changelog extensions adapt the source code difference calculations for different cases.
+Tagging extensions allow the plugin to apply tags in the current workspace.
+Build initiation extensions control the conditions that start a build. They can ignore notifications of a change or force a deeper evaluation of the commits when polling.
+Merge extensions can optionally merge changes from other branches into the current branch of the agent workspace. They control the source branch for the merge and the options applied to the merge.
+Array / List of Nested Choice of Objects
+authorInChangelog
+$class: 'BitbucketEnvVarExtension'
+$class: 'BuildChooserSetting'
+buildSingleRevisionOnly
+changelogToBranch
+checkoutOption
+cleanBeforeCheckout
+cleanAfterCheckout
+cloneOption
+$class: 'CodeCommitURLHelper'
+$class: 'DisableRemotePoll'
+$class: 'ExcludeFromChangeSet'
+$class: 'ExcludeFromPoll'
+$class: 'FallbackToOtherRepositoryGitSCMExtension'
+firstBuildChangelog
+$class: 'GitClientAuthenticatorExtension'
+lfs
+$class: 'GitSCMChecksExtension'
+$class: 'GitSCMStatusChecksExtension'
+$class: 'GitTagMessageExtension'
+$class: 'IgnoreNotifyCommit'
+localBranch
+$class: 'MessageExclusion'
+$class: 'PathRestriction'
+perBuildTag
+$class: 'PreBuildMerge'
+pretestedIntegration
+pruneStaleBranch
+pruneTags
+$class: 'RelativeTargetDirectory'
+$class: 'ScmName'
+sparseCheckout
+submodule
+$class: 'UserExclusion'
+$class: 'UserIdentity'
+$class: 'WipeWorkspace'
+doGenerateSubmoduleConfigurations : boolean (optional)
+Removed facility that was intended to test combinations of git submodule versions. Removed in git plugin 4.6.0. Ignores the user provided value and always uses false as its value.
+
+submoduleCfg (optional)
+Removed facility that was intended to test combinations of git submodule versions. Removed in git plugin 4.6.0. Ignores the user provided value(s) and always uses empty values.
+
+Array / List of Nested Object
+submoduleName : String
+Removed in git plugin 4.6.0.
+
+branches : Array / List of String
+Removed in git plugin 4.6.0.
+
 Was this page helpful?

data/docs/raw/jenkins_credentials_text.txt

@@ -1,125 +1,125 @@
-The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
-
-For a list of other such plugins, see the Pipeline Steps Reference page.
-
-Table of Contents
-Credentials Binding Plugin
-withCredentials: Bind credentials to variables
-Credentials Binding Plugin
-View this plugin on the Plugins site
-
-withCredentials: Bind credentials to variables
-Allows various kinds of credentials (secrets) to be used in idiosyncratic ways. (Some steps explicitly ask for credentials of a particular kind, usually as a credentialsId parameter, in which case this step is unnecessary.) Each binding will define an environment variable active within the scope of the step. You can then use them directly from any other steps that expect environment variables to be set:
-
-node {
-  withCredentials([usernameColonPassword(credentialsId: 'mylogin', variable: 'USERPASS')]) {
-    sh '''
-      set +x
-      curl -u "$USERPASS" https://private.server/ > output
-    '''
-  }
-}
-As another example (use Snippet Generator to see all options):
-
-node {
-  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
-    sh '''
-      set +x
-      curl -H "Token: $TOKEN" https://some.api/
-    '''
-  }
-}
-Note the use of single quotes to define the script (implicit parameter to sh) in Groovy above. You want the secret to be expanded by the shell as an environment variable. The following idiom is potentially less secure, as the secret is interpolated by Groovy and so (for example) typical operating system process listings will accidentally disclose it:
-
-node {
-  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
-    sh /* WRONG! */ """
-      set +x
-      curl -H 'Token: $TOKEN' https://some.api/
-    """
-  }
-}
-At least on Linux, environment variables can be obtained by other processes running in the same account, so you should not run a job which uses secrets on the same node as a job controlled by untrusted parties. In any event, you should always prefer expansion as environment variables to inclusion in the command, since Jenkins visualizations such as Blue Ocean will attempt to detect step parameters containing secrets and refuse to display them.
-
-The secret(s) will be masked (****) in case they are printed to the build log. This prevents you from accidentally disclosing passwords and the like via the log. (Bourne shell set +x, or Windows batch @echo off, blocks secrets from being displayed in echoed commands; but build tools in debug mode might dump all environment variables to standard output/error, or poorly designed network clients might display authentication, etc.) The masking could of course be trivially circumvented; anyone permitted to configure a job or define Pipeline steps is assumed to be trusted to use any credentials in scope however they like.
-
-Beware that certain tools mangle secrets when displaying them. As one example, Bash (as opposed to Ubuntu’s plainer Dash) does so with text containing ' in echo mode:
-
-$ export PASS=foo"'"bar
-$ env|fgrep PASS
-PASS=foo'bar
-$ sh -xc 'echo $PASS'
-+ echo foo'bar
-foo'bar
-$ bash -xc 'echo $PASS'
-+ echo 'foo'\''bar'
-foo'bar
-Mangled secrets can only be detected on a best-effort basis. By default, Jenkins will attempt to mask mangled secrets as they would appear in output of Bourne shell, Bash, Almquist shell and Windows batch. Without these strategies in place, mangled secrets would appear in plain text in log files. In the example above, this would result in:
-
-+ echo 'foo'\''bar'
-****
-This particular issue can be more safely prevented by turning off echo with set +x or avoiding the use of shell metacharacters in secrets.
-
-For bindings which store a secret file, beware that
-
-node {
-  dir('subdir') {
-    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
-      sh 'use $FILE'
-    }
-  }
-}
-is not safe, as $FILE might be inside the workspace (in subdir@tmp/secretFiles/), and thus visible to anyone able to browse the job’s workspace. If you need to run steps in a different directory than the usual workspace, you should instead use
-
-node {
-  withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
-    dir('subdir') {
-      sh 'use $FILE'
-    }
-  }
-}
-to ensure that the secrets are outside the workspace; or choose a different workspace entirely:
-
-node {
-  ws {
-    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
-      sh 'use $FILE'
-    }
-  }
-}
-Also see the Limitations of Credentials Masking blog post for more background.
-
-bindings
-Array / List of Nested Choice of Objects
-aws
-token
-$class: 'AwsBucketCredentialsBinding'
-ociCredentials
-certificate
-ConjurSecretApplianceCredentials
-conjurSecretCredential
-conjurSecretDockerClientCert
-conjurSecretFile
-conjurSecretString
-conjurSecretUsername
-conjurSecretUsernameSSHKey
-dockerCert
-file
-gitlabApiToken
-gitUsernamePassword
-$class: 'KeychainPasswordAndPathBinding'
-OSFBuilderSuiteOpenCommerceAPICredentials
-sshUserPrivateKey
-string
-OSFBuilderSuiteTwoFactorAuthCredentials
-usernameColonPassword
-usernamePassword
-$class: 'VaultCertificateCredentialsBinding'
-vaultFile
-$class: 'VaultSSHUserPrivateKeyBinding'
-vaultString
-$class: 'VaultTokenCredentialBinding'
-$class: 'VaultUsernamePasswordCredentialBinding'
-zip
-azureServicePrincipal
-azureStorage
+The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
+
+For a list of other such plugins, see the Pipeline Steps Reference page.
+
+Table of Contents
+Credentials Binding Plugin
+withCredentials: Bind credentials to variables
+Credentials Binding Plugin
+View this plugin on the Plugins site
+
+withCredentials: Bind credentials to variables
+Allows various kinds of credentials (secrets) to be used in idiosyncratic ways. (Some steps explicitly ask for credentials of a particular kind, usually as a credentialsId parameter, in which case this step is unnecessary.) Each binding will define an environment variable active within the scope of the step. You can then use them directly from any other steps that expect environment variables to be set:
+
+node {
+  withCredentials([usernameColonPassword(credentialsId: 'mylogin', variable: 'USERPASS')]) {
+    sh '''
+      set +x
+      curl -u "$USERPASS" https://private.server/ > output
+    '''
+  }
+}
+As another example (use Snippet Generator to see all options):
+
+node {
+  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
+    sh '''
+      set +x
+      curl -H "Token: $TOKEN" https://some.api/
+    '''
+  }
+}
+Note the use of single quotes to define the script (implicit parameter to sh) in Groovy above. You want the secret to be expanded by the shell as an environment variable. The following idiom is potentially less secure, as the secret is interpolated by Groovy and so (for example) typical operating system process listings will accidentally disclose it:
+
+node {
+  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
+    sh /* WRONG! */ """
+      set +x
+      curl -H 'Token: $TOKEN' https://some.api/
+    """
+  }
+}
+At least on Linux, environment variables can be obtained by other processes running in the same account, so you should not run a job which uses secrets on the same node as a job controlled by untrusted parties. In any event, you should always prefer expansion as environment variables to inclusion in the command, since Jenkins visualizations such as Blue Ocean will attempt to detect step parameters containing secrets and refuse to display them.
+
+The secret(s) will be masked (****) in case they are printed to the build log. This prevents you from accidentally disclosing passwords and the like via the log. (Bourne shell set +x, or Windows batch @echo off, blocks secrets from being displayed in echoed commands; but build tools in debug mode might dump all environment variables to standard output/error, or poorly designed network clients might display authentication, etc.) The masking could of course be trivially circumvented; anyone permitted to configure a job or define Pipeline steps is assumed to be trusted to use any credentials in scope however they like.
+
+Beware that certain tools mangle secrets when displaying them. As one example, Bash (as opposed to Ubuntu’s plainer Dash) does so with text containing ' in echo mode:
+
+$ export PASS=foo"'"bar
+$ env|fgrep PASS
+PASS=foo'bar
+$ sh -xc 'echo $PASS'
++ echo foo'bar
+foo'bar
+$ bash -xc 'echo $PASS'
++ echo 'foo'\''bar'
+foo'bar
+Mangled secrets can only be detected on a best-effort basis. By default, Jenkins will attempt to mask mangled secrets as they would appear in output of Bourne shell, Bash, Almquist shell and Windows batch. Without these strategies in place, mangled secrets would appear in plain text in log files. In the example above, this would result in:
+
++ echo 'foo'\''bar'
+****
+This particular issue can be more safely prevented by turning off echo with set +x or avoiding the use of shell metacharacters in secrets.
+
+For bindings which store a secret file, beware that
+
+node {
+  dir('subdir') {
+    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
+      sh 'use $FILE'
+    }
+  }
+}
+is not safe, as $FILE might be inside the workspace (in subdir@tmp/secretFiles/), and thus visible to anyone able to browse the job’s workspace. If you need to run steps in a different directory than the usual workspace, you should instead use
+
+node {
+  withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
+    dir('subdir') {
+      sh 'use $FILE'
+    }
+  }
+}
+to ensure that the secrets are outside the workspace; or choose a different workspace entirely:
+
+node {
+  ws {
+    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
+      sh 'use $FILE'
+    }
+  }
+}
+Also see the Limitations of Credentials Masking blog post for more background.
+
+bindings
+Array / List of Nested Choice of Objects
+aws
+token
+$class: 'AwsBucketCredentialsBinding'
+ociCredentials
+certificate
+ConjurSecretApplianceCredentials
+conjurSecretCredential
+conjurSecretDockerClientCert
+conjurSecretFile
+conjurSecretString
+conjurSecretUsername
+conjurSecretUsernameSSHKey
+dockerCert
+file
+gitlabApiToken
+gitUsernamePassword
+$class: 'KeychainPasswordAndPathBinding'
+OSFBuilderSuiteOpenCommerceAPICredentials
+sshUserPrivateKey
+string
+OSFBuilderSuiteTwoFactorAuthCredentials
+usernameColonPassword
+usernamePassword
+$class: 'VaultCertificateCredentialsBinding'
+vaultFile
+$class: 'VaultSSHUserPrivateKeyBinding'
+vaultString
+$class: 'VaultTokenCredentialBinding'
+$class: 'VaultUsernamePasswordCredentialBinding'
+zip
+azureServicePrincipal
+azureStorage

data/docs/raw/jenkins_git.txt

@@ -1,110 +1,110 @@
-The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
-
-For a list of other such plugins, see the Pipeline Steps Reference page.
-
-Table of Contents
-Git plugin
-git: Git
-Git plugin
-View this plugin on the Plugins site
-
-git: Git
-The git step performs a clone from the specified repository into a Pipeline workspace.
-
-Use the Pipeline Syntax Snippet Generator to generate a sample pipeline script for the git step. More advanced checkout operations require the checkout step with the scmGit parameter rather than the git step. Examples of the git step include:
-
-Git step with defaults
-Git step with https and a specific branch
-Git step with ssh and a private key credential
-Git step with https and changelog disabled
-Git step with git protocol and polling disabled
-See the argument descriptions for more details.
-The git step is a simplified shorthand for a subset of the more powerful checkout step with the scmGit parameter:
-
-checkout scmGit(branches: [[name: 'main']],
-    userRemoteConfigs: [[url: 'https://git-server/user/repository.git']])
-NOTE: The checkout step with the scmGit parameter is the preferred SCM checkout method. It provides significantly more functionality than the git step.
-
-Use the Pipeline Syntax Snippet Generator to generate a sample pipeline script for the checkout step.
-
-The checkout step with the scmGit parameter can be used in many cases where the git step cannot be used. Refer to the git plugin documentation for detailed descriptions of options available to the scmGit parameter of the checkout step. For example, the git step does not support:
-
-SHA-1 checkout
-Tag checkout
-Submodule checkout
-Sparse checkout
-Large file checkout (LFS)
-Reference repositories
-Branch merges
-Repository tagging
-Custom refspecs
-Timeout configuration
-Changelog calculation against a non-default reference
-Stale branch pruning
-Example: Git step with defaults
-Checkout from the git plugin source repository using https protocol, no credentials, and the master branch.
-
-The Pipeline Syntax Snippet Generator generates this example:
-
-git 'https://github.com/jenkinsci/git-plugin.git'
-Example: Git step with https and a specific branch
-Checkout from the Jenkins source repository using https protocol, no credentials, and a specific branch (stable-2.492). Note that this must be a local branch name like 'master' or 'develop'.
-
-Branch names that are not supported by the git step
-
-Remote branch names like 'origin/master' and 'origin/develop' are not supported as the branch argument
-SHA-1 hashes are not supported as the branch argument
-Tag names are not supported as the branch argument
-Remote branch names, SHA-1 hashes, and tag names are supported by the general purpose scmGit parameter of the checkout step.
-
-The Pipeline Syntax Snippet Generator generates this example:
-
-git branch: 'stable-2.492',
-    url: 'https://github.com/jenkinsci/jenkins.git'
-Example: Git step with ssh and a private key credential
-Checkout from the git client plugin source repository using ssh protocol, private key credentials, and the master branch. The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.
-
-The Pipeline Syntax Snippet Generator generates this example:
-
-git credentialsId: 'my-private-key-credential-id',
-    url: 'git@github.com:jenkinsci/git-client-plugin.git'
-Example: Git step with https and changelog disabled
-Checkout from the Jenkins source repository using https protocol, no credentials, the master branch, and changelog calculation disabled. If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed. See the workflow scm step documentation for more changelog details.
-
-The Pipeline Syntax Snippet Generator generates this example:
-
-git changelog: false,
-    url: 'https://github.com/jenkinsci/credentials-plugin.git'
-Example: Git step with https protocol and polling disabled
-Checkout from the Jenkins platform labeler repository using https protocol, no credentials, the master branch, and no polling for changes. If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes. See the workflow scm step documentation for more polling details.
-
-The Pipeline Syntax Snippet Generator generates this example:
-
-git poll: false,
-    url: 'https://github.com/jenkinsci/platformlabeler-plugin.git'
-Argument Descriptions
-url : String
-URL of the repository to be checked out in the workspace. Required parameter.
-
-Repository URL's should follow the git URL guidelines. Git steps to access a secured repository should provide a Jenkins credential with the credentialsId argument rather than embedding credentials in the URL. Credentials embedded in a repository URL may be visible in console logs or in other log files.
-
-branch : String (optional)
-Branch to be checked out in the workspace. Default is 'master'.
-
-Note that this must be a local branch name like 'master' or 'develop'. Remote branch names like 'origin/master' and 'origin/develop' are not supported as the branch argument. Tag names are not supported as the branch argument. SHA-1 hashes are not supported as the branch argument. Remote branch names, tag names, and SHA-1 hashes are supported by the general purpose checkout step with the scmGit parameter.
-
-changelog : boolean (optional)
-Compute changelog for this job. Default is 'true'.
-
-If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed.
-
-credentialsId : String (optional)
-Identifier of the credential used to access the remote git repository. Default is '<empty>'.
-
-The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.
-
-poll : boolean (optional)
-Poll remote repository for changes. Default is 'true'.
-
-If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes.
-
+The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
+
+For a list of other such plugins, see the Pipeline Steps Reference page.
+
+Table of Contents
+Git plugin
+git: Git
+Git plugin
+View this plugin on the Plugins site
+
+git: Git
+The git step performs a clone from the specified repository into a Pipeline workspace.
+
+Use the Pipeline Syntax Snippet Generator to generate a sample pipeline script for the git step. More advanced checkout operations require the checkout step with the scmGit parameter rather than the git step. Examples of the git step include:
+
+Git step with defaults
+Git step with https and a specific branch
+Git step with ssh and a private key credential
+Git step with https and changelog disabled
+Git step with git protocol and polling disabled
+See the argument descriptions for more details.
+The git step is a simplified shorthand for a subset of the more powerful checkout step with the scmGit parameter:
+
+checkout scmGit(branches: [[name: 'main']],
+    userRemoteConfigs: [[url: 'https://git-server/user/repository.git']])
+NOTE: The checkout step with the scmGit parameter is the preferred SCM checkout method. It provides significantly more functionality than the git step.
+
+Use the Pipeline Syntax Snippet Generator to generate a sample pipeline script for the checkout step.
+
+The checkout step with the scmGit parameter can be used in many cases where the git step cannot be used. Refer to the git plugin documentation for detailed descriptions of options available to the scmGit parameter of the checkout step. For example, the git step does not support:
+
+SHA-1 checkout
+Tag checkout
+Submodule checkout
+Sparse checkout
+Large file checkout (LFS)
+Reference repositories
+Branch merges
+Repository tagging
+Custom refspecs
+Timeout configuration
+Changelog calculation against a non-default reference
+Stale branch pruning
+Example: Git step with defaults
+Checkout from the git plugin source repository using https protocol, no credentials, and the master branch.
+
+The Pipeline Syntax Snippet Generator generates this example:
+
+git 'https://github.com/jenkinsci/git-plugin.git'
+Example: Git step with https and a specific branch
+Checkout from the Jenkins source repository using https protocol, no credentials, and a specific branch (stable-2.492). Note that this must be a local branch name like 'master' or 'develop'.
+
+Branch names that are not supported by the git step
+
+Remote branch names like 'origin/master' and 'origin/develop' are not supported as the branch argument
+SHA-1 hashes are not supported as the branch argument
+Tag names are not supported as the branch argument
+Remote branch names, SHA-1 hashes, and tag names are supported by the general purpose scmGit parameter of the checkout step.
+
+The Pipeline Syntax Snippet Generator generates this example:
+
+git branch: 'stable-2.492',
+    url: 'https://github.com/jenkinsci/jenkins.git'
+Example: Git step with ssh and a private key credential
+Checkout from the git client plugin source repository using ssh protocol, private key credentials, and the master branch. The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.
+
+The Pipeline Syntax Snippet Generator generates this example:
+
+git credentialsId: 'my-private-key-credential-id',
+    url: 'git@github.com:jenkinsci/git-client-plugin.git'
+Example: Git step with https and changelog disabled
+Checkout from the Jenkins source repository using https protocol, no credentials, the master branch, and changelog calculation disabled. If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed. See the workflow scm step documentation for more changelog details.
+
+The Pipeline Syntax Snippet Generator generates this example:
+
+git changelog: false,
+    url: 'https://github.com/jenkinsci/credentials-plugin.git'
+Example: Git step with https protocol and polling disabled
+Checkout from the Jenkins platform labeler repository using https protocol, no credentials, the master branch, and no polling for changes. If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes. See the workflow scm step documentation for more polling details.
+
+The Pipeline Syntax Snippet Generator generates this example:
+
+git poll: false,
+    url: 'https://github.com/jenkinsci/platformlabeler-plugin.git'
+Argument Descriptions
+url : String
+URL of the repository to be checked out in the workspace. Required parameter.
+
+Repository URL's should follow the git URL guidelines. Git steps to access a secured repository should provide a Jenkins credential with the credentialsId argument rather than embedding credentials in the URL. Credentials embedded in a repository URL may be visible in console logs or in other log files.
+
+branch : String (optional)
+Branch to be checked out in the workspace. Default is 'master'.
+
+Note that this must be a local branch name like 'master' or 'develop'. Remote branch names like 'origin/master' and 'origin/develop' are not supported as the branch argument. Tag names are not supported as the branch argument. SHA-1 hashes are not supported as the branch argument. Remote branch names, tag names, and SHA-1 hashes are supported by the general purpose checkout step with the scmGit parameter.
+
+changelog : boolean (optional)
+Compute changelog for this job. Default is 'true'.
+
+If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed.
+
+credentialsId : String (optional)
+Identifier of the credential used to access the remote git repository. Default is '<empty>'.
+
+The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.
+
+poll : boolean (optional)
+Poll remote repository for changes. Default is 'true'.
+
+If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes.
+

data/docs/raw/jenkins_nodes.txt

@@ -1,171 +1,171 @@
-Managing Nodes 
-Table of Contents
-Components of Distributed Builds
-Creating Agents
-Launch inbound agent via Windows Scheduler
-Installing a Jenkins agent on Windows
-Creating a macOS agent for Jenkins
-Components of Distributed Builds
-Builds in a distributed builds architecture use nodes, agents, and executors, which are distinct from the Jenkins controller itself. Understanding what each of these components are is useful when managing nodes:
-
-Jenkins controller
-The Jenkins controller is the Jenkins service itself and where Jenkins is installed. It is also a web server that also acts as a "brain" for deciding how, when, and where to run tasks. Management tasks such as configuration, authorization, and authentication are executed on the controller, which serves HTTP requests. Files written when a Pipeline executes are written to the filesystem on the controller, unless they are off-loaded to an artifact repository such as Nexus or Artifactory.
-
-Nodes
-Nodes are the "machines" on which build agents run. Jenkins monitors each attached node for disk space, free temp space, free swap, clock time/sync, and response time. A node is taken offline if any of these values go outside the configured threshold. Jenkins supports two types of nodes:
-
-agents (described below)
-
-built-in node
-
-The built-in node is a node that exists within the controller process. It is possible to use agents and the build-in node to run tasks. However, running tasks on the built-in node is discouraged for security, performance, and scalability reasons. The number of executors configured for the node determines the node’s ability to run tasks. Set the number of executors to 0 to disable running tasks on the built-in node.
-
-Agents
-Agents manage the task execution on behalf of the Jenkins controller by using executors. An agent is a small (170KB single jar) Java client process that connects to a Jenkins controller and is assumed to be unreliable. An agent can use any operating system that supports Java. Any tools required for building and testing get installed on the node where the agent runs. Because these tools are a part of the node, they can be installed directly or in a container, such as Docker or Kubernetes. Each agent is effectively a process with its own Process Identifier (PID) on the host machine. In practice, nodes and agents are essentially the same but it is good to remember that they are conceptually distinct.
-
-Executors
-An executor is a slot for the execution of tasks. Effectively, it is a thread in the agent. The number of executors on a node defines the number of concurrent tasks that can run. In other words, this determines the number of concurrent Pipeline stages that can execute at the same time. Determine the correct number of executors per build node must be determined based on the resources available on the node and the resources required for the workload. When determining how many executors to run on a node, consider CPU and memory requirements, as well as the amount of I/O and network activity:
-
-One executor per node is the safest configuration.
-
-One executor per CPU core can work well, if the tasks running are small.
-
-Monitor I/O performance, CPU load, memory usage, and I/O throughput carefully when running multiple executors on a node.
-
-Creating Agents
-Jenkins agents are the "workers" that perform operations requested by the Jenkins controller. The Jenkins controller administers the agents and can manage the tooling on the agents. Jenkins agents may be statically allocated or they can be dynamically allocated through systems like Kubernetes, OpenShift, Amazon EC2, Azure, Google Cloud, IBM Cloud, Oracle Cloud, and other cloud providers.
-
-This 30 minute tutorial from Darin Pope creates a Jenkins agent and connects it to a controller.
-
-How to create an agent node in Jenkins
-
-Launch inbound agent via Windows Scheduler
-If you are having trouble getting the inbound agent installed as a Windows service (i.e., you followed the instructions on installing the agent as a service here but it didn’t work), an alternative method of starting the service automatically when Windows starts is to use the Windows Scheduler. 
-
-We take advantage of the Windows Scheduler’s ability to run command at system startup
-
-Configure your node to use the "Launch agents by connecting it to the master" launch method
-
-Click Save
-
-Note the command required to launch the agent
-
-On the new agent node’s Jenkins page, note the agent command line shown. 
-
-It will be like:
-
-java \
-    -jar agent.jar \
-    -url <Jenkins URL> \
-    -secret <secret key> \
-    -name <agent name>
-Obtain the agent.jar file and copy it to your new Windows agent node
-
-In the command line noted in the last step, the "agent.jar" is a hyperlink. Click it to download the agent.jar file.
-
-Copy the agent.jar file to a permanent location on your agent machine
-
-Ensure that you have a java version available on your agent machine
-
-If not, obtain and install a supported version of Java
-
-Run the command manually from a CMD window on your agent to confirm that it works
-
-Open the CMD window
-
-Run the command the one like
-
-java \
-    -jar agent.jar \
-    -url <Jenkins URL> \
-    -secret <secret key> \
-    -name <agent name>
-Go back to the node’s web page in Jenkins.  If everything works then page should say "Agent is connected"
-
-Stop the command (control-c)
-
-Register a new scheduled job to run the same command
-
-Open "Task Scheduler" on your windows machine
-
-Start → Run: task Scheduler
-
-Create a basic task (Menu: Action → Create Basic Task)
-
-First page of the wizard:
-
-Name: Jenkins Agent
-
-Description (optional)
-
-Click Next
-
-Next page of the wizard
-
-When do you want the task to start: select "When the computer starts"
-
-Click Next
-
-Next page of the wizard
-
-What action do you want the task to perform: select "Start a program"
-
-Click Next
-
-Next page of the wizard
-
-Program/Script: enter "java.exe" (or the full path to your java.exe)
-
-Add arguments: enter the rest of the command, like
-
-java
-    -jar agent.jar \
-    -url <Jenkins URL> \
-    -secret <secret key> \
-    -name <agent name>
-eg:
-
-java \
-    -jar D:\Scripts\jenkins\agent.jar \
-    -url http://jenkinshost.example.com \
-    -secret d6a84df1fc4f45ddc9c6ab34b08f13391983ffffffffffb3488b7d5ac77fbc7 \
-    -name buildNode1
-Click Next
-
-Next page of the wizard
-
-Click the check box "Open the Properties dialog for this task when I click Finish
-
-Click Finish
-
-Update the task’s properties
-
-On the General tab
-
-Select the user to run the task as
-
-Select "Run whether user is logged on or not"
-
-On the settings tab
-
-Uncheck "Stop the task if it runs longer than"
-
-Check "Run the task as soon as possible after a scheduled start is missed"
-
-Check "If the task failed, restart every: 10 minutes", and "Attempt to restart up to: 3 times"
-
-Click OK
-
-Start the scheduled task and again check that the agent is connected
-
-Go back to the node’s web page in Jenkins.  If everything works then page should say "Agent is connected"
-
-Installing a Jenkins agent on Windows
-You can install a Jenkins agent on Windows using the command line. In this video, Darin reviews setting up and installing the Jenkins agent, including how to create any necessary files.
-
-How to install a Jenkins agent on Windows
-
-Creating a macOS agent for Jenkins
-This video reviews the process of creating a macOS agent for Jenkins using Java 11.
-
-
+Managing Nodes 
+Table of Contents
+Components of Distributed Builds
+Creating Agents
+Launch inbound agent via Windows Scheduler
+Installing a Jenkins agent on Windows
+Creating a macOS agent for Jenkins
+Components of Distributed Builds
+Builds in a distributed builds architecture use nodes, agents, and executors, which are distinct from the Jenkins controller itself. Understanding what each of these components are is useful when managing nodes:
+
+Jenkins controller
+The Jenkins controller is the Jenkins service itself and where Jenkins is installed. It is also a web server that also acts as a "brain" for deciding how, when, and where to run tasks. Management tasks such as configuration, authorization, and authentication are executed on the controller, which serves HTTP requests. Files written when a Pipeline executes are written to the filesystem on the controller, unless they are off-loaded to an artifact repository such as Nexus or Artifactory.
+
+Nodes
+Nodes are the "machines" on which build agents run. Jenkins monitors each attached node for disk space, free temp space, free swap, clock time/sync, and response time. A node is taken offline if any of these values go outside the configured threshold. Jenkins supports two types of nodes:
+
+agents (described below)
+
+built-in node
+
+The built-in node is a node that exists within the controller process. It is possible to use agents and the build-in node to run tasks. However, running tasks on the built-in node is discouraged for security, performance, and scalability reasons. The number of executors configured for the node determines the node’s ability to run tasks. Set the number of executors to 0 to disable running tasks on the built-in node.
+
+Agents
+Agents manage the task execution on behalf of the Jenkins controller by using executors. An agent is a small (170KB single jar) Java client process that connects to a Jenkins controller and is assumed to be unreliable. An agent can use any operating system that supports Java. Any tools required for building and testing get installed on the node where the agent runs. Because these tools are a part of the node, they can be installed directly or in a container, such as Docker or Kubernetes. Each agent is effectively a process with its own Process Identifier (PID) on the host machine. In practice, nodes and agents are essentially the same but it is good to remember that they are conceptually distinct.
+
+Executors
+An executor is a slot for the execution of tasks. Effectively, it is a thread in the agent. The number of executors on a node defines the number of concurrent tasks that can run. In other words, this determines the number of concurrent Pipeline stages that can execute at the same time. Determine the correct number of executors per build node must be determined based on the resources available on the node and the resources required for the workload. When determining how many executors to run on a node, consider CPU and memory requirements, as well as the amount of I/O and network activity:
+
+One executor per node is the safest configuration.
+
+One executor per CPU core can work well, if the tasks running are small.
+
+Monitor I/O performance, CPU load, memory usage, and I/O throughput carefully when running multiple executors on a node.
+
+Creating Agents
+Jenkins agents are the "workers" that perform operations requested by the Jenkins controller. The Jenkins controller administers the agents and can manage the tooling on the agents. Jenkins agents may be statically allocated or they can be dynamically allocated through systems like Kubernetes, OpenShift, Amazon EC2, Azure, Google Cloud, IBM Cloud, Oracle Cloud, and other cloud providers.
+
+This 30 minute tutorial from Darin Pope creates a Jenkins agent and connects it to a controller.
+
+How to create an agent node in Jenkins
+
+Launch inbound agent via Windows Scheduler
+If you are having trouble getting the inbound agent installed as a Windows service (i.e., you followed the instructions on installing the agent as a service here but it didn’t work), an alternative method of starting the service automatically when Windows starts is to use the Windows Scheduler. 
+
+We take advantage of the Windows Scheduler’s ability to run command at system startup
+
+Configure your node to use the "Launch agents by connecting it to the master" launch method
+
+Click Save
+
+Note the command required to launch the agent
+
+On the new agent node’s Jenkins page, note the agent command line shown. 
+
+It will be like:
+
+java \
+    -jar agent.jar \
+    -url <Jenkins URL> \
+    -secret <secret key> \
+    -name <agent name>
+Obtain the agent.jar file and copy it to your new Windows agent node
+
+In the command line noted in the last step, the "agent.jar" is a hyperlink. Click it to download the agent.jar file.
+
+Copy the agent.jar file to a permanent location on your agent machine
+
+Ensure that you have a java version available on your agent machine
+
+If not, obtain and install a supported version of Java
+
+Run the command manually from a CMD window on your agent to confirm that it works
+
+Open the CMD window
+
+Run the command the one like
+
+java \
+    -jar agent.jar \
+    -url <Jenkins URL> \
+    -secret <secret key> \
+    -name <agent name>
+Go back to the node’s web page in Jenkins.  If everything works then page should say "Agent is connected"
+
+Stop the command (control-c)
+
+Register a new scheduled job to run the same command
+
+Open "Task Scheduler" on your windows machine
+
+Start → Run: task Scheduler
+
+Create a basic task (Menu: Action → Create Basic Task)
+
+First page of the wizard:
+
+Name: Jenkins Agent
+
+Description (optional)
+
+Click Next
+
+Next page of the wizard
+
+When do you want the task to start: select "When the computer starts"
+
+Click Next
+
+Next page of the wizard
+
+What action do you want the task to perform: select "Start a program"
+
+Click Next
+
+Next page of the wizard
+
+Program/Script: enter "java.exe" (or the full path to your java.exe)
+
+Add arguments: enter the rest of the command, like
+
+java
+    -jar agent.jar \
+    -url <Jenkins URL> \
+    -secret <secret key> \
+    -name <agent name>
+eg:
+
+java \
+    -jar D:\Scripts\jenkins\agent.jar \
+    -url http://jenkinshost.example.com \
+    -secret d6a84df1fc4f45ddc9c6ab34b08f13391983ffffffffffb3488b7d5ac77fbc7 \
+    -name buildNode1
+Click Next
+
+Next page of the wizard
+
+Click the check box "Open the Properties dialog for this task when I click Finish
+
+Click Finish
+
+Update the task’s properties
+
+On the General tab
+
+Select the user to run the task as
+
+Select "Run whether user is logged on or not"
+
+On the settings tab
+
+Uncheck "Stop the task if it runs longer than"
+
+Check "Run the task as soon as possible after a scheduled start is missed"
+
+Check "If the task failed, restart every: 10 minutes", and "Attempt to restart up to: 3 times"
+
+Click OK
+
+Start the scheduled task and again check that the agent is connected
+
+Go back to the node’s web page in Jenkins.  If everything works then page should say "Agent is connected"
+
+Installing a Jenkins agent on Windows
+You can install a Jenkins agent on Windows using the command line. In this video, Darin reviews setting up and installing the Jenkins agent, including how to create any necessary files.
+
+How to install a Jenkins agent on Windows
+
+Creating a macOS agent for Jenkins
+This video reviews the process of creating a macOS agent for Jenkins using Java 11.
+
+

data/docs/raw/using_a_jenkinsfile.txt

@@ -1,810 +1,810 @@
-Using a Jenkinsfile 
-Table of Contents
-Creating a Jenkinsfile
-Build
-Test
-Deploy
-Working with your Jenkinsfile
-Using environment variables
-Setting environment variables
-Setting environment variables dynamically
-Handling credentials
-For secret text, usernames and passwords, and secret files
-Secret text
-Usernames and passwords
-Secret files
-For other credential types
-Combining credentials in one step
-String interpolation
-Interpolation of sensitive environment variables
-Injection via interpolation
-Handling parameters
-Handling failure
-Error-handling steps
-Using multiple agents
-Optional step arguments
-Advanced Scripted Pipeline
-Parallel execution
-This section builds on the information covered in Getting started with Pipeline and introduces more useful steps, common patterns, and demonstrates some non-trivial Jenkinsfile examples.
-
-Creating a Jenkinsfile, which is checked into source control [1], provides a number of immediate benefits:
-
-Code review/iteration on the Pipeline
-
-Audit trail for the Pipeline
-
-Single source of truth [2] for the Pipeline, which can be viewed and edited by multiple members of the project.
-
-Pipeline supports two syntaxes, Declarative (introduced in Pipeline 2.5) and Scripted Pipeline. Both of which support building continuous delivery pipelines. Both may be used to define a Pipeline in either the web UI or with a Jenkinsfile, though it’s generally considered a best practice to create a Jenkinsfile and check the file into the source control repository.
-
-Creating a Jenkinsfile
-As discussed in the Defining a Pipeline in SCM, a Jenkinsfile is a text file that contains the definition of a Jenkins Pipeline and is checked into source control. Consider the following Pipeline which implements a basic three-stage continuous delivery pipeline.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-
-    stages {
-        stage('Build') {
-            steps {
-                echo 'Building..'
-            }
-        }
-        stage('Test') {
-            steps {
-                echo 'Testing..'
-            }
-        }
-        stage('Deploy') {
-            steps {
-                echo 'Deploying....'
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-Not all Pipelines will have these same three stages, but it is a good starting point to define them for most projects. The sections below will demonstrate the creation and execution of a simple Pipeline in a test installation of Jenkins.
-
-It is assumed that there is already a source control repository set up for the project and a Pipeline has been defined in Jenkins following these instructions.
-
-Using a text editor, ideally one which supports Groovy syntax highlighting, create a new Jenkinsfile in the root directory of the project.
-
-The Declarative Pipeline example above contains the minimum necessary structure to implement a continuous delivery pipeline. The agent directive, which is required, instructs Jenkins to allocate an executor and workspace for the Pipeline. Without an agent directive, not only is the Declarative Pipeline not valid, it would not be capable of doing any work! By default the agent directive ensures that the source repository is checked out and made available for steps in the subsequent stages.
-
-The stages directive and steps directives are also required for a valid Declarative Pipeline as they instruct Jenkins what to execute and in which stage it should be executed.
-
-For more advanced usage with Scripted Pipeline, the example above node is a crucial first step as it allocates an executor and workspace for the Pipeline. In essence, without node, a Pipeline cannot do any work! From within node, the first order of business will be to checkout the source code for this project. Since the Jenkinsfile is being pulled directly from source control, Pipeline provides a quick and easy way to access the right revision of the source code.
-
-Jenkinsfile (Scripted Pipeline)
-node {
-    checkout scm 
-    /* .. snip .. */
-}
-The checkout step will checkout code from source control; scm is a special variable which instructs the checkout step to clone the specific revision which triggered this Pipeline run.
-Build
-For many projects the beginning of "work" in the Pipeline would be the "build" stage. Typically this stage of the Pipeline will be where source code is assembled, compiled, or packaged. The Jenkinsfile is not a replacement for an existing build tool such as GNU/Make, Maven, Gradle, or others, but rather can be viewed as a glue layer to bind the multiple phases of a project’s development lifecycle (build, test, deploy) together.
-
-Jenkins has a number of plugins for invoking practically any build tool in general use, but this example will simply invoke make from a shell step (sh). The sh step assumes the system is Unix/Linux-based, for Windows-based systems the bat could be used instead.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-
-    stages {
-        stage('Build') {
-            steps {
-                sh 'make' 
-                archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true 
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-The sh step invokes the make command and will only continue if a zero exit code is returned by the command. Any non-zero exit code will fail the Pipeline.
-archiveArtifacts captures the files built matching the include pattern (**/target/*.jar) and saves them to the Jenkins controller for later retrieval.
-Archiving artifacts is not a substitute for using external artifact repositories such as Artifactory or Nexus and should be considered only for basic reporting and file archival.
-
-Test
-Running automated tests is a crucial component of any successful continuous delivery process. As such, Jenkins has a number of test recording, reporting, and visualization facilities provided by a number of plugins. At a fundamental level, when there are test failures, it is useful to have Jenkins record the failures for reporting and visualization in the web UI. The example below uses the junit step, provided by the JUnit plugin.
-
-In the example below, if tests fail, the Pipeline is marked "unstable", as denoted by a yellow ball in the web UI. Based on the recorded test reports, Jenkins can also provide historical trend analysis and visualization.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-
-    stages {
-        stage('Test') {
-            steps {
-                /* `make check` returns non-zero on test failures,
-                * using `true` to allow the Pipeline to continue nonetheless
-                */
-                sh 'make check || true' 
-                junit '**/target/*.xml' 
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-Using an inline shell conditional (sh 'make check || true') ensures that the sh step always sees a zero exit code, giving the junit step the opportunity to capture and process the test reports. Alternative approaches to this are covered in more detail in the Handling failure section below.
-junit captures and associates the JUnit XML files matching the inclusion pattern (**/target/*.xml).
-Deploy
-Deployment can imply a variety of steps, depending on the project or organization requirements, and may be anything from publishing built artifacts to an Artifactory server, to pushing code to a production system.
-
-At this stage of the example Pipeline, both the "Build" and "Test" stages have successfully executed. In essence, the "Deploy" stage will only execute assuming previous stages completed successfully, otherwise the Pipeline would have exited early.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-
-    stages {
-        stage('Deploy') {
-            when {
-              expression {
-                currentBuild.result == null || currentBuild.result == 'SUCCESS' 
-              }
-            }
-            steps {
-                sh 'make publish'
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-Accessing the currentBuild.result variable allows the Pipeline to determine if there were any test failures. In which case, the value would be UNSTABLE.
-Assuming everything has executed successfully in the example Jenkins Pipeline, each successful Pipeline run will have associated build artifacts archived, test results reported upon and the full console output all in Jenkins.
-
-A Scripted Pipeline can include conditional tests (shown above), loops, try/catch/finally blocks, and even functions. The next section will cover this advanced Scripted Pipeline syntax in more detail.
-
-Working with your Jenkinsfile
-The following sections provide details about handling:
-
-specific Pipeline syntax in your Jenkinsfile and
-
-features and functionality of Pipeline syntax which are essential in building your application or Pipeline project.
-
-Using environment variables
-Jenkins Pipeline exposes environment variables via the global variable env, which is available from anywhere within a Jenkinsfile. The full list of environment variables accessible from within Jenkins Pipeline is documented at ${YOUR_JENKINS_URL}/pipeline-syntax/globals#env and includes:
-
-BUILD_ID
-The current build ID, identical to BUILD_NUMBER for builds created in Jenkins versions 1.597+.
-
-BUILD_NUMBER
-The current build number, such as "153".
-
-BUILD_TAG
-String of jenkins-${JOB_NAME}-${BUILD_NUMBER}. Convenient to put into a resource file, a jar file, etc for easier identification.
-
-BUILD_URL
-The URL where the results of this build can be found (for example, http://buildserver/jenkins/job/MyJobName/17/).
-
-EXECUTOR_NUMBER
-The unique number that identifies the current executor (among executors of the same machine) performing this build. This is the number you see in the "build executor status", except that the number starts from 0, not 1.
-
-JAVA_HOME
-If your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to include the bin subdirectory of JAVA_HOME.
-
-JENKINS_URL
-Full URL of Jenkins, such as https://example.com:port/jenkins/ (NOTE: only available if Jenkins URL set in "System Configuration").
-
-JOB_NAME
-Name of the project of this build, such as "foo" or "foo/bar".
-
-NODE_NAME
-The name of the node the current build is running on. Set to 'master' for the Jenkins controller.
-
-WORKSPACE
-The absolute path of the workspace.
-
-Referencing or using these environment variables can be accomplished like accessing any key in a Groovy Map, for example:
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-    stages {
-        stage('Example') {
-            steps {
-                echo "Running ${env.BUILD_ID} on ${env.JENKINS_URL}"
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-Setting environment variables
-Setting an environment variable within a Jenkins Pipeline is accomplished differently depending on whether Declarative or Scripted Pipeline is used.
-
-Declarative Pipeline supports an environment directive, whereas users of Scripted Pipeline must use the withEnv step.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-    environment { 
-        CC = 'clang'
-    }
-    stages {
-        stage('Example') {
-            environment { 
-                DEBUG_FLAGS = '-g'
-            }
-            steps {
-                sh 'printenv'
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-An environment directive used in the top-level pipeline block will apply to all steps within the Pipeline.
-An environment directive defined within a stage will only apply the given environment variables to steps within the stage.
-Setting environment variables dynamically
-Environment variables can be set at run time and can be used by shell scripts (sh), Windows batch scripts (bat) and PowerShell scripts (powershell). Each script can either returnStatus or returnStdout. More information on scripts.
-
-Below is an example in a declarative pipeline using sh (shell) with both returnStatus and returnStdout.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any 
-    environment {
-        // Using returnStdout
-        CC = """${sh(
-                returnStdout: true,
-                script: 'echo "clang"'
-            )}""" 
-        // Using returnStatus
-        EXIT_STATUS = """${sh(
-                returnStatus: true,
-                script: 'exit 1'
-            )}"""
-    }
-    stages {
-        stage('Example') {
-            environment {
-                DEBUG_FLAGS = '-g'
-            }
-            steps {
-                sh 'printenv'
-            }
-        }
-    }
-}
-An agent must be set at the top level of the pipeline. This will fail if agent is set as agent none.
-When using returnStdout a trailing whitespace will be appended to the returned string. Use .trim() to remove this.
-Handling credentials
-Credentials configured in Jenkins can be handled in Pipelines for immediate use. Read more about using credentials in Jenkins on the Using credentials page.
-
-The correct way to handle credentials in Jenkins
-
-For secret text, usernames and passwords, and secret files
-Jenkins' declarative Pipeline syntax has the credentials() helper method (used within the environment directive) which supports secret text, username and password, as well as secret file credentials. If you want to handle other types of credentials, refer to the For other credential types section.
-
-Secret text
-The following Pipeline code shows an example of how to create a Pipeline using environment variables for secret text credentials.
-
-In this example, two secret text credentials are assigned to separate environment variables to access Amazon Web Services (AWS). These credentials would have been configured in Jenkins with their respective credential IDs jenkins-aws-secret-key-id and jenkins-aws-secret-access-key.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent {
-        // Define agent details here
-    }
-    environment {
-        AWS_ACCESS_KEY_ID     = credentials('jenkins-aws-secret-key-id')
-        AWS_SECRET_ACCESS_KEY = credentials('jenkins-aws-secret-access-key')
-    }
-    stages {
-        stage('Example stage 1') {
-            steps {
-                // 
-            }
-        }
-        stage('Example stage 2') {
-            steps {
-                // 
-            }
-        }
-    }
-}
-You can reference the two credential environment variables (defined in this Pipeline’s environment directive), within this stage’s steps using the syntax $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY. For example, here you can authenticate to AWS using the secret text credentials assigned to these credential variables. To maintain the security and anonymity of these credentials, if the job displays the value of these credential variables from within the Pipeline (such as echo $AWS_SECRET_ACCESS_KEY), Jenkins only returns the value “****” to reduce the risk of secret information being disclosed to the console output and any logs. Any sensitive information in credential IDs themselves (such as usernames) are also returned as “****” in the Pipeline run’s output. This only reduces the risk of accidental exposure. It does not prevent a malicious user from capturing the credential value by other means. A Pipeline that uses credentials can also disclose those credentials. Don’t allow untrusted Pipeline jobs to use trusted credentials.
-In this Pipeline example, the credentials assigned to the two AWS_…​ environment variables are scoped globally for the entire Pipeline, so these credential variables could also be used in this stage’s steps. If, however, the environment directive in this Pipeline were moved to a specific stage (as is the case in the Usernames and passwords Pipeline example below), then these AWS_…​ environment variables would only be scoped to the steps in that stage.
-Storing static AWS keys in Jenkins credentials is not very secure. If you can run Jenkins itself in AWS (at least the agent), it is preferable to use IAM roles for a computer or EKS service account. It is also possible to use web identity federation.
-Usernames and passwords
-The following Pipeline code snippets show an example of how to create a Pipeline using environment variables for username and password credentials.
-
-In this example, username and password credentials are assigned to environment variables to access a Bitbucket repository in a common account or team for your organization; these credentials would have been configured in Jenkins with the credential ID jenkins-bitbucket-common-creds.
-
-When setting the credential environment variable in the environment directive:
-
-environment {
-    BITBUCKET_COMMON_CREDS = credentials('jenkins-bitbucket-common-creds')
-}
-this actually sets the following three environment variables:
-
-BITBUCKET_COMMON_CREDS - contains a username and a password separated by a colon in the format username:password.
-
-BITBUCKET_COMMON_CREDS_USR - an additional variable containing the username component only.
-
-BITBUCKET_COMMON_CREDS_PSW - an additional variable containing the password component only.
-
-By convention, variable names for environment variables are typically specified in capital case, with individual words separated by underscores You can, however, specify any legitimate variable name using lower case characters. Bear in mind that the additional environment variables created by the credentials() method (above) will always be appended with _USR and _PSW (i.e. in the format of an underscore followed by three capital letters).
-
-The following code snippet shows the example Pipeline in its entirety:
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent {
-        // Define agent details here
-    }
-    stages {
-        stage('Example stage 1') {
-            environment {
-                BITBUCKET_COMMON_CREDS = credentials('jenkins-bitbucket-common-creds')
-            }
-            steps {
-                // 
-            }
-        }
-        stage('Example stage 2') {
-            steps {
-                // 
-            }
-        }
-    }
-}
-The following credential environment variables (defined in this Pipeline’s environment directive) are available within this stage’s steps and can be referenced using the syntax:
-$BITBUCKET_COMMON_CREDS
-
-$BITBUCKET_COMMON_CREDS_USR
-
-$BITBUCKET_COMMON_CREDS_PSW
-
-For example, here you can authenticate to Bitbucket with the username and password assigned to these credential variables. To maintain the security and anonymity of these credentials, if the job displays the value of these credential variables from within the Pipeline the same behavior described in the Secret text example above applies to these username and password credential variable types too. This only reduces the risk of accidental exposure. It does not prevent a malicious user from capturing the credential value by other means. A Pipeline that uses credentials can also disclose those credentials. Don’t allow untrusted Pipeline jobs to use trusted credentials.
-
-In this Pipeline example, the credentials assigned to the three BITBUCKET_COMMON_CREDS…​ environment variables are scoped only to Example stage 1, so these credential variables are not available for use in this Example stage 2 stage’s steps. If, however, the environment directive in this Pipeline were moved immediately within the pipeline block (as is the case in the Secret text Pipeline example above), then these BITBUCKET_COMMON_CREDS…​ environment variables would be scoped globally and could be used in any stage’s steps.
-Secret files
-A secret file is a credential which is stored in a file and uploaded to Jenkins. Secret files are used for credentials that are:
-
-too unwieldy to enter directly into Jenkins, and/or
-
-in binary format, such as a GPG file.
-
-In this example, we use a Kubernetes config file that has been configured as a secret file credential named my-kubeconfig.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent {
-        // Define agent details here
-    }
-    environment {
-        // The MY_KUBECONFIG environment variable will be assigned the value of a temporary file.
-        // For example:
-        //   /home/user/.jenkins/workspace/cred_test@tmp/secretFiles/546a5cf3-9b56-4165-a0fd-19e2afe6b31f/kubeconfig.txt
-        MY_KUBECONFIG = credentials('my-kubeconfig')
-    }
-    stages {
-        stage('Example stage 1') {
-            steps {
-                sh("kubectl --kubeconfig $MY_KUBECONFIG get pods")
-            }
-        }
-    }
-}
-For other credential types
-If you need to set credentials in a Pipeline for anything other than secret text, usernames and passwords, or secret files like SSH keys or certificates, use Jenkins' Snippet Generator feature, which you can access through Jenkins' classic UI.
-
-To access the Snippet Generator for your Pipeline project/item:
-
-From the Jenkins Dashboard, select the name of your Pipeline project/item.
-
-In the left navigation pane, select Pipeline Syntax and ensure that the Snippet Generator option is available at the top of the navigation pane.
-
-From the Sample Step field, choose withCredentials: Bind credentials to variables.
-
-Under Bindings, click Add and choose from the dropdown:
-
-SSH User Private Key - to handle SSH public/private key pair credentials, from which you can specify:
-
-Key File Variable - the name of the environment variable that will be bound to these credentials. Jenkins actually assigns this temporary variable to the secure location of the private key file required in the SSH public/private key pair authentication process.
-
-Passphrase Variable ( Optional ) - the name of the environment variable that will be bound to the passphrase associated with the SSH public/private key pair.
-
-Username Variable ( Optional ) - the name of the environment variable that will be bound to username associated with the SSH public/private key pair.
-
-Credentials - choose the SSH public/private key credentials stored in Jenkins. The value of this field is the credential ID, which Jenkins writes out to the generated snippet.
-
-Certificate - to handle PKCS#12 certificates, from which you can specify:
-
-Keystore Variable - the name of the environment variable that will be bound to these credentials. Jenkins actually assigns this temporary variable to the secure location of the certificate’s keystore required in the certificate authentication process.
-
-Password Variable ( Optional ) - the name of the environment variable that will be bound to the password associated with the certificate.
-
-Alias Variable ( Optional ) - the name of the environment variable that will be bound to the unique alias associated with the certificate.
-
-Credentials - choose the certificate credentials stored in Jenkins. The value of this field is the credential ID, which Jenkins writes out to the generated snippet.
-
-Docker client certificate - to handle Docker Host Certificate Authentication.
-
-Click Generate Pipeline Script and Jenkins generates a withCredentials(…​) { …​ } Pipeline step snippet for the credentials you specified, which you can then copy and paste into your Declarative or Scripted Pipeline code.
-Notes:
-
-The Credentials fields (above) show the names of credentials configured in Jenkins. However, these values are converted to credential IDs after clicking Generate Pipeline Script.
-
-To combine more than one credential in a single withCredentials(…​) { …​ } Pipeline step, see Combining credentials in one step (below) for details.
-
-SSH User Private Key example
-
-withCredentials(bindings: [sshUserPrivateKey(credentialsId: 'jenkins-ssh-key-for-abc', \
-                                             keyFileVariable: 'SSH_KEY_FOR_ABC', \
-                                             passphraseVariable: '', \
-                                             usernameVariable: '')]) {
-  // some block
-}
-The optional passphraseVariable and usernameVariable definitions can be deleted in your final Pipeline code.
-
-Certificate example
-
-withCredentials(bindings: [certificate(aliasVariable: '', \
-                                       credentialsId: 'jenkins-certificate-for-xyz', \
-                                       keystoreVariable: 'CERTIFICATE_FOR_XYZ', \
-                                       passwordVariable: 'XYZ-CERTIFICATE-PASSWORD')]) {
-  // some block
-}
-The optional aliasVariable and passwordVariable variable definitions can be deleted in your final Pipeline code.
-
-The following code snippet shows an example Pipeline in its entirety, which implements the SSH User Private Key and Certificate snippets above:
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent {
-        // define agent details
-    }
-    stages {
-        stage('Example stage 1') {
-            steps {
-                withCredentials(bindings: [sshUserPrivateKey(credentialsId: 'jenkins-ssh-key-for-abc', \
-                                                             keyFileVariable: 'SSH_KEY_FOR_ABC')]) {
-                  // 
-                }
-                withCredentials(bindings: [certificate(credentialsId: 'jenkins-certificate-for-xyz', \
-                                                       keystoreVariable: 'CERTIFICATE_FOR_XYZ', \
-                                                       passwordVariable: 'XYZ-CERTIFICATE-PASSWORD')]) {
-                  // 
-                }
-            }
-        }
-        stage('Example stage 2') {
-            steps {
-                // 
-            }
-        }
-    }
-}
-Within this step, you can reference the credential environment variable with the syntax $SSH_KEY_FOR_ABC. For example, here you can authenticate to the ABC application with its configured SSH public/private key pair credentials, whose SSH User Private Key file is assigned to $SSH_KEY_FOR_ABC.
-Within this step, you can reference the credential environment variable with the syntax $CERTIFICATE_FOR_XYZ and $XYZ-CERTIFICATE-PASSWORD. For example, here you can authenticate to the XYZ application with its configured certificate credentials, whose Certificate's keystore file and password are assigned to the variables $CERTIFICATE_FOR_XYZ and $XYZ-CERTIFICATE-PASSWORD, respectively.
-In this Pipeline example, the credentials assigned to the $SSH_KEY_FOR_ABC, $CERTIFICATE_FOR_XYZ and $XYZ-CERTIFICATE-PASSWORD environment variables are scoped only within their respective withCredentials( …​ ) { …​ } steps, so these credential variables are not available for use in this Example stage 2 stage’s steps.
-To maintain the security and anonymity of these credentials, if you attempt to retrieve the value of these credential variables from within these withCredentials( …​ ) { …​ } steps, the same behavior described in the Secret text example (above) applies to these SSH public/private key pair credential and certificate variable types too. This only reduces the risk of accidental exposure. It does not prevent a malicious user from capturing the credential value by other means. A Pipeline that uses credentials can also disclose those credentials. Don’t allow untrusted Pipeline jobs to use trusted credentials.
-
-When using the Sample Step field’s withCredentials: Bind credentials to variables option in the Snippet Generator, only credentials which your current Pipeline project/item has access to can be selected from any Credentials field’s list. While you can manually write a withCredentials( …​ ) { …​ } step for your Pipeline (like the examples above), using the Snippet Generator is recommended to avoid specifying credentials that are out of scope for this Pipeline project/item, which when run, will make the step fail.
-
-You can also use the Snippet Generator to generate withCredentials( …​ ) { …​ } steps to handle secret text, usernames and passwords and secret files. However, if you only need to handle these types of credentials, it is recommended you use the relevant procedure described in the section above for improved Pipeline code readability.
-
-The use of single-quotes instead of double-quotes to define the script (the implicit parameter to sh) in Groovy above. The single-quotes will cause the secret to be expanded by the shell as an environment variable. The double-quotes are potentially less secure as the secret is interpolated by Groovy, and so typical operating system process listings will accidentally disclose it :
-
-node {
-  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
-    sh /* WRONG! */ """
-      set +x
-      curl -H 'Token: $TOKEN' https://some.api/
-    """
-    sh /* CORRECT */ '''
-      set +x
-      curl -H 'Token: $TOKEN' https://some.api/
-    '''
-  }
-}
-Combining credentials in one step
-Using the Snippet Generator, you can make multiple credentials available within a single withCredentials( …​ ) { …​ } step by doing the following:
-
-From the Jenkins Dashboard, select the name of your Pipeline project/item.
-
-In the left navigation pane, select Pipeline Syntax and ensure that the Snippet Generator option is available at the top of the navigation pane.
-
-From the Sample Step field, choose withCredentials: Bind credentials to variables.
-
-Click Add under Bindings.
-
-Choose the credential type to add to the withCredentials( …​ ) { …​ } step from the dropdown list.
-
-Specify the credential Bindings details. Read more above these in the procedure under For other credential types (above).
-
-Repeat from "Click Add …​" (above) for each (set of) credential/s to add to the withCredentials( …​ ) { …​ } step.
-
-Select Generate Pipeline Script to generate the final withCredentials( …​ ) { …​ } step snippet.
-
-String interpolation
-Jenkins Pipeline uses rules identical to Groovy for string interpolation. Groovy’s String interpolation support can be confusing to many newcomers to the language. While Groovy supports declaring a string with either single quotes, or double quotes, for example:
-
-def singlyQuoted = 'Hello'
-def doublyQuoted = "World"
-Only the latter string will support the dollar-sign ($) based string interpolation, for example:
-
-def username = 'Jenkins'
-echo 'Hello Mr. ${username}'
-echo "I said, Hello Mr. ${username}"
-Would result in:
-
-Hello Mr. ${username}
-I said, Hello Mr. Jenkins
-Understanding how to use string interpolation is vital for using some of Pipeline’s more advanced features.
-
-Interpolation of sensitive environment variables
-Groovy string interpolation should never be used with credentials.
-
-Groovy GStrings (double-quoted or triple-double-quoted strings) expand ${TOKEN} before the command is sent to the agent. When that happens, the secret is copied into the process arguments (visible via tooling such as ps) and any shell metacharacters inside the secret or user-controlled value are executed immediately. Always send a literal command string to sh, bat, powershell, or pwsh and let the shell read secrets from its environment, which withCredentials or the environment block have already populated.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-    environment {
-        API_TOKEN = credentials('example-token-id')
-    }
-    stages {
-        stage('Example') {
-            steps {
-                /* WRONG */
-                    sh "curl -H 'Authorization: Bearer ${API_TOKEN}' https://example.com"
-                """
-            }
-        }
-    }
-}
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-    environment {
-        API_TOKEN = credentials('example-token-id')
-    }
-    stages {
-        stage('Example') {
-            steps {
-                /* CORRECT */
-                sh 'curl -H "Authorization: Bearer ${API_TOKEN}" https://example.com'
-            }
-        }
-    }
-}
-Any Groovy construct that avoids interpolation (for example, sh(script: 'curl …​ $API_TOKEN', label: 'call API')) is safe; the key is keeping secrets out of GStrings so only the shell expands them.
-
-Injection via interpolation
-Groovy string interpolation can inject rogue commands into command interpreters via special characters.
-
-Another note of caution. Using Groovy string interpolation for user-controlled variables with steps that pass their arguments to command interpreters such as the sh, bat, powershell, or pwsh steps can result in problems analogous to SQL injection. This occurs when a user-controlled variable (generally an environment variable, usually a parameter passed to the build) that contains special characters (e.g. / \ $ & % ^ > < | ;) is passed to the sh, bat, powershell, or pwsh steps using Groovy interpolation. For a simple example:
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-  agent any
-  parameters {
-    string(name: 'STATEMENT', defaultValue: 'hello; ls /', description: 'What should I say?')
-  }
-  stages {
-    stage('Example') {
-      steps {
-        /* WRONG! */
-        sh("echo ${STATEMENT}")
-      }
-    }
-  }
-}
-In this example, the argument to the sh step is evaluated by Groovy, and STATEMENT is interpolated directly into the argument as if sh('echo hello; ls /') has been written in the Pipeline. When this is processed on the agent, rather than echoing the value hello; ls /, it will echo hello then proceed to list the entire root directory of the agent. Any user able to control a variable interpolated by such a step would be able to make the sh step run arbitrary code on the agent. To avoid this problem, make sure arguments to steps such as sh or bat that reference parameters or other user-controlled environment variables use single quotes to avoid Groovy interpolation.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-  agent any
-  parameters {
-    string(name: 'STATEMENT', defaultValue: 'hello; ls /', description: 'What should I say?')
-  }
-  stages {
-    stage('Example') {
-      steps {
-        /* CORRECT */
-        sh('echo ${STATEMENT}')
-      }
-    }
-  }
-}
-Credential mangling is another issue that can occur when credentials that contain special characters are passed to a step using Groovy interpolation. When the credential value is mangled, it is no longer valid and will no longer be masked in the console log.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-  agent any
-  environment {
-    EXAMPLE_KEY = credentials('example-credentials-id') // Secret value is 'sec%ret'
-  }
-  stages {
-    stage('Example') {
-      steps {
-          /* WRONG! */
-          bat "echo ${EXAMPLE_KEY}"
-      }
-    }
-  }
-}
-Here, the bat step receives echo sec%ret and the Windows batch shell will simply drop the % and print out the value secret. Because there is a single character difference, the value secret will not be masked. Though the value is not the same as the actual credential, this is still a significant exposure of sensitive information. Again, single-quotes avoids this issue.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-  agent any
-  environment {
-    EXAMPLE_KEY = credentials('example-credentials-id') // Secret value is 'sec%ret'
-  }
-  stages {
-    stage('Example') {
-      steps {
-          /* CORRECT */
-          bat 'echo %EXAMPLE_KEY%'
-      }
-    }
-  }
-}
-Handling parameters
-Declarative Pipeline supports parameters out-of-the-box, allowing the Pipeline to accept user-specified parameters at runtime via the parameters directive. Configuring parameters with Scripted Pipeline is done with the properties step, which can be found in the Snippet Generator.
-
-If you configured your pipeline to accept parameters using the Build with Parameters option, those parameters are accessible as members of the params variable.
-
-Assuming that a String parameter named "Greeting" has been configured in the Jenkinsfile, it can access that parameter via ${params.Greeting}:
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-    parameters {
-        string(name: 'Greeting', defaultValue: 'Hello', description: 'How should I greet the world?')
-    }
-    stages {
-        stage('Example') {
-            steps {
-                echo "${params.Greeting} World!"
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-Handling failure
-Declarative Pipeline supports robust failure handling by default via its post section which allows declaring a number of different "post conditions" such as: always, unstable, success, failure, and changed. The Pipeline Syntax section provides more detail on how to use the various post conditions.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent any
-    stages {
-        stage('Test') {
-            steps {
-                sh 'make check'
-            }
-        }
-    }
-    post {
-        always {
-            junit '**/target/*.xml'
-        }
-        failure {
-            mail to: team@example.com, subject: 'The Pipeline failed :('
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-Scripted Pipeline however relies on Groovy’s built-in try/catch/finally semantics for handling failures during execution of the Pipeline.
-
-In the Test example above, the sh step was modified to never return a non-zero exit code (sh 'make check || true'). This approach, while valid, means the following stages need to check currentBuild.result to know if there has been a test failure or not.
-
-An alternative way of handling this, which preserves the early-exit behavior of failures in Pipeline, while still giving junit the chance to capture test reports, is to use a series of try/finally blocks:
-
-Error-handling steps
-Jenkins Pipelines provide dedicated steps for flexible error handling, allowing you to control how your Pipeline responds to errors and warnings. These steps help you surface errors and warnings clearly in Jenkins, giving you control over whether the Pipeline fails, continues, or simply reports a warning. For more information, refer to:
-
-catchError
-
-error
-
-unstable
-
-warnError
-
-Using multiple agents
-In all the previous examples, only a single agent has been used. This means Jenkins will allocate an executor wherever one is available, regardless of how it is labeled or configured. Not only can this behavior be overridden, but Pipeline allows utilizing multiple agents in the Jenkins environment from within the same Jenkinsfile, which can be helpful for more advanced use-cases such as executing builds/tests across multiple platforms.
-
-In the example below, the "Build" stage will be performed on one agent and the built results will be reused on two subsequent agents, labelled "linux" and "windows" respectively, during the "Test" stage.
-
-Jenkinsfile (Declarative Pipeline)
-pipeline {
-    agent none
-    stages {
-        stage('Build') {
-            agent any
-            steps {
-                checkout scm
-                sh 'make'
-                stash includes: '**/target/*.jar', name: 'app' 
-            }
-        }
-        stage('Test on Linux') {
-            agent { 
-                label 'linux'
-            }
-            steps {
-                unstash 'app' 
-                sh 'make check'
-            }
-            post {
-                always {
-                    junit '**/target/*.xml'
-                }
-            }
-        }
-        stage('Test on Windows') {
-            agent {
-                label 'windows'
-            }
-            steps {
-                unstash 'app'
-                bat 'make check' 
-            }
-            post {
-                always {
-                    junit '**/target/*.xml'
-                }
-            }
-        }
-    }
-}
-Toggle Scripted Pipeline (Advanced)
-The stash step allows capturing files matching an inclusion pattern (**/target/*.jar) for reuse within the same Pipeline. Once the Pipeline has completed its execution, stashed files are deleted from the Jenkins controller.
-The parameter in agent/node allows for any valid Jenkins label expression. Consult the Pipeline Syntax section for more details.
-unstash will retrieve the named "stash" from the Jenkins controller into the Pipeline’s current workspace.
-The bat script allows for executing batch scripts on Windows-based platforms.
-Optional step arguments
-Pipeline follows the Groovy language convention of allowing parentheses to be omitted around method arguments.
-
-Many Pipeline steps also use the named-parameter syntax as a shorthand for creating a Map in Groovy, which uses the syntax [key1: value1, key2: value2]. Making statements like the following functionally equivalent:
-
-git url: 'git://example.com/amazing-project.git', branch: 'master'
-git([url: 'git://example.com/amazing-project.git', branch: 'master'])
-For convenience, when calling steps taking only one parameter (or only one mandatory parameter), the parameter name may be omitted, for example:
-
-sh 'echo hello' /* short form  */
-sh([script: 'echo hello'])  /* long form */
-Advanced Scripted Pipeline
-Scripted Pipeline is a domain-specific language [3] based on Groovy, most Groovy syntax can be used in Scripted Pipeline without modification.
-
-Parallel execution
-The example in the section above runs tests across two different platforms in a linear series. In practice, if the make check execution takes 30 minutes to complete, the "Test" stage would now take 60 minutes to complete!
-
-Fortunately, Pipeline has built-in functionality for executing portions of Scripted Pipeline in parallel, implemented in the aptly named parallel step.
-
-Refactoring the example above to use the parallel step:
-
-Jenkinsfile (Scripted Pipeline)
-stage('Build') {
-    /* .. snip .. */
-}
-
-stage('Test') {
-    parallel linux: {
-        node('linux') {
-            checkout scm
-            try {
-                unstash 'app'
-                sh 'make check'
-            }
-            finally {
-                junit '**/target/*.xml'
-            }
-        }
-    },
-    windows: {
-        node('windows') {
-            /* .. snip .. */
-        }
-    }
-}
-Instead of executing the tests on the "linux" and "windows" labelled nodes in series, they will now execute in parallel assuming the requisite capacity exists in the Jenkins environment.
-
-1. en.wikipedia.org/wiki/Source_control_management
-2. en.wikipedia.org/wiki/Single_Source_of_Truth
-3. en.wikipedia.org/wiki/Domain-specific_language
+Using a Jenkinsfile 
+Table of Contents
+Creating a Jenkinsfile
+Build
+Test
+Deploy
+Working with your Jenkinsfile
+Using environment variables
+Setting environment variables
+Setting environment variables dynamically
+Handling credentials
+For secret text, usernames and passwords, and secret files
+Secret text
+Usernames and passwords
+Secret files
+For other credential types
+Combining credentials in one step
+String interpolation
+Interpolation of sensitive environment variables
+Injection via interpolation
+Handling parameters
+Handling failure
+Error-handling steps
+Using multiple agents
+Optional step arguments
+Advanced Scripted Pipeline
+Parallel execution
+This section builds on the information covered in Getting started with Pipeline and introduces more useful steps, common patterns, and demonstrates some non-trivial Jenkinsfile examples.
+
+Creating a Jenkinsfile, which is checked into source control [1], provides a number of immediate benefits:
+
+Code review/iteration on the Pipeline
+
+Audit trail for the Pipeline
+
+Single source of truth [2] for the Pipeline, which can be viewed and edited by multiple members of the project.
+
+Pipeline supports two syntaxes, Declarative (introduced in Pipeline 2.5) and Scripted Pipeline. Both of which support building continuous delivery pipelines. Both may be used to define a Pipeline in either the web UI or with a Jenkinsfile, though it’s generally considered a best practice to create a Jenkinsfile and check the file into the source control repository.
+
+Creating a Jenkinsfile
+As discussed in the Defining a Pipeline in SCM, a Jenkinsfile is a text file that contains the definition of a Jenkins Pipeline and is checked into source control. Consider the following Pipeline which implements a basic three-stage continuous delivery pipeline.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+
+    stages {
+        stage('Build') {
+            steps {
+                echo 'Building..'
+            }
+        }
+        stage('Test') {
+            steps {
+                echo 'Testing..'
+            }
+        }
+        stage('Deploy') {
+            steps {
+                echo 'Deploying....'
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+Not all Pipelines will have these same three stages, but it is a good starting point to define them for most projects. The sections below will demonstrate the creation and execution of a simple Pipeline in a test installation of Jenkins.
+
+It is assumed that there is already a source control repository set up for the project and a Pipeline has been defined in Jenkins following these instructions.
+
+Using a text editor, ideally one which supports Groovy syntax highlighting, create a new Jenkinsfile in the root directory of the project.
+
+The Declarative Pipeline example above contains the minimum necessary structure to implement a continuous delivery pipeline. The agent directive, which is required, instructs Jenkins to allocate an executor and workspace for the Pipeline. Without an agent directive, not only is the Declarative Pipeline not valid, it would not be capable of doing any work! By default the agent directive ensures that the source repository is checked out and made available for steps in the subsequent stages.
+
+The stages directive and steps directives are also required for a valid Declarative Pipeline as they instruct Jenkins what to execute and in which stage it should be executed.
+
+For more advanced usage with Scripted Pipeline, the example above node is a crucial first step as it allocates an executor and workspace for the Pipeline. In essence, without node, a Pipeline cannot do any work! From within node, the first order of business will be to checkout the source code for this project. Since the Jenkinsfile is being pulled directly from source control, Pipeline provides a quick and easy way to access the right revision of the source code.
+
+Jenkinsfile (Scripted Pipeline)
+node {
+    checkout scm 
+    /* .. snip .. */
+}
+The checkout step will checkout code from source control; scm is a special variable which instructs the checkout step to clone the specific revision which triggered this Pipeline run.
+Build
+For many projects the beginning of "work" in the Pipeline would be the "build" stage. Typically this stage of the Pipeline will be where source code is assembled, compiled, or packaged. The Jenkinsfile is not a replacement for an existing build tool such as GNU/Make, Maven, Gradle, or others, but rather can be viewed as a glue layer to bind the multiple phases of a project’s development lifecycle (build, test, deploy) together.
+
+Jenkins has a number of plugins for invoking practically any build tool in general use, but this example will simply invoke make from a shell step (sh). The sh step assumes the system is Unix/Linux-based, for Windows-based systems the bat could be used instead.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+
+    stages {
+        stage('Build') {
+            steps {
+                sh 'make' 
+                archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true 
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+The sh step invokes the make command and will only continue if a zero exit code is returned by the command. Any non-zero exit code will fail the Pipeline.
+archiveArtifacts captures the files built matching the include pattern (**/target/*.jar) and saves them to the Jenkins controller for later retrieval.
+Archiving artifacts is not a substitute for using external artifact repositories such as Artifactory or Nexus and should be considered only for basic reporting and file archival.
+
+Test
+Running automated tests is a crucial component of any successful continuous delivery process. As such, Jenkins has a number of test recording, reporting, and visualization facilities provided by a number of plugins. At a fundamental level, when there are test failures, it is useful to have Jenkins record the failures for reporting and visualization in the web UI. The example below uses the junit step, provided by the JUnit plugin.
+
+In the example below, if tests fail, the Pipeline is marked "unstable", as denoted by a yellow ball in the web UI. Based on the recorded test reports, Jenkins can also provide historical trend analysis and visualization.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+
+    stages {
+        stage('Test') {
+            steps {
+                /* `make check` returns non-zero on test failures,
+                * using `true` to allow the Pipeline to continue nonetheless
+                */
+                sh 'make check || true' 
+                junit '**/target/*.xml' 
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+Using an inline shell conditional (sh 'make check || true') ensures that the sh step always sees a zero exit code, giving the junit step the opportunity to capture and process the test reports. Alternative approaches to this are covered in more detail in the Handling failure section below.
+junit captures and associates the JUnit XML files matching the inclusion pattern (**/target/*.xml).
+Deploy
+Deployment can imply a variety of steps, depending on the project or organization requirements, and may be anything from publishing built artifacts to an Artifactory server, to pushing code to a production system.
+
+At this stage of the example Pipeline, both the "Build" and "Test" stages have successfully executed. In essence, the "Deploy" stage will only execute assuming previous stages completed successfully, otherwise the Pipeline would have exited early.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+
+    stages {
+        stage('Deploy') {
+            when {
+              expression {
+                currentBuild.result == null || currentBuild.result == 'SUCCESS' 
+              }
+            }
+            steps {
+                sh 'make publish'
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+Accessing the currentBuild.result variable allows the Pipeline to determine if there were any test failures. In which case, the value would be UNSTABLE.
+Assuming everything has executed successfully in the example Jenkins Pipeline, each successful Pipeline run will have associated build artifacts archived, test results reported upon and the full console output all in Jenkins.
+
+A Scripted Pipeline can include conditional tests (shown above), loops, try/catch/finally blocks, and even functions. The next section will cover this advanced Scripted Pipeline syntax in more detail.
+
+Working with your Jenkinsfile
+The following sections provide details about handling:
+
+specific Pipeline syntax in your Jenkinsfile and
+
+features and functionality of Pipeline syntax which are essential in building your application or Pipeline project.
+
+Using environment variables
+Jenkins Pipeline exposes environment variables via the global variable env, which is available from anywhere within a Jenkinsfile. The full list of environment variables accessible from within Jenkins Pipeline is documented at ${YOUR_JENKINS_URL}/pipeline-syntax/globals#env and includes:
+
+BUILD_ID
+The current build ID, identical to BUILD_NUMBER for builds created in Jenkins versions 1.597+.
+
+BUILD_NUMBER
+The current build number, such as "153".
+
+BUILD_TAG
+String of jenkins-${JOB_NAME}-${BUILD_NUMBER}. Convenient to put into a resource file, a jar file, etc for easier identification.
+
+BUILD_URL
+The URL where the results of this build can be found (for example, http://buildserver/jenkins/job/MyJobName/17/).
+
+EXECUTOR_NUMBER
+The unique number that identifies the current executor (among executors of the same machine) performing this build. This is the number you see in the "build executor status", except that the number starts from 0, not 1.
+
+JAVA_HOME
+If your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to include the bin subdirectory of JAVA_HOME.
+
+JENKINS_URL
+Full URL of Jenkins, such as https://example.com:port/jenkins/ (NOTE: only available if Jenkins URL set in "System Configuration").
+
+JOB_NAME
+Name of the project of this build, such as "foo" or "foo/bar".
+
+NODE_NAME
+The name of the node the current build is running on. Set to 'master' for the Jenkins controller.
+
+WORKSPACE
+The absolute path of the workspace.
+
+Referencing or using these environment variables can be accomplished like accessing any key in a Groovy Map, for example:
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+    stages {
+        stage('Example') {
+            steps {
+                echo "Running ${env.BUILD_ID} on ${env.JENKINS_URL}"
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+Setting environment variables
+Setting an environment variable within a Jenkins Pipeline is accomplished differently depending on whether Declarative or Scripted Pipeline is used.
+
+Declarative Pipeline supports an environment directive, whereas users of Scripted Pipeline must use the withEnv step.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+    environment { 
+        CC = 'clang'
+    }
+    stages {
+        stage('Example') {
+            environment { 
+                DEBUG_FLAGS = '-g'
+            }
+            steps {
+                sh 'printenv'
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+An environment directive used in the top-level pipeline block will apply to all steps within the Pipeline.
+An environment directive defined within a stage will only apply the given environment variables to steps within the stage.
+Setting environment variables dynamically
+Environment variables can be set at run time and can be used by shell scripts (sh), Windows batch scripts (bat) and PowerShell scripts (powershell). Each script can either returnStatus or returnStdout. More information on scripts.
+
+Below is an example in a declarative pipeline using sh (shell) with both returnStatus and returnStdout.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any 
+    environment {
+        // Using returnStdout
+        CC = """${sh(
+                returnStdout: true,
+                script: 'echo "clang"'
+            )}""" 
+        // Using returnStatus
+        EXIT_STATUS = """${sh(
+                returnStatus: true,
+                script: 'exit 1'
+            )}"""
+    }
+    stages {
+        stage('Example') {
+            environment {
+                DEBUG_FLAGS = '-g'
+            }
+            steps {
+                sh 'printenv'
+            }
+        }
+    }
+}
+An agent must be set at the top level of the pipeline. This will fail if agent is set as agent none.
+When using returnStdout a trailing whitespace will be appended to the returned string. Use .trim() to remove this.
+Handling credentials
+Credentials configured in Jenkins can be handled in Pipelines for immediate use. Read more about using credentials in Jenkins on the Using credentials page.
+
+The correct way to handle credentials in Jenkins
+
+For secret text, usernames and passwords, and secret files
+Jenkins' declarative Pipeline syntax has the credentials() helper method (used within the environment directive) which supports secret text, username and password, as well as secret file credentials. If you want to handle other types of credentials, refer to the For other credential types section.
+
+Secret text
+The following Pipeline code shows an example of how to create a Pipeline using environment variables for secret text credentials.
+
+In this example, two secret text credentials are assigned to separate environment variables to access Amazon Web Services (AWS). These credentials would have been configured in Jenkins with their respective credential IDs jenkins-aws-secret-key-id and jenkins-aws-secret-access-key.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent {
+        // Define agent details here
+    }
+    environment {
+        AWS_ACCESS_KEY_ID     = credentials('jenkins-aws-secret-key-id')
+        AWS_SECRET_ACCESS_KEY = credentials('jenkins-aws-secret-access-key')
+    }
+    stages {
+        stage('Example stage 1') {
+            steps {
+                // 
+            }
+        }
+        stage('Example stage 2') {
+            steps {
+                // 
+            }
+        }
+    }
+}
+You can reference the two credential environment variables (defined in this Pipeline’s environment directive), within this stage’s steps using the syntax $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY. For example, here you can authenticate to AWS using the secret text credentials assigned to these credential variables. To maintain the security and anonymity of these credentials, if the job displays the value of these credential variables from within the Pipeline (such as echo $AWS_SECRET_ACCESS_KEY), Jenkins only returns the value “****” to reduce the risk of secret information being disclosed to the console output and any logs. Any sensitive information in credential IDs themselves (such as usernames) are also returned as “****” in the Pipeline run’s output. This only reduces the risk of accidental exposure. It does not prevent a malicious user from capturing the credential value by other means. A Pipeline that uses credentials can also disclose those credentials. Don’t allow untrusted Pipeline jobs to use trusted credentials.
+In this Pipeline example, the credentials assigned to the two AWS_…​ environment variables are scoped globally for the entire Pipeline, so these credential variables could also be used in this stage’s steps. If, however, the environment directive in this Pipeline were moved to a specific stage (as is the case in the Usernames and passwords Pipeline example below), then these AWS_…​ environment variables would only be scoped to the steps in that stage.
+Storing static AWS keys in Jenkins credentials is not very secure. If you can run Jenkins itself in AWS (at least the agent), it is preferable to use IAM roles for a computer or EKS service account. It is also possible to use web identity federation.
+Usernames and passwords
+The following Pipeline code snippets show an example of how to create a Pipeline using environment variables for username and password credentials.
+
+In this example, username and password credentials are assigned to environment variables to access a Bitbucket repository in a common account or team for your organization; these credentials would have been configured in Jenkins with the credential ID jenkins-bitbucket-common-creds.
+
+When setting the credential environment variable in the environment directive:
+
+environment {
+    BITBUCKET_COMMON_CREDS = credentials('jenkins-bitbucket-common-creds')
+}
+this actually sets the following three environment variables:
+
+BITBUCKET_COMMON_CREDS - contains a username and a password separated by a colon in the format username:password.
+
+BITBUCKET_COMMON_CREDS_USR - an additional variable containing the username component only.
+
+BITBUCKET_COMMON_CREDS_PSW - an additional variable containing the password component only.
+
+By convention, variable names for environment variables are typically specified in capital case, with individual words separated by underscores You can, however, specify any legitimate variable name using lower case characters. Bear in mind that the additional environment variables created by the credentials() method (above) will always be appended with _USR and _PSW (i.e. in the format of an underscore followed by three capital letters).
+
+The following code snippet shows the example Pipeline in its entirety:
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent {
+        // Define agent details here
+    }
+    stages {
+        stage('Example stage 1') {
+            environment {
+                BITBUCKET_COMMON_CREDS = credentials('jenkins-bitbucket-common-creds')
+            }
+            steps {
+                // 
+            }
+        }
+        stage('Example stage 2') {
+            steps {
+                // 
+            }
+        }
+    }
+}
+The following credential environment variables (defined in this Pipeline’s environment directive) are available within this stage’s steps and can be referenced using the syntax:
+$BITBUCKET_COMMON_CREDS
+
+$BITBUCKET_COMMON_CREDS_USR
+
+$BITBUCKET_COMMON_CREDS_PSW
+
+For example, here you can authenticate to Bitbucket with the username and password assigned to these credential variables. To maintain the security and anonymity of these credentials, if the job displays the value of these credential variables from within the Pipeline the same behavior described in the Secret text example above applies to these username and password credential variable types too. This only reduces the risk of accidental exposure. It does not prevent a malicious user from capturing the credential value by other means. A Pipeline that uses credentials can also disclose those credentials. Don’t allow untrusted Pipeline jobs to use trusted credentials.
+
+In this Pipeline example, the credentials assigned to the three BITBUCKET_COMMON_CREDS…​ environment variables are scoped only to Example stage 1, so these credential variables are not available for use in this Example stage 2 stage’s steps. If, however, the environment directive in this Pipeline were moved immediately within the pipeline block (as is the case in the Secret text Pipeline example above), then these BITBUCKET_COMMON_CREDS…​ environment variables would be scoped globally and could be used in any stage’s steps.
+Secret files
+A secret file is a credential which is stored in a file and uploaded to Jenkins. Secret files are used for credentials that are:
+
+too unwieldy to enter directly into Jenkins, and/or
+
+in binary format, such as a GPG file.
+
+In this example, we use a Kubernetes config file that has been configured as a secret file credential named my-kubeconfig.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent {
+        // Define agent details here
+    }
+    environment {
+        // The MY_KUBECONFIG environment variable will be assigned the value of a temporary file.
+        // For example:
+        //   /home/user/.jenkins/workspace/cred_test@tmp/secretFiles/546a5cf3-9b56-4165-a0fd-19e2afe6b31f/kubeconfig.txt
+        MY_KUBECONFIG = credentials('my-kubeconfig')
+    }
+    stages {
+        stage('Example stage 1') {
+            steps {
+                sh("kubectl --kubeconfig $MY_KUBECONFIG get pods")
+            }
+        }
+    }
+}
+For other credential types
+If you need to set credentials in a Pipeline for anything other than secret text, usernames and passwords, or secret files like SSH keys or certificates, use Jenkins' Snippet Generator feature, which you can access through Jenkins' classic UI.
+
+To access the Snippet Generator for your Pipeline project/item:
+
+From the Jenkins Dashboard, select the name of your Pipeline project/item.
+
+In the left navigation pane, select Pipeline Syntax and ensure that the Snippet Generator option is available at the top of the navigation pane.
+
+From the Sample Step field, choose withCredentials: Bind credentials to variables.
+
+Under Bindings, click Add and choose from the dropdown:
+
+SSH User Private Key - to handle SSH public/private key pair credentials, from which you can specify:
+
+Key File Variable - the name of the environment variable that will be bound to these credentials. Jenkins actually assigns this temporary variable to the secure location of the private key file required in the SSH public/private key pair authentication process.
+
+Passphrase Variable ( Optional ) - the name of the environment variable that will be bound to the passphrase associated with the SSH public/private key pair.
+
+Username Variable ( Optional ) - the name of the environment variable that will be bound to username associated with the SSH public/private key pair.
+
+Credentials - choose the SSH public/private key credentials stored in Jenkins. The value of this field is the credential ID, which Jenkins writes out to the generated snippet.
+
+Certificate - to handle PKCS#12 certificates, from which you can specify:
+
+Keystore Variable - the name of the environment variable that will be bound to these credentials. Jenkins actually assigns this temporary variable to the secure location of the certificate’s keystore required in the certificate authentication process.
+
+Password Variable ( Optional ) - the name of the environment variable that will be bound to the password associated with the certificate.
+
+Alias Variable ( Optional ) - the name of the environment variable that will be bound to the unique alias associated with the certificate.
+
+Credentials - choose the certificate credentials stored in Jenkins. The value of this field is the credential ID, which Jenkins writes out to the generated snippet.
+
+Docker client certificate - to handle Docker Host Certificate Authentication.
+
+Click Generate Pipeline Script and Jenkins generates a withCredentials(…​) { …​ } Pipeline step snippet for the credentials you specified, which you can then copy and paste into your Declarative or Scripted Pipeline code.
+Notes:
+
+The Credentials fields (above) show the names of credentials configured in Jenkins. However, these values are converted to credential IDs after clicking Generate Pipeline Script.
+
+To combine more than one credential in a single withCredentials(…​) { …​ } Pipeline step, see Combining credentials in one step (below) for details.
+
+SSH User Private Key example
+
+withCredentials(bindings: [sshUserPrivateKey(credentialsId: 'jenkins-ssh-key-for-abc', \
+                                             keyFileVariable: 'SSH_KEY_FOR_ABC', \
+                                             passphraseVariable: '', \
+                                             usernameVariable: '')]) {
+  // some block
+}
+The optional passphraseVariable and usernameVariable definitions can be deleted in your final Pipeline code.
+
+Certificate example
+
+withCredentials(bindings: [certificate(aliasVariable: '', \
+                                       credentialsId: 'jenkins-certificate-for-xyz', \
+                                       keystoreVariable: 'CERTIFICATE_FOR_XYZ', \
+                                       passwordVariable: 'XYZ-CERTIFICATE-PASSWORD')]) {
+  // some block
+}
+The optional aliasVariable and passwordVariable variable definitions can be deleted in your final Pipeline code.
+
+The following code snippet shows an example Pipeline in its entirety, which implements the SSH User Private Key and Certificate snippets above:
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent {
+        // define agent details
+    }
+    stages {
+        stage('Example stage 1') {
+            steps {
+                withCredentials(bindings: [sshUserPrivateKey(credentialsId: 'jenkins-ssh-key-for-abc', \
+                                                             keyFileVariable: 'SSH_KEY_FOR_ABC')]) {
+                  // 
+                }
+                withCredentials(bindings: [certificate(credentialsId: 'jenkins-certificate-for-xyz', \
+                                                       keystoreVariable: 'CERTIFICATE_FOR_XYZ', \
+                                                       passwordVariable: 'XYZ-CERTIFICATE-PASSWORD')]) {
+                  // 
+                }
+            }
+        }
+        stage('Example stage 2') {
+            steps {
+                // 
+            }
+        }
+    }
+}
+Within this step, you can reference the credential environment variable with the syntax $SSH_KEY_FOR_ABC. For example, here you can authenticate to the ABC application with its configured SSH public/private key pair credentials, whose SSH User Private Key file is assigned to $SSH_KEY_FOR_ABC.
+Within this step, you can reference the credential environment variable with the syntax $CERTIFICATE_FOR_XYZ and $XYZ-CERTIFICATE-PASSWORD. For example, here you can authenticate to the XYZ application with its configured certificate credentials, whose Certificate's keystore file and password are assigned to the variables $CERTIFICATE_FOR_XYZ and $XYZ-CERTIFICATE-PASSWORD, respectively.
+In this Pipeline example, the credentials assigned to the $SSH_KEY_FOR_ABC, $CERTIFICATE_FOR_XYZ and $XYZ-CERTIFICATE-PASSWORD environment variables are scoped only within their respective withCredentials( …​ ) { …​ } steps, so these credential variables are not available for use in this Example stage 2 stage’s steps.
+To maintain the security and anonymity of these credentials, if you attempt to retrieve the value of these credential variables from within these withCredentials( …​ ) { …​ } steps, the same behavior described in the Secret text example (above) applies to these SSH public/private key pair credential and certificate variable types too. This only reduces the risk of accidental exposure. It does not prevent a malicious user from capturing the credential value by other means. A Pipeline that uses credentials can also disclose those credentials. Don’t allow untrusted Pipeline jobs to use trusted credentials.
+
+When using the Sample Step field’s withCredentials: Bind credentials to variables option in the Snippet Generator, only credentials which your current Pipeline project/item has access to can be selected from any Credentials field’s list. While you can manually write a withCredentials( …​ ) { …​ } step for your Pipeline (like the examples above), using the Snippet Generator is recommended to avoid specifying credentials that are out of scope for this Pipeline project/item, which when run, will make the step fail.
+
+You can also use the Snippet Generator to generate withCredentials( …​ ) { …​ } steps to handle secret text, usernames and passwords and secret files. However, if you only need to handle these types of credentials, it is recommended you use the relevant procedure described in the section above for improved Pipeline code readability.
+
+The use of single-quotes instead of double-quotes to define the script (the implicit parameter to sh) in Groovy above. The single-quotes will cause the secret to be expanded by the shell as an environment variable. The double-quotes are potentially less secure as the secret is interpolated by Groovy, and so typical operating system process listings will accidentally disclose it :
+
+node {
+  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
+    sh /* WRONG! */ """
+      set +x
+      curl -H 'Token: $TOKEN' https://some.api/
+    """
+    sh /* CORRECT */ '''
+      set +x
+      curl -H 'Token: $TOKEN' https://some.api/
+    '''
+  }
+}
+Combining credentials in one step
+Using the Snippet Generator, you can make multiple credentials available within a single withCredentials( …​ ) { …​ } step by doing the following:
+
+From the Jenkins Dashboard, select the name of your Pipeline project/item.
+
+In the left navigation pane, select Pipeline Syntax and ensure that the Snippet Generator option is available at the top of the navigation pane.
+
+From the Sample Step field, choose withCredentials: Bind credentials to variables.
+
+Click Add under Bindings.
+
+Choose the credential type to add to the withCredentials( …​ ) { …​ } step from the dropdown list.
+
+Specify the credential Bindings details. Read more above these in the procedure under For other credential types (above).
+
+Repeat from "Click Add …​" (above) for each (set of) credential/s to add to the withCredentials( …​ ) { …​ } step.
+
+Select Generate Pipeline Script to generate the final withCredentials( …​ ) { …​ } step snippet.
+
+String interpolation
+Jenkins Pipeline uses rules identical to Groovy for string interpolation. Groovy’s String interpolation support can be confusing to many newcomers to the language. While Groovy supports declaring a string with either single quotes, or double quotes, for example:
+
+def singlyQuoted = 'Hello'
+def doublyQuoted = "World"
+Only the latter string will support the dollar-sign ($) based string interpolation, for example:
+
+def username = 'Jenkins'
+echo 'Hello Mr. ${username}'
+echo "I said, Hello Mr. ${username}"
+Would result in:
+
+Hello Mr. ${username}
+I said, Hello Mr. Jenkins
+Understanding how to use string interpolation is vital for using some of Pipeline’s more advanced features.
+
+Interpolation of sensitive environment variables
+Groovy string interpolation should never be used with credentials.
+
+Groovy GStrings (double-quoted or triple-double-quoted strings) expand ${TOKEN} before the command is sent to the agent. When that happens, the secret is copied into the process arguments (visible via tooling such as ps) and any shell metacharacters inside the secret or user-controlled value are executed immediately. Always send a literal command string to sh, bat, powershell, or pwsh and let the shell read secrets from its environment, which withCredentials or the environment block have already populated.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+    environment {
+        API_TOKEN = credentials('example-token-id')
+    }
+    stages {
+        stage('Example') {
+            steps {
+                /* WRONG */
+                    sh "curl -H 'Authorization: Bearer ${API_TOKEN}' https://example.com"
+                """
+            }
+        }
+    }
+}
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+    environment {
+        API_TOKEN = credentials('example-token-id')
+    }
+    stages {
+        stage('Example') {
+            steps {
+                /* CORRECT */
+                sh 'curl -H "Authorization: Bearer ${API_TOKEN}" https://example.com'
+            }
+        }
+    }
+}
+Any Groovy construct that avoids interpolation (for example, sh(script: 'curl …​ $API_TOKEN', label: 'call API')) is safe; the key is keeping secrets out of GStrings so only the shell expands them.
+
+Injection via interpolation
+Groovy string interpolation can inject rogue commands into command interpreters via special characters.
+
+Another note of caution. Using Groovy string interpolation for user-controlled variables with steps that pass their arguments to command interpreters such as the sh, bat, powershell, or pwsh steps can result in problems analogous to SQL injection. This occurs when a user-controlled variable (generally an environment variable, usually a parameter passed to the build) that contains special characters (e.g. / \ $ & % ^ > < | ;) is passed to the sh, bat, powershell, or pwsh steps using Groovy interpolation. For a simple example:
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+  agent any
+  parameters {
+    string(name: 'STATEMENT', defaultValue: 'hello; ls /', description: 'What should I say?')
+  }
+  stages {
+    stage('Example') {
+      steps {
+        /* WRONG! */
+        sh("echo ${STATEMENT}")
+      }
+    }
+  }
+}
+In this example, the argument to the sh step is evaluated by Groovy, and STATEMENT is interpolated directly into the argument as if sh('echo hello; ls /') has been written in the Pipeline. When this is processed on the agent, rather than echoing the value hello; ls /, it will echo hello then proceed to list the entire root directory of the agent. Any user able to control a variable interpolated by such a step would be able to make the sh step run arbitrary code on the agent. To avoid this problem, make sure arguments to steps such as sh or bat that reference parameters or other user-controlled environment variables use single quotes to avoid Groovy interpolation.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+  agent any
+  parameters {
+    string(name: 'STATEMENT', defaultValue: 'hello; ls /', description: 'What should I say?')
+  }
+  stages {
+    stage('Example') {
+      steps {
+        /* CORRECT */
+        sh('echo ${STATEMENT}')
+      }
+    }
+  }
+}
+Credential mangling is another issue that can occur when credentials that contain special characters are passed to a step using Groovy interpolation. When the credential value is mangled, it is no longer valid and will no longer be masked in the console log.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+  agent any
+  environment {
+    EXAMPLE_KEY = credentials('example-credentials-id') // Secret value is 'sec%ret'
+  }
+  stages {
+    stage('Example') {
+      steps {
+          /* WRONG! */
+          bat "echo ${EXAMPLE_KEY}"
+      }
+    }
+  }
+}
+Here, the bat step receives echo sec%ret and the Windows batch shell will simply drop the % and print out the value secret. Because there is a single character difference, the value secret will not be masked. Though the value is not the same as the actual credential, this is still a significant exposure of sensitive information. Again, single-quotes avoids this issue.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+  agent any
+  environment {
+    EXAMPLE_KEY = credentials('example-credentials-id') // Secret value is 'sec%ret'
+  }
+  stages {
+    stage('Example') {
+      steps {
+          /* CORRECT */
+          bat 'echo %EXAMPLE_KEY%'
+      }
+    }
+  }
+}
+Handling parameters
+Declarative Pipeline supports parameters out-of-the-box, allowing the Pipeline to accept user-specified parameters at runtime via the parameters directive. Configuring parameters with Scripted Pipeline is done with the properties step, which can be found in the Snippet Generator.
+
+If you configured your pipeline to accept parameters using the Build with Parameters option, those parameters are accessible as members of the params variable.
+
+Assuming that a String parameter named "Greeting" has been configured in the Jenkinsfile, it can access that parameter via ${params.Greeting}:
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+    parameters {
+        string(name: 'Greeting', defaultValue: 'Hello', description: 'How should I greet the world?')
+    }
+    stages {
+        stage('Example') {
+            steps {
+                echo "${params.Greeting} World!"
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+Handling failure
+Declarative Pipeline supports robust failure handling by default via its post section which allows declaring a number of different "post conditions" such as: always, unstable, success, failure, and changed. The Pipeline Syntax section provides more detail on how to use the various post conditions.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent any
+    stages {
+        stage('Test') {
+            steps {
+                sh 'make check'
+            }
+        }
+    }
+    post {
+        always {
+            junit '**/target/*.xml'
+        }
+        failure {
+            mail to: team@example.com, subject: 'The Pipeline failed :('
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+Scripted Pipeline however relies on Groovy’s built-in try/catch/finally semantics for handling failures during execution of the Pipeline.
+
+In the Test example above, the sh step was modified to never return a non-zero exit code (sh 'make check || true'). This approach, while valid, means the following stages need to check currentBuild.result to know if there has been a test failure or not.
+
+An alternative way of handling this, which preserves the early-exit behavior of failures in Pipeline, while still giving junit the chance to capture test reports, is to use a series of try/finally blocks:
+
+Error-handling steps
+Jenkins Pipelines provide dedicated steps for flexible error handling, allowing you to control how your Pipeline responds to errors and warnings. These steps help you surface errors and warnings clearly in Jenkins, giving you control over whether the Pipeline fails, continues, or simply reports a warning. For more information, refer to:
+
+catchError
+
+error
+
+unstable
+
+warnError
+
+Using multiple agents
+In all the previous examples, only a single agent has been used. This means Jenkins will allocate an executor wherever one is available, regardless of how it is labeled or configured. Not only can this behavior be overridden, but Pipeline allows utilizing multiple agents in the Jenkins environment from within the same Jenkinsfile, which can be helpful for more advanced use-cases such as executing builds/tests across multiple platforms.
+
+In the example below, the "Build" stage will be performed on one agent and the built results will be reused on two subsequent agents, labelled "linux" and "windows" respectively, during the "Test" stage.
+
+Jenkinsfile (Declarative Pipeline)
+pipeline {
+    agent none
+    stages {
+        stage('Build') {
+            agent any
+            steps {
+                checkout scm
+                sh 'make'
+                stash includes: '**/target/*.jar', name: 'app' 
+            }
+        }
+        stage('Test on Linux') {
+            agent { 
+                label 'linux'
+            }
+            steps {
+                unstash 'app' 
+                sh 'make check'
+            }
+            post {
+                always {
+                    junit '**/target/*.xml'
+                }
+            }
+        }
+        stage('Test on Windows') {
+            agent {
+                label 'windows'
+            }
+            steps {
+                unstash 'app'
+                bat 'make check' 
+            }
+            post {
+                always {
+                    junit '**/target/*.xml'
+                }
+            }
+        }
+    }
+}
+Toggle Scripted Pipeline (Advanced)
+The stash step allows capturing files matching an inclusion pattern (**/target/*.jar) for reuse within the same Pipeline. Once the Pipeline has completed its execution, stashed files are deleted from the Jenkins controller.
+The parameter in agent/node allows for any valid Jenkins label expression. Consult the Pipeline Syntax section for more details.
+unstash will retrieve the named "stash" from the Jenkins controller into the Pipeline’s current workspace.
+The bat script allows for executing batch scripts on Windows-based platforms.
+Optional step arguments
+Pipeline follows the Groovy language convention of allowing parentheses to be omitted around method arguments.
+
+Many Pipeline steps also use the named-parameter syntax as a shorthand for creating a Map in Groovy, which uses the syntax [key1: value1, key2: value2]. Making statements like the following functionally equivalent:
+
+git url: 'git://example.com/amazing-project.git', branch: 'master'
+git([url: 'git://example.com/amazing-project.git', branch: 'master'])
+For convenience, when calling steps taking only one parameter (or only one mandatory parameter), the parameter name may be omitted, for example:
+
+sh 'echo hello' /* short form  */
+sh([script: 'echo hello'])  /* long form */
+Advanced Scripted Pipeline
+Scripted Pipeline is a domain-specific language [3] based on Groovy, most Groovy syntax can be used in Scripted Pipeline without modification.
+
+Parallel execution
+The example in the section above runs tests across two different platforms in a linear series. In practice, if the make check execution takes 30 minutes to complete, the "Test" stage would now take 60 minutes to complete!
+
+Fortunately, Pipeline has built-in functionality for executing portions of Scripted Pipeline in parallel, implemented in the aptly named parallel step.
+
+Refactoring the example above to use the parallel step:
+
+Jenkinsfile (Scripted Pipeline)
+stage('Build') {
+    /* .. snip .. */
+}
+
+stage('Test') {
+    parallel linux: {
+        node('linux') {
+            checkout scm
+            try {
+                unstash 'app'
+                sh 'make check'
+            }
+            finally {
+                junit '**/target/*.xml'
+            }
+        }
+    },
+    windows: {
+        node('windows') {
+            /* .. snip .. */
+        }
+    }
+}
+Instead of executing the tests on the "linux" and "windows" labelled nodes in series, they will now execute in parallel assuming the requisite capacity exists in the Jenkins environment.
+
+1. en.wikipedia.org/wiki/Source_control_management
+2. en.wikipedia.org/wiki/Single_Source_of_Truth
+3. en.wikipedia.org/wiki/Domain-specific_language

data/errors/error_01.txt

@@ -1,29 +1,29 @@
-Started by user Arvind Nandigam
-org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
-WorkflowScript: 10: expecting '}', found '' @ line 10, column 1.
-1 error
-
-	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
-	at org.codehaus.groovy.control.ErrorCollector.addFatalError(ErrorCollector.java:149)
-	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:119)
-	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:131)
-	at org.codehaus.groovy.control.SourceUnit.addError(SourceUnit.java:349)
-	at org.codehaus.groovy.antlr.AntlrParserPlugin.transformCSTIntoAST(AntlrParserPlugin.java:225)
-	at org.codehaus.groovy.antlr.AntlrParserPlugin.parseCST(AntlrParserPlugin.java:191)
-	at org.codehaus.groovy.control.SourceUnit.parse(SourceUnit.java:233)
-	at org.codehaus.groovy.control.CompilationUnit$1.call(CompilationUnit.java:189)
-	at org.codehaus.groovy.control.CompilationUnit.applyToSourceUnits(CompilationUnit.java:966)
-	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:626)
-	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
-	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
-	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
-	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
-	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
-	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
-	at hudson.model.ResourceController.execute(ResourceController.java:101)
-	at hudson.model.Executor.run(Executor.java:460)
-Finished: FAILURE
+Started by user Arvind Nandigam
+org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
+WorkflowScript: 10: expecting '}', found '' @ line 10, column 1.
+1 error
+
+	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
+	at org.codehaus.groovy.control.ErrorCollector.addFatalError(ErrorCollector.java:149)
+	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:119)
+	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:131)
+	at org.codehaus.groovy.control.SourceUnit.addError(SourceUnit.java:349)
+	at org.codehaus.groovy.antlr.AntlrParserPlugin.transformCSTIntoAST(AntlrParserPlugin.java:225)
+	at org.codehaus.groovy.antlr.AntlrParserPlugin.parseCST(AntlrParserPlugin.java:191)
+	at org.codehaus.groovy.control.SourceUnit.parse(SourceUnit.java:233)
+	at org.codehaus.groovy.control.CompilationUnit$1.call(CompilationUnit.java:189)
+	at org.codehaus.groovy.control.CompilationUnit.applyToSourceUnits(CompilationUnit.java:966)
+	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:626)
+	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
+	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
+	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
+	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
+	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
+	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
+	at hudson.model.ResourceController.execute(ResourceController.java:101)
+	at hudson.model.Executor.run(Executor.java:460)
+Finished: FAILURE

data/errors/error_02.txt

@@ -1,29 +1,29 @@
-Started by user Arvind Nandigam
-org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
-WorkflowScript: 9: expecting '}', found '' @ line 9, column 1.
-1 error
-
-	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
-	at org.codehaus.groovy.control.ErrorCollector.addFatalError(ErrorCollector.java:149)
-	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:119)
-	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:131)
-	at org.codehaus.groovy.control.SourceUnit.addError(SourceUnit.java:349)
-	at org.codehaus.groovy.antlr.AntlrParserPlugin.transformCSTIntoAST(AntlrParserPlugin.java:225)
-	at org.codehaus.groovy.antlr.AntlrParserPlugin.parseCST(AntlrParserPlugin.java:191)
-	at org.codehaus.groovy.control.SourceUnit.parse(SourceUnit.java:233)
-	at org.codehaus.groovy.control.CompilationUnit$1.call(CompilationUnit.java:189)
-	at org.codehaus.groovy.control.CompilationUnit.applyToSourceUnits(CompilationUnit.java:966)
-	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:626)
-	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
-	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
-	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
-	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
-	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
-	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
-	at hudson.model.ResourceController.execute(ResourceController.java:101)
-	at hudson.model.Executor.run(Executor.java:460)
-Finished: FAILURE
+Started by user Arvind Nandigam
+org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
+WorkflowScript: 9: expecting '}', found '' @ line 9, column 1.
+1 error
+
+	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
+	at org.codehaus.groovy.control.ErrorCollector.addFatalError(ErrorCollector.java:149)
+	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:119)
+	at org.codehaus.groovy.control.ErrorCollector.addError(ErrorCollector.java:131)
+	at org.codehaus.groovy.control.SourceUnit.addError(SourceUnit.java:349)
+	at org.codehaus.groovy.antlr.AntlrParserPlugin.transformCSTIntoAST(AntlrParserPlugin.java:225)
+	at org.codehaus.groovy.antlr.AntlrParserPlugin.parseCST(AntlrParserPlugin.java:191)
+	at org.codehaus.groovy.control.SourceUnit.parse(SourceUnit.java:233)
+	at org.codehaus.groovy.control.CompilationUnit$1.call(CompilationUnit.java:189)
+	at org.codehaus.groovy.control.CompilationUnit.applyToSourceUnits(CompilationUnit.java:966)
+	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:626)
+	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
+	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
+	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
+	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
+	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
+	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
+	at hudson.model.ResourceController.execute(ResourceController.java:101)
+	at hudson.model.Executor.run(Executor.java:460)
+Finished: FAILURE

data/errors/error_03.txt

@@ -1,11 +1,11 @@
-Started by user Arvind Nandigam
-[Pipeline] Start of Pipeline
-[Pipeline] stage
-[Pipeline] { (Build)
-[Pipeline] sh
-[Pipeline] error
-[Pipeline] }
-[Pipeline] // stage
-[Pipeline] End of Pipeline
-ERROR: Attempted to execute a step that requires a node context while ‘agent none’ was specified. Be sure to specify your own ‘node { ... }’ blocks when using ‘agent none’.
+Started by user Arvind Nandigam
+[Pipeline] Start of Pipeline
+[Pipeline] stage
+[Pipeline] { (Build)
+[Pipeline] sh
+[Pipeline] error
+[Pipeline] }
+[Pipeline] // stage
+[Pipeline] End of Pipeline
+ERROR: Attempted to execute a step that requires a node context while ‘agent none’ was specified. Be sure to specify your own ‘node { ... }’ blocks when using ‘agent none’.
 Finished: FAILURE

data/errors/error_04.txt

@@ -1,48 +1,48 @@
-Started by user Arvind Nandigam
-[Pipeline] Start of Pipeline
-[Pipeline] node
-Running on Jenkins in /var/jenkins_home/workspace/error_04
-[Pipeline] {
-[Pipeline] stage
-[Pipeline] { (Checkout)
-[Pipeline] git
-The recommended git tool is: NONE
-No credentials specified
-Cloning the remote Git repository
-Cloning repository https://github.com/example/repo.git
- > git init /var/jenkins_home/workspace/error_04 # timeout=10
-Fetching upstream changes from https://github.com/example/repo.git
- > git --version # timeout=10
- > git --version # 'git version 2.47.3'
- > git fetch --tags --force --progress -- https://github.com/example/repo.git +refs/heads/*:refs/remotes/origin/* # timeout=10
-ERROR: Error cloning remote repo 'origin'
-hudson.plugins.git.GitException: Command "git fetch --tags --force --progress -- https://github.com/example/repo.git +refs/heads/*:refs/remotes/origin/*" returned status code 128:
-stdout: 
-stderr: remote: Invalid username or token. Password authentication is not supported for Git operations.
-fatal: Authentication failed for 'https://github.com/example/repo.git/'
-
-	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(CliGitAPIImpl.java:2848)
-	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandWithCredentials(CliGitAPIImpl.java:2189)
-	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl$1.execute(CliGitAPIImpl.java:638)
-	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl$2.execute(CliGitAPIImpl.java:880)
-	at PluginClassLoader for git//hudson.plugins.git.GitSCM.retrieveChanges(GitSCM.java:1220)
-	at PluginClassLoader for git//hudson.plugins.git.GitSCM._checkout(GitSCM.java:1310)
-	at PluginClassLoader for git//hudson.plugins.git.GitSCM.checkout(GitSCM.java:1277)
-	at PluginClassLoader for workflow-scm-step//org.jenkinsci.plugins.workflow.steps.scm.SCMStep.checkout(SCMStep.java:136)
-	at PluginClassLoader for workflow-scm-step//org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:101)
-	at PluginClassLoader for workflow-scm-step//org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:88)
-	at PluginClassLoader for workflow-step-api//org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution.lambda$start$0(SynchronousNonBlockingStepExecution.java:49)
-	at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source)
-	at java.base/java.util.concurrent.FutureTask.run(Unknown Source)
-	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)
-	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
-	at java.base/java.lang.Thread.run(Unknown Source)
-ERROR: Error cloning remote repo 'origin'
-ERROR: Maximum checkout retry attempts reached, aborting
-[Pipeline] }
-[Pipeline] // stage
-[Pipeline] }
-[Pipeline] // node
-[Pipeline] End of Pipeline
-ERROR: Error cloning remote repo 'origin'
-Finished: FAILURE
+Started by user Arvind Nandigam
+[Pipeline] Start of Pipeline
+[Pipeline] node
+Running on Jenkins in /var/jenkins_home/workspace/error_04
+[Pipeline] {
+[Pipeline] stage
+[Pipeline] { (Checkout)
+[Pipeline] git
+The recommended git tool is: NONE
+No credentials specified
+Cloning the remote Git repository
+Cloning repository https://github.com/example/repo.git
+ > git init /var/jenkins_home/workspace/error_04 # timeout=10
+Fetching upstream changes from https://github.com/example/repo.git
+ > git --version # timeout=10
+ > git --version # 'git version 2.47.3'
+ > git fetch --tags --force --progress -- https://github.com/example/repo.git +refs/heads/*:refs/remotes/origin/* # timeout=10
+ERROR: Error cloning remote repo 'origin'
+hudson.plugins.git.GitException: Command "git fetch --tags --force --progress -- https://github.com/example/repo.git +refs/heads/*:refs/remotes/origin/*" returned status code 128:
+stdout: 
+stderr: remote: Invalid username or token. Password authentication is not supported for Git operations.
+fatal: Authentication failed for 'https://github.com/example/repo.git/'
+
+	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(CliGitAPIImpl.java:2848)
+	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandWithCredentials(CliGitAPIImpl.java:2189)
+	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl$1.execute(CliGitAPIImpl.java:638)
+	at PluginClassLoader for git-client//org.jenkinsci.plugins.gitclient.CliGitAPIImpl$2.execute(CliGitAPIImpl.java:880)
+	at PluginClassLoader for git//hudson.plugins.git.GitSCM.retrieveChanges(GitSCM.java:1220)
+	at PluginClassLoader for git//hudson.plugins.git.GitSCM._checkout(GitSCM.java:1310)
+	at PluginClassLoader for git//hudson.plugins.git.GitSCM.checkout(GitSCM.java:1277)
+	at PluginClassLoader for workflow-scm-step//org.jenkinsci.plugins.workflow.steps.scm.SCMStep.checkout(SCMStep.java:136)
+	at PluginClassLoader for workflow-scm-step//org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:101)
+	at PluginClassLoader for workflow-scm-step//org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:88)
+	at PluginClassLoader for workflow-step-api//org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution.lambda$start$0(SynchronousNonBlockingStepExecution.java:49)
+	at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source)
+	at java.base/java.util.concurrent.FutureTask.run(Unknown Source)
+	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)
+	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
+	at java.base/java.lang.Thread.run(Unknown Source)
+ERROR: Error cloning remote repo 'origin'
+ERROR: Maximum checkout retry attempts reached, aborting
+[Pipeline] }
+[Pipeline] // stage
+[Pipeline] }
+[Pipeline] // node
+[Pipeline] End of Pipeline
+ERROR: Error cloning remote repo 'origin'
+Finished: FAILURE

data/errors/error_05.txt

@@ -1,16 +1,16 @@
-Started by user Arvind Nandigam
-[Pipeline] Start of Pipeline
-[Pipeline] node
-Running on Jenkins in /var/jenkins_home/workspace/error_05
-[Pipeline] {
-[Pipeline] stage
-[Pipeline] { (Auth)
-[Pipeline] withCredentials
-[Pipeline] // withCredentials
-[Pipeline] }
-[Pipeline] // stage
-[Pipeline] }
-[Pipeline] // node
-[Pipeline] End of Pipeline
-ERROR: Could not find credentials entry with ID 'does-not-exist'
+Started by user Arvind Nandigam
+[Pipeline] Start of Pipeline
+[Pipeline] node
+Running on Jenkins in /var/jenkins_home/workspace/error_05
+[Pipeline] {
+[Pipeline] stage
+[Pipeline] { (Auth)
+[Pipeline] withCredentials
+[Pipeline] // withCredentials
+[Pipeline] }
+[Pipeline] // stage
+[Pipeline] }
+[Pipeline] // node
+[Pipeline] End of Pipeline
+ERROR: Could not find credentials entry with ID 'does-not-exist'
 Finished: FAILURE

data/errors/error_06.txt

@@ -1,10 +1,10 @@
-Started by user Arvind Nandigam
-[Pipeline] Start of Pipeline
-[Pipeline] node
-Still waiting to schedule task
-‘Jenkins’ doesn’t have label ‘no-such-node’
-Aborted by Arvind Nandigam
-[Pipeline] // node
-[Pipeline] End of Pipeline
-org.jenkinsci.plugins.workflow.actions.ErrorAction$ErrorId: db6e2408-0d72-4f17-a842-4d2ecce38130
+Started by user Arvind Nandigam
+[Pipeline] Start of Pipeline
+[Pipeline] node
+Still waiting to schedule task
+‘Jenkins’ doesn’t have label ‘no-such-node’
+Aborted by Arvind Nandigam
+[Pipeline] // node
+[Pipeline] End of Pipeline
+org.jenkinsci.plugins.workflow.actions.ErrorAction$ErrorId: db6e2408-0d72-4f17-a842-4d2ecce38130
 Finished: ABORTED

data/errors/error_07.txt

@@ -1,25 +1,25 @@
-Started by user Arvind Nandigam
-
-org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
-WorkflowScript: 6: Expected a step @ line 6, column 17.
-                   def x = 1
-                   ^
-
-1 error
-
-	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
-	at org.codehaus.groovy.control.CompilationUnit.applyToPrimaryClassNodes(CompilationUnit.java:1107)
-	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:624)
-	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
-	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
-	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
-	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
-	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
-	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
-	at hudson.model.ResourceController.execute(ResourceController.java:101)
-	at hudson.model.Executor.run(Executor.java:460)
-Finished: FAILURE
+Started by user Arvind Nandigam
+
+org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
+WorkflowScript: 6: Expected a step @ line 6, column 17.
+                   def x = 1
+                   ^
+
+1 error
+
+	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
+	at org.codehaus.groovy.control.CompilationUnit.applyToPrimaryClassNodes(CompilationUnit.java:1107)
+	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:624)
+	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
+	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
+	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
+	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
+	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
+	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
+	at hudson.model.ResourceController.execute(ResourceController.java:101)
+	at hudson.model.Executor.run(Executor.java:460)
+Finished: FAILURE

data/errors/error_08.txt

@@ -1,24 +1,24 @@
-Started by user Arvind Nandigam
-org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
-WorkflowScript: 3: Invalid agent type "docker" specified. Must be one of [any, label, none] @ line 3, column 9.
-           docker {
-           ^
-
-1 error
-
-	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
-	at org.codehaus.groovy.control.CompilationUnit.applyToPrimaryClassNodes(CompilationUnit.java:1107)
-	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:624)
-	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
-	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
-	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
-	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
-	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
-	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
-	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
-	at hudson.model.ResourceController.execute(ResourceController.java:101)
-	at hudson.model.Executor.run(Executor.java:460)
-Finished: FAILURE
+Started by user Arvind Nandigam
+org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
+WorkflowScript: 3: Invalid agent type "docker" specified. Must be one of [any, label, none] @ line 3, column 9.
+           docker {
+           ^
+
+1 error
+
+	at org.codehaus.groovy.control.ErrorCollector.failIfErrors(ErrorCollector.java:309)
+	at org.codehaus.groovy.control.CompilationUnit.applyToPrimaryClassNodes(CompilationUnit.java:1107)
+	at org.codehaus.groovy.control.CompilationUnit.doPhaseOperation(CompilationUnit.java:624)
+	at org.codehaus.groovy.control.CompilationUnit.processPhaseOperations(CompilationUnit.java:602)
+	at org.codehaus.groovy.control.CompilationUnit.compile(CompilationUnit.java:579)
+	at groovy.lang.GroovyClassLoader.doParseClass(GroovyClassLoader.java:323)
+	at groovy.lang.GroovyClassLoader.parseClass(GroovyClassLoader.java:293)
+	at PluginClassLoader for script-security//org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.GroovySandbox$Scope.parse(GroovySandbox.java:162)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.doParse(CpsGroovyShell.java:202)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsGroovyShell.reparse(CpsGroovyShell.java:186)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.parseScript(CpsFlowExecution.java:669)
+	at PluginClassLoader for workflow-cps//org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.start(CpsFlowExecution.java:615)
+	at PluginClassLoader for workflow-job//org.jenkinsci.plugins.workflow.job.WorkflowRun.run(WorkflowRun.java:341)
+	at hudson.model.ResourceController.execute(ResourceController.java:101)
+	at hudson.model.Executor.run(Executor.java:460)
+Finished: FAILURE

demo_langchain_rag.py

@@ -0,0 +1,144 @@
+# demo_langchain_rag.py
+# Demo script showcasing LangChain and RAG for internship interview
+# Run: python demo_langchain_rag.py
+
+import json
+from langchain_rag import JenkinsRAGChain, get_rag_chain
+
+def print_section(title):
+    print("\n" + "=" * 60)
+    print(f"  {title}")
+    print("=" * 60)
+
+def main():
+    print_section("LangChain + RAG Demo for Textify.ai Internship")
+    print("\nThis demo showcases:")
+    print("  • LangChain framework for building LLM chains")
+    print("  • RAG (Retrieval-Augmented Generation) pattern")
+    print("  • Vector search with FAISS + HuggingFace embeddings")
+    print("  • Integration with Jenkins documentation")
+
+    print_section("1. Initializing LangChain RAG Chain")
+    print("Loading Jenkins documentation...")
+    print("Creating vector embeddings with paraphrase-MiniLM-L3-v2...")
+    print("Setting up RetrievalQA chain with FLAN-T5...")
+    
+    rag = JenkinsRAGChain()
+    print("\n✓ RAG Chain initialized successfully!")
+    print(f"  - Documents indexed: {len(rag.documents)}")
+    print(f"  - Embedding model: {rag.embeddings.model_name}")
+    print(f"  - LLM: {rag.llm.repo_id}")
+
+    test_errors = [
+        {
+            "name": "Groovy Syntax Error",
+            "log": """
+Started by user admin
+org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
+WorkflowScript: 10: expecting '}', found '' @ line 10, column 1.
+1 error
+    at org.codehaus.groovy.control.ErrorNode.accept(ErrorNode.java:36)
+"""
+        },
+        {
+            "name": "Missing Agent Error",
+            "log": """
+[Pipeline] node
+Running on in /var/jenkins/workspace/test
+[Pipeline] {
+java.lang.IllegalStateException: agent none is specified, but no stage has an agent assigned
+    at org.jenkinsci.plugins.workflow.cps.CpsFlowExecution.initialize(CpsFlowExecution.java:123)
+"""
+        },
+        {
+            "name": "Missing Plugin Error",
+            "log": """
+No such DSL method 'dockerBuild'
+Available DSL methods: 
+  archive
+  bat
+  build
+  checkout
+  deleteDir
+  dir
+  echo
+  emailext
+  fileExists
+"""
+        }
+    ]
+
+    for i, test in enumerate(test_errors, 1):
+        print_section(f"2.{i} Testing: {test['name']}")
+        print(f"\nInput Error Log:\n{test['log'][:200]}...")
+        
+        result = rag.explain_error(test['log'])
+        
+        print(f"\n--- Result ---")
+        print(f"Error Category: {result['error_category']}")
+        print(f"\nLLM Explanation (from RAG):")
+        print(result['llm_explanation'])
+        print(f"\n[Metadata]")
+        print(f"  Retrieval: {result['retrieval_source']}")
+        print(f"  LLM Model: {result['model_used']}")
+        print(f"  Embeddings: {result['embedding_model']}")
+
+    print_section("3. LangChain Architecture Summary")
+    print("""
+┌─────────────────────────────────────────────────────────────┐
+│                    LangChain RAG Pipeline                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │  User Error  │───▶│   Retriever  │───▶│     LLM      │  │
+│  │    Log       │    │  (FAISS)     │    │  (FLAN-T5)   │  │
+│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│         │                   │                   │           │
+│         ▼                   ▼                   ▼           │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
+│  │   Feature    │    │   Context    │    │   Generated  │  │
+│  │  Extraction  │    │  (Docs +     │    │   Explanation│  │
+│  │              │    │  Prompt)     │    │              │  │
+│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
+Key Components:
+  • LangChain Core: Document, Prompt, OutputParser
+  • LangChain Community: FAISS vectorstore
+  • LangChain HuggingFace: Embeddings & LLM integration
+  • RetrievalQA: End-to-end RAG chain
+""")
+
+    print_section("4. API Endpoint Demo")
+    print("""
+POST /explain-rag
+{
+  "log_text": "org.codehaus.groovy.control.MultipleCompilationErrorsException..."
+}
+
+Response:
+{
+  "error_category": "groovy_syntax_error",
+  "llm_explanation": "The error indicates...",
+  "retrieval_source": "LangChain RAG (FAISS + HuggingFace)",
+  "model_used": "google/flan-t5-base",
+  "embedding_model": "paraphrase-MiniLM-L3-v2"
+}
+""")
+
+    print("\n" + "=" * 60)
+    print("  Demo Complete!")
+    print("=" * 60)
+    print("""
+To run the API server:
+  uvicorn main:app --reload
+
+To test the /explain-rag endpoint:
+  curl -X POST http://localhost:8000/explain-rag \\
+       -H "Content-Type: application/json" \\
+       -d '{"log_text": "your error log here"}'
+""")
+
+if __name__ == "__main__":
+    main()

error_taxonomy.py

@@ -1,49 +1,49 @@
-# error_taxonomy.py
-
-ERROR_CATEGORIES = {
-    # Groovy / pipeline syntax
-    "groovy_syntax_error": [
-        r"MultipleCompilationErrorsException",
-        r"expecting '\}'",
-        r"WorkflowScript"
-    ],
-
-    # Agent / executor issues
-    "missing_agent": [
-        r"requires a node context",
-        r"agent none"
-    ],
-
-    "no_node_available": [
-        r"There are no nodes with the label",
-        r"doesn’t have label",
-        r"does not have label",
-        r"Still waiting to schedule task"
-    ],
-
-    # SCM / Git related
-    "git_authentication_error": [
-        r"Authentication failed",
-        r"Invalid username or token",
-        r"Error cloning remote repo"
-    ],
-
-    # Jenkins credentials system
-    "missing_credentials": [
-        r"Credentials .* not found",
-        r"Could not find credentials entry with ID"
-    ],
-
-    # Plugin / DSL
-    "missing_plugin": [
-        r"No such DSL method",
-        r"No such step"
-    ],
-
-    # File system
-    "file_not_found": [
-        r"No such file or directory",
-        r"cannot open",
-        r"script returned exit code 1"
-    ]
-}
+# error_taxonomy.py
+
+ERROR_CATEGORIES = {
+    # Groovy / pipeline syntax
+    "groovy_syntax_error": [
+        r"MultipleCompilationErrorsException",
+        r"expecting '\}'",
+        r"WorkflowScript"
+    ],
+
+    # Agent / executor issues
+    "missing_agent": [
+        r"requires a node context",
+        r"agent none"
+    ],
+
+    "no_node_available": [
+        r"There are no nodes with the label",
+        r"doesn’t have label",
+        r"does not have label",
+        r"Still waiting to schedule task"
+    ],
+
+    # SCM / Git related
+    "git_authentication_error": [
+        r"Authentication failed",
+        r"Invalid username or token",
+        r"Error cloning remote repo"
+    ],
+
+    # Jenkins credentials system
+    "missing_credentials": [
+        r"Credentials .* not found",
+        r"Could not find credentials entry with ID"
+    ],
+
+    # Plugin / DSL
+    "missing_plugin": [
+        r"No such DSL method",
+        r"No such step"
+    ],
+
+    # File system
+    "file_not_found": [
+        r"No such file or directory",
+        r"cannot open",
+        r"script returned exit code 1"
+    ]
+}

explain_error.py

@@ -1,126 +1,126 @@
-# explain_error.py
-
-from extract_error_features import extract_error_features
-from retrieve_docs import retrieve_docs
-
-SYSTEM_PROMPT = """
-You are a Jenkins CI/CD expert.
-
-Explain the Jenkins error using ONLY the provided documentation context.
-If the documentation does not clearly explain the error, say so explicitly.
-
-Output format:
-
-Error Summary:
-<short explanation>
-
-Likely Causes:
-- cause 1
-- cause 2
-
-Relevant Documentation:
-- link or source file
-"""
-
-def explain_error(log_text: str):
-    features = extract_error_features(log_text)
-    category = features["category"]
-
-    retrieved = retrieve_docs(category)
-
-    explanation = {
-        "error_category": category,
-        "summary": "",
-        "likely_causes": [],
-        "references": []
-    }
-
-    # Heuristic explanation (v1, deterministic)
-    if category == "groovy_syntax_error":
-        explanation["summary"] = (
-            "The pipeline failed due to a Groovy syntax error, "
-            "most likely caused by an invalid or incomplete Jenkinsfile."
-        )
-        explanation["likely_causes"] = [
-            "Missing or mismatched braces in the Jenkinsfile",
-            "Invalid declarative pipeline structure"
-        ]
-
-    elif category == "missing_agent":
-        explanation["summary"] = (
-            "The pipeline attempted to execute a step that requires a node, "
-            "but no agent was allocated."
-        )
-        explanation["likely_causes"] = [
-            "Using 'agent none' without defining a stage-level agent",
-            "Executing node-dependent steps without a workspace"
-        ]
-
-    elif category == "no_node_available":
-        explanation["summary"] = (
-            "The pipeline could not be scheduled because no Jenkins node "
-            "matched the requested label."
-        )
-        explanation["likely_causes"] = [
-            "The specified node label does not exist",
-            "All matching nodes are offline or busy"
-        ]
-
-    elif category == "missing_plugin":
-        explanation["summary"] = (
-            "The pipeline referenced a step that is not available, "
-            "indicating a missing or uninstalled plugin."
-        )
-        explanation["likely_causes"] = [
-            "Required plugin is not installed",
-            "Incorrect step name in the Jenkinsfile"
-        ]
-
-    elif category == "missing_credentials":
-        explanation["summary"] = (
-            "The pipeline referenced credentials that do not exist in Jenkins."
-        )
-        explanation["likely_causes"] = [
-            "Credentials ID is incorrect or misspelled",
-            "Credentials were not configured in Jenkins"
-        ]
-
-    elif category == "file_not_found":
-        explanation["summary"] = (
-            "The pipeline attempted to access a file that does not exist "
-            "in the workspace."
-        )
-        explanation["likely_causes"] = [
-            "File path is incorrect",
-            "File was not generated or checked out"
-        ]
-
-    elif category == "git_authentication_error":
-        explanation["summary"] = (
-            "Jenkins failed to authenticate with the Git repository during checkout."
-        )
-        explanation["likely_causes"] = [
-            "Invalid or missing Git credentials",
-            "Repository requires token-based authentication"
-        ]
-
-    else:
-        explanation["summary"] = (
-            "The error could not be confidently explained using the available documentation."
-        )
-
-    for r in retrieved:
-        explanation["references"].append(
-            f"{r['meta']['source_file']} ({r['meta']['source']})"
-        )
-    if not retrieved:
-        explanation["summary"] = (
-            "No relevant Jenkins documentation was found for this error. "
-            "The error may be plugin-specific or outside the current scope."
-        )
-        explanation["likely_causes"] = []
-        explanation["references"] = []
-
-    return explanation
-
-
+# explain_error.py
+
+from extract_error_features import extract_error_features
+from retrieve_docs import retrieve_docs
+
+SYSTEM_PROMPT = """
+You are a Jenkins CI/CD expert.
+
+Explain the Jenkins error using ONLY the provided documentation context.
+If the documentation does not clearly explain the error, say so explicitly.
+
+Output format:
+
+Error Summary:
+<short explanation>
+
+Likely Causes:
+- cause 1
+- cause 2
+
+Relevant Documentation:
+- link or source file
+"""
+
+def explain_error(log_text: str):
+    features = extract_error_features(log_text)
+    category = features["category"]
+
+    retrieved = retrieve_docs(category)
+
+    explanation = {
+        "error_category": category,
+        "summary": "",
+        "likely_causes": [],
+        "references": []
+    }
+
+    # Heuristic explanation (v1, deterministic)
+    if category == "groovy_syntax_error":
+        explanation["summary"] = (
+            "The pipeline failed due to a Groovy syntax error, "
+            "most likely caused by an invalid or incomplete Jenkinsfile."
+        )
+        explanation["likely_causes"] = [
+            "Missing or mismatched braces in the Jenkinsfile",
+            "Invalid declarative pipeline structure"
+        ]
+
+    elif category == "missing_agent":
+        explanation["summary"] = (
+            "The pipeline attempted to execute a step that requires a node, "
+            "but no agent was allocated."
+        )
+        explanation["likely_causes"] = [
+            "Using 'agent none' without defining a stage-level agent",
+            "Executing node-dependent steps without a workspace"
+        ]
+
+    elif category == "no_node_available":
+        explanation["summary"] = (
+            "The pipeline could not be scheduled because no Jenkins node "
+            "matched the requested label."
+        )
+        explanation["likely_causes"] = [
+            "The specified node label does not exist",
+            "All matching nodes are offline or busy"
+        ]
+
+    elif category == "missing_plugin":
+        explanation["summary"] = (
+            "The pipeline referenced a step that is not available, "
+            "indicating a missing or uninstalled plugin."
+        )
+        explanation["likely_causes"] = [
+            "Required plugin is not installed",
+            "Incorrect step name in the Jenkinsfile"
+        ]
+
+    elif category == "missing_credentials":
+        explanation["summary"] = (
+            "The pipeline referenced credentials that do not exist in Jenkins."
+        )
+        explanation["likely_causes"] = [
+            "Credentials ID is incorrect or misspelled",
+            "Credentials were not configured in Jenkins"
+        ]
+
+    elif category == "file_not_found":
+        explanation["summary"] = (
+            "The pipeline attempted to access a file that does not exist "
+            "in the workspace."
+        )
+        explanation["likely_causes"] = [
+            "File path is incorrect",
+            "File was not generated or checked out"
+        ]
+
+    elif category == "git_authentication_error":
+        explanation["summary"] = (
+            "Jenkins failed to authenticate with the Git repository during checkout."
+        )
+        explanation["likely_causes"] = [
+            "Invalid or missing Git credentials",
+            "Repository requires token-based authentication"
+        ]
+
+    else:
+        explanation["summary"] = (
+            "The error could not be confidently explained using the available documentation."
+        )
+
+    for r in retrieved:
+        explanation["references"].append(
+            f"{r['meta']['source_file']} ({r['meta']['source']})"
+        )
+    if not retrieved:
+        explanation["summary"] = (
+            "No relevant Jenkins documentation was found for this error. "
+            "The error may be plugin-specific or outside the current scope."
+        )
+        explanation["likely_causes"] = []
+        explanation["references"] = []
+
+    return explanation
+
+

extract_error_features.py

@@ -1,24 +1,24 @@
-import re
-from error_taxonomy import ERROR_CATEGORIES
-
-COMPILED_PATTERNS = {
-    cat: [re.compile(p) for p in pats]
-    for cat, pats in ERROR_CATEGORIES.items()
-}
-
-def extract_error_features(log_text: str) -> dict:
-    result = {
-        "category": "unknown",
-        "matched_signals": [],
-        "line_numbers": []
-    }
-
-    for category, patterns in COMPILED_PATTERNS.items():
-        for pattern in patterns:
-            if pattern.search(log_text):
-                result["category"] = category
-                result["matched_signals"].append(pattern.pattern)
-
-    result["line_numbers"] = re.findall(r"line (\d+)", log_text)
-
-    return result
+import re
+from error_taxonomy import ERROR_CATEGORIES
+
+COMPILED_PATTERNS = {
+    cat: [re.compile(p) for p in pats]
+    for cat, pats in ERROR_CATEGORIES.items()
+}
+
+def extract_error_features(log_text: str) -> dict:
+    result = {
+        "category": "unknown",
+        "matched_signals": [],
+        "line_numbers": []
+    }
+
+    for category, patterns in COMPILED_PATTERNS.items():
+        for pattern in patterns:
+            if pattern.search(log_text):
+                result["category"] = category
+                result["matched_signals"].append(pattern.pattern)
+
+    result["line_numbers"] = re.findall(r"line (\d+)", log_text)
+
+    return result

ingest_docs.py

@@ -1,54 +1,54 @@
-# ingest_docs.py
-
-import os
-import json
-import faiss
-from sentence_transformers import SentenceTransformer
-
-RAW_DOCS_DIR = "data/docs/raw"
-INDEX_PATH = "data/docs/docs.index"
-META_PATH = "data/docs/docs_meta.json"
-
-CHUNK_SIZE = 400
-
-def chunk_text(text, size):
-    chunks = []
-    for i in range(0, len(text), size):
-        chunk = text[i:i+size].strip()
-        if chunk:
-            chunks.append(chunk)
-    return chunks
-
-def main():
-    model = SentenceTransformer("paraphrase-MiniLM-L3-v2", cache_folder="./model_cache")
-
-    documents = []
-    metadata = []
-
-    for fname in os.listdir(RAW_DOCS_DIR):
-        path = os.path.join(RAW_DOCS_DIR, fname)
-        with open(path, "r", encoding="utf-8") as f:
-            text = f.read()
-
-        chunks = chunk_text(text, CHUNK_SIZE)
-        for chunk in chunks:
-            documents.append(chunk)
-            metadata.append({
-                "source_file": fname,
-                "source": f"https://www.jenkins.io/doc/"
-            })
-
-    embeddings = model.encode(documents)
-    index = faiss.IndexFlatL2(embeddings.shape[1])
-    index.add(embeddings)
-
-    os.makedirs("data/docs", exist_ok=True)
-    faiss.write_index(index, INDEX_PATH)
-
-    with open(META_PATH, "w", encoding="utf-8") as f:
-        json.dump(metadata, f, indent=2)
-
-    print(f"Ingested {len(documents)} document chunks.")
-
-if __name__ == "__main__":
-    main()
+# ingest_docs.py
+
+import os
+import json
+import faiss
+from sentence_transformers import SentenceTransformer
+
+RAW_DOCS_DIR = "data/docs/raw"
+INDEX_PATH = "data/docs/docs.index"
+META_PATH = "data/docs/docs_meta.json"
+
+CHUNK_SIZE = 400
+
+def chunk_text(text, size):
+    chunks = []
+    for i in range(0, len(text), size):
+        chunk = text[i:i+size].strip()
+        if chunk:
+            chunks.append(chunk)
+    return chunks
+
+def main():
+    model = SentenceTransformer("paraphrase-MiniLM-L3-v2", cache_folder="./model_cache")
+
+    documents = []
+    metadata = []
+
+    for fname in os.listdir(RAW_DOCS_DIR):
+        path = os.path.join(RAW_DOCS_DIR, fname)
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        chunks = chunk_text(text, CHUNK_SIZE)
+        for chunk in chunks:
+            documents.append(chunk)
+            metadata.append({
+                "source_file": fname,
+                "source": f"https://www.jenkins.io/doc/"
+            })
+
+    embeddings = model.encode(documents)
+    index = faiss.IndexFlatL2(embeddings.shape[1])
+    index.add(embeddings)
+
+    os.makedirs("data/docs", exist_ok=True)
+    faiss.write_index(index, INDEX_PATH)
+
+    with open(META_PATH, "w", encoding="utf-8") as f:
+        json.dump(metadata, f, indent=2)
+
+    print(f"Ingested {len(documents)} document chunks.")
+
+if __name__ == "__main__":
+    main()

langchain_rag.py

@@ -0,0 +1,156 @@
+# langchain_rag.py
+# LangChain-based RAG pipeline for Jenkins error explanation
+
+import os
+import json
+import tempfile
+from typing import List, Dict, Any
+
+from langchain_core.documents import Document
+from langchain_core.prompts import PromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+from langchain_community.llms import HuggingFaceHub
+from langchain.chains import RetrievalQA
+
+from extract_error_features import extract_error_features
+
+RAW_DOCS_DIR = "data/docs/raw"
+CHUNK_SIZE = 400
+
+def load_raw_docs() -> List[Document]:
+    """Load raw Jenkins documentation files and convert to LangChain Documents."""
+    documents = []
+    
+    for fname in os.listdir(RAW_DOCS_DIR):
+        path = os.path.join(RAW_DOCS_DIR, fname)
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
+        
+        chunks = chunk_text(text, CHUNK_SIZE)
+        for chunk in chunks:
+            documents.append(Document(
+                page_content=chunk,
+                metadata={
+                    "source_file": fname,
+                    "source": "https://www.jenkins.io/doc/"
+                }
+            ))
+    
+    return documents
+
+def chunk_text(text: str, size: int) -> List[str]:
+    """Split text into chunks."""
+    chunks = []
+    for i in range(0, len(text), size):
+        chunk = text[i:i+size].strip()
+        if chunk:
+            chunks.append(chunk)
+    return chunks
+
+class JenkinsRAGChain:
+    """LangChain-based RAG chain for Jenkins error explanation."""
+    
+    def __init__(self):
+        self.embeddings = HuggingFaceEmbeddings(
+            model_name="sentence-transformers/paraphrase-MiniLM-L3-v2",
+            model_kwargs={'device': 'cpu'}
+        )
+        
+        self.documents = load_raw_docs()
+        self.vectorstore = FAISS.from_documents(
+            self.documents,
+            self.embeddings
+        )
+        
+        self.retriever = self.vectorstore.as_retriever(
+            search_kwargs={"k": 5}
+        )
+        
+        self.llm = HuggingFaceHub(
+            repo_id="google/flan-t5-base",
+            model_kwargs={"temperature": 0.3, "max_new_tokens": 256}
+        )
+        
+        self.prompt = PromptTemplate(
+            template="""You are a Jenkins CI/CD expert. Use the following context from 
+official Jenkins documentation to explain the error.
+
+Context from Jenkins documentation:
+{context}
+
+Error log to explain:
+{question}
+
+Provide a clear explanation with:
+1. Error Summary
+2. Likely Causes
+3. Relevant Documentation links
+
+If the documentation doesn't cover this error, say so explicitly.""",
+            input_variables=["context", "question"]
+        )
+        
+        self.qa_chain = RetrievalQA.from_chain_type(
+            llm=self.llm,
+            chain_type="stuff",
+            retriever=self.retriever,
+            chain_type_kwargs={"prompt": self.prompt},
+            output_parser=StrOutputParser()
+        )
+    
+    def explain_error(self, log_text: str) -> Dict[str, Any]:
+        """Explain a Jenkins error using LangChain RAG."""
+        features = extract_error_features(log_text)
+        category = features["category"]
+        
+        enhanced_query = f"""
+Error Category: {category}
+
+Jenkins log:
+{log_text}
+
+Explain this error using the retrieved documentation.
+"""
+        
+        result = self.qa_chain.invoke(enhanced_query)
+        
+        return {
+            "error_category": category,
+            "llm_explanation": result,
+            "retrieval_source": "LangChain RAG (FAISS + HuggingFace)",
+            "model_used": "google/flan-t5-base",
+            "embedding_model": "paraphrase-MiniLM-L3-v2"
+        }
+
+def get_rag_chain() -> JenkinsRAGChain:
+    """Get or create the RAG chain (singleton pattern for efficiency)."""
+    if not hasattr(get_rag_chain, '_instance'):
+        get_rag_chain._instance = JenkinsRAGChain()
+    return get_rag_chain._instance
+
+
+if __name__ == "__main__":
+    print("Initializing LangChain RAG Chain...")
+    print("=" * 50)
+    
+    rag = JenkinsRAGChain()
+    
+    sample_error = """
+Started by user admin
+org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed:
+WorkflowScript: 10: expecting '}', found '' @ line 10, column 1.
+1 error
+    at org.codehaus.groovy.control.ErrorNode.accept(ErrorNode.java:36)
+    at org.codehaus.groovy.control.CompilationUnit$3.call(CompilationUnit.java:698)
+    """
+    
+    print("\nSample Jenkins Error:")
+    print(sample_error)
+    print("=" * 50)
+    
+    result = rag.explain_error(sample_error)
+    
+    print("\nResult from LangChain RAG:")
+    print(json.dumps(result, indent=2))

main.py

@@ -1,21 +1,20 @@
 from fastapi import FastAPI
 from explain_error import explain_error
+from langchain_rag import get_rag_chain
 
 app = FastAPI()
 
-
-from pydantic import BaseModel
-
-class LogRequest(BaseModel):
-    log_text: str
-
-@app.post("/explain")
-def explain(req: LogRequest):
-    return explain_error(req.log_text)
-
-from fastapi.responses import RedirectResponse
-
 @app.get("/")
-def redirect_to_docs():
-    return RedirectResponse(url="/docs")
+def home():
+    return {"message": "Jenkins Error Explainer API running"}
 
+@app.post("/explain")
+def explain(payload: dict):
+    log = payload["log_text"]
+    return explain_error(log)
+
+@app.post("/explain-rag")
+def explain_with_rag(payload: dict):
+    log = payload["log_text"]
+    rag_chain = get_rag_chain()
+    return rag_chain.explain_error(log)

preload_model.py

@@ -1,9 +1,9 @@
-from sentence_transformers import SentenceTransformer
-
-print("Downloading model...")
-MODEL = SentenceTransformer(
-    "paraphrase-MiniLM-L3-v2",
-    cache_folder="./model_cache"
-)
-
+from sentence_transformers import SentenceTransformer
+
+print("Downloading model...")
+MODEL = SentenceTransformer(
+    "paraphrase-MiniLM-L3-v2",
+    cache_folder="./model_cache"
+)
+
 print("Model cached successfully!")

requirements.txt

@@ -1,10 +1,15 @@
 fastapi
-uvicorn
-sentence-transformers==2.2.2
-huggingface_hub==0.19.4
+uvicorn[standard]
+sentence-transformers
+huggingface_hub
 faiss-cpu
 numpy
 pydantic
 torch
-transformers==4.35.2
-tokenizers==0.15.2
+transformers
+tokenizers
+langchain
+langchain-core
+langchain-community
+langchain-huggingface
+chromadb

retrieve_docs.py

@@ -1,53 +1,53 @@
-# retrieve_docs.py
-
-import json
-import faiss
-import numpy as np
-from sentence_transformers import SentenceTransformer
-
-INDEX_PATH = "data/docs/docs.index"
-META_PATH = "data/docs/docs_meta.json"
-TOP_K = 5
-
-QUERY_TEMPLATES = {
-    "groovy_syntax_error": "Jenkins pipeline Groovy syntax error missing brace",
-    "missing_agent": "Jenkins pipeline agent none requires node context",
-    "no_node_available": "Jenkins no nodes with label scheduling executor",
-    "missing_plugin": "Jenkins No such DSL method pipeline step",
-    "missing_credentials": "Jenkins credentials not found pipeline",
-    "file_not_found": "Jenkins pipeline workspace file not found",
-    "git_authentication_error": "Jenkins git authentication failed checkout"
-}
-model = SentenceTransformer(
-    "paraphrase-MiniLM-L3-v2",
-    cache_folder="./model_cache"
-)
-
-def retrieve_docs(error_category: str):
-
-    index = faiss.read_index(INDEX_PATH)
-    with open(META_PATH, "r", encoding="utf-8") as f:
-        metadata = json.load(f)
-
-    query = QUERY_TEMPLATES.get(
-        error_category,
-        "Jenkins pipeline error"
-    )
-
-    query_embedding = model.encode([query])
-    distances, indices = index.search(query_embedding, TOP_K)
-
-    results = []
-    for idx in indices[0]:
-        results.append({
-            "text": None,
-            "meta": metadata[idx]
-        })
-
-    return results
-
-
-if __name__ == "__main__":
-    results = retrieve_docs("Started by user Arvind Nandigam org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: WorkflowScript: 10: expecting '}', found '' @ line 10, column 1.1 error")
-    for r in results:
+# retrieve_docs.py
+
+import json
+import faiss
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+INDEX_PATH = "data/docs/docs.index"
+META_PATH = "data/docs/docs_meta.json"
+TOP_K = 5
+
+QUERY_TEMPLATES = {
+    "groovy_syntax_error": "Jenkins pipeline Groovy syntax error missing brace",
+    "missing_agent": "Jenkins pipeline agent none requires node context",
+    "no_node_available": "Jenkins no nodes with label scheduling executor",
+    "missing_plugin": "Jenkins No such DSL method pipeline step",
+    "missing_credentials": "Jenkins credentials not found pipeline",
+    "file_not_found": "Jenkins pipeline workspace file not found",
+    "git_authentication_error": "Jenkins git authentication failed checkout"
+}
+model = SentenceTransformer(
+    "paraphrase-MiniLM-L3-v2",
+    cache_folder="./model_cache"
+)
+
+def retrieve_docs(error_category: str):
+
+    index = faiss.read_index(INDEX_PATH)
+    with open(META_PATH, "r", encoding="utf-8") as f:
+        metadata = json.load(f)
+
+    query = QUERY_TEMPLATES.get(
+        error_category,
+        "Jenkins pipeline error"
+    )
+
+    query_embedding = model.encode([query])
+    distances, indices = index.search(query_embedding, TOP_K)
+
+    results = []
+    for idx in indices[0]:
+        results.append({
+            "text": None,
+            "meta": metadata[idx]
+        })
+
+    return results
+
+
+if __name__ == "__main__":
+    results = retrieve_docs("Started by user Arvind Nandigam org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: WorkflowScript: 10: expecting '}', found '' @ line 10, column 1.1 error")
+    for r in results:
         print(r)