jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-01-18 05:18:24 +02:00
Code Issues Releases Activity

Updated documentation

Browse Source
This commit is contained in:
Sven Merk 2019-03-08 12:33:31 +01:00
parent 78b41ce7d8
commit 6b61bc1b98
9 changed files with 424 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
documentation/bin/createDocu.groovy
View File

@ -5,7 +5,7 @@ import com.sap.piper.GenerateDocumentation
import java.util.regex.Matcher
//
// Collects helper functions for rendering the docu
// Collects helper functions for rendering the documentation
//
class TemplateHelper {
@ -83,13 +83,15 @@ class TemplateHelper {
//
class Helper {
static projectRoot = new File(Helper.class.protectionDomain.codeSource.location.path).getParentFile().getParentFile().getParentFile()
static getConfigHelper(classLoader, roots, script) {
def compilerConfig = new CompilerConfiguration()
compilerConfig.setClasspathList( roots )
new GroovyClassLoader(classLoader, compilerConfig, true)
.parseClass(new File('src/com/sap/piper/ConfigurationHelper.groovy'))
.parseClass(new File(projectRoot, 'src/com/sap/piper/ConfigurationHelper.groovy'))
.newInstance(script, [:]).loadStepDefaults()
}
@ -101,7 +103,7 @@ class Helper {
m, c -> c()
}
prepareDefaultValuesStep.metaClass.libraryResource {
f -> new File("resources/${f}").text
f -> new File(projectRoot,"resources/${f}").text
}
prepareDefaultValuesStep.metaClass.readYaml {
m -> new Yaml().load(m.text)
@ -331,8 +333,8 @@ class Helper {
stepsDir.traverse(type: FileType.FILES, maxDepth: 0) {
if(it.getName().endsWith('.groovy')) {
def scriptName = (it =~ /vars\/(.*)\.groovy/)[0][1]
def stepScript = gse.createScript("${scriptName}.groovy", new Binding())
def scriptName = (it.getName() =~ /(.*)\.groovy/)[0][1]
def stepScript = gse.createScript(it.getName(), new Binding())
for (def method in stepScript.getClass().getMethods()) {
if(method.getName() == 'call' && method.getAnnotation(GenerateDocumentation) != null) {
docuRelevantSteps << scriptName
@ -346,8 +348,8 @@ class Helper {
}
roots = [
'vars',
'src',
new File(Helper.projectRoot, "vars").getAbsolutePath(),
new File(Helper.projectRoot, "src").getAbsolutePath()
]
stepsDir = null
@ -361,12 +363,12 @@ steps = []
if(args.length >= 1)
stepsDir = new File(args[0])
stepsDir = stepsDir ?: new File('vars')
stepsDir = stepsDir ?: new File(Helper.projectRoot, "vars")
if(args.length >= 2)
stepsDocuDir = new File(args[1])
stepsDocuDir = stepsDocuDir ?: new File('documentation/docs/steps')
stepsDocuDir = stepsDocuDir ?: new File(Helper.projectRoot, "documentation/docs/steps")
if(args.length >= 3)
@ -393,7 +395,7 @@ if( !stepsDir.exists() ) {
// sanity checks
//
def gse = new GroovyScriptEngine( [ stepsDir.getName() ] as String[] , getClass().getClassLoader() )
def gse = new GroovyScriptEngine([ stepsDir.getAbsolutePath() ] as String[], GenerateDocumentation.class.getClassLoader() )
//
// find all the steps we have to document (if no step has been provided from outside)

47
documentation/docs/steps/checkChangeInDevelopment.md
View File

@ -2,7 +2,11 @@
## Description
Content here is generated from corresponding step, see `vars`.
Checks if a Change Document in SAP Solution Manager is in status 'in development'. The change document id is retrieved from the git commit history. The change document id
can also be provided via parameter `changeDocumentId`. Any value provided as parameter has a higher precedence than a value from the commit history.
By default the git commit messages between `origin/master` and `HEAD` are scanned for a line like `ChangeDocument : <changeDocumentId>`. The commit
range and the pattern can be configured. For details see 'parameters' table.
## Prerequisites
@ -10,11 +14,48 @@ Content here is generated from corresponding step, see `vars`.
## Parameters
Content here is generated from corresponding step, see `vars`.
| name | mandatory | default | possible values |
|------|-----------|---------|-----------------|
| `changeDocumentId` | yes | | |
| `changeManagement/changeDocumentLabel` | no | `ChangeDocument\s?:` | regex pattern |
| `changeManagement/clientOpts` | no | | |
| `changeManagement/credentialsId` | no | `CM` | |
| `changeManagement/endpoint` | yes | | |
| `changeManagement/git/format` | no | `%b` | see `git log --help` |
| `changeManagement/git/from` | no | `origin/master` | |
| `changeManagement/git/to` | no | `HEAD` | |
| `failIfStatusIsNotInDevelopment` | no | `true` | `true`, `false` |
| `script` | yes | | |
* `changeDocumentId` - The id of the change document to transport. If not provided, it is retrieved from the git commit history.
* `changeManagement/changeDocumentLabel` - A pattern used for identifying lines holding the change document id.
* `changeManagement/clientOpts` - Additional options for cm command line client, e.g. like JAVA_OPTS.
* `changeManagement/credentialsId` - The id of the credentials to connect to the Solution Manager. The credentials needs to be maintained on Jenkins.
* `changeManagement/endpoint` - The address of the Solution Manager.
* `changeManagement/git/format` - Specifies what part of the commit is scanned. By default the body of the commit message is scanned.
* `changeManagement/git/from` - The starting point for retrieving the change document id
* `changeManagement/git/to` - The end point for retrieving the change document id
* `failIfStatusIsNotInDevelopment` - When set to `false` the step will not fail in case the step is not in status 'in development'.
* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in `script: this`. This allows the function to access the commonPipelineEnvironment for retrieving, for example, configuration parameters.
## Step configuration
Content here is generated from corresponding step, see `vars`.
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections of the config.yml the configuration is possible:
| parameter | general | step | stage |
|-----------|---------|------|-------|
| `changeDocumentId` | | | X |
| `changeManagement/changeDocumentLabel` | X | X | X |
| `changeManagement/clientOpts` | X | X | X |
| `changeManagement/credentialsId` | X | X | X |
| `changeManagement/endpoint` | X | X | X |
| `changeManagement/git/format` | X | X | X |
| `changeManagement/git/from` | X | X | X |
| `changeManagement/git/to` | X | X | X |
| `failIfStatusIsNotInDevelopment` | | X | X |
| `script` | | | |
## Exceptions

75
documentation/docs/steps/dockerExecute.md
View File

@ -2,11 +2,55 @@
## Description
Content here is generated from corresponding step, see `vars`.
Executes a closure inside a docker container with the specified docker image.
The workspace is mounted into the docker image.
Proxy environment variables defined on the Jenkins machine are also available in the Docker container.
## Parameters
Content here is generated from corresponding step, see `vars`.
| name | mandatory | default | possible values |
|------|-----------|---------|-----------------|
| `containerCommand` | no | | |
| `containerPortMappings` | no | | |
| `containerShell` | no | | |
| `dockerEnvVars` | no | | |
| `dockerImage` | no | | |
| `dockerName` | no | | |
| `dockerOptions` | no | | |
| `dockerPullImage` | no | `true` | |
| `dockerVolumeBind` | no | | |
| `dockerWorkspace` | no | | |
| `jenkinsKubernetes` | no | `[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]` | |
| `script` | yes | | |
| `sidecarEnvVars` | no | | |
| `sidecarImage` | no | | |
| `sidecarName` | no | | |
| `sidecarOptions` | no | | |
| `sidecarPullImage` | no | `true` | |
| `sidecarVolumeBind` | no | | |
| `sidecarWorkspace` | no | | |
| `stashContent` | no | | |
* `containerCommand` - Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
* `containerPortMappings` - Map which defines per docker image the port mappings, e.g. `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`.
* `containerShell` - Kubernetes only: Allows to specify the shell to be used for execution of commands.
* `dockerEnvVars` - Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080'].
* `dockerImage` - Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
* `dockerName` - Kubernetes only: Name of the container launching `dockerImage`. SideCar only: Name of the container in local network.
* `dockerOptions` - Docker options to be set when starting the container (List or String).
* `dockerPullImage` - Set this to 'false' to bypass a docker image pull. Usefull during development process. Allows testing of images which are available in the local registry only.
* `dockerVolumeBind` - Volumes that should be mounted into the container.
* `dockerWorkspace` - Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`.
* `jenkinsKubernetes` -
* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in `script: this`. This allows the function to access the commonPipelineEnvironment for retrieving, for example, configuration parameters.
* `sidecarEnvVars` - as `dockerEnvVars` for the sidecar container
* `sidecarImage` - as `dockerImage` for the sidecar container
* `sidecarName` - as `dockerName` for the sidecar container
* `sidecarOptions` - as `dockerOptions` for the sidecar container
* `sidecarPullImage` - Set this to 'false' to bypass a docker image pull. Usefull during development process. Allows testing of images which are available in the local registry only.
* `sidecarVolumeBind` - as `dockerVolumeBind` for the sidecar container
* `sidecarWorkspace` - as `dockerWorkspace` for the sidecar container
* `stashContent` - Specific stashes that should be considered for the step execution.
## Kubernetes support
@ -14,7 +58,32 @@ If the Jenkins is setup on a Kubernetes cluster, then you can execute the closur
## Step configuration
Content here is generated from corresponding step, see `vars`.
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections of the config.yml the configuration is possible:
| parameter | general | step | stage |
|-----------|---------|------|-------|
| `containerCommand` | | X | X |
| `containerPortMappings` | | X | X |
| `containerShell` | | X | X |
| `dockerEnvVars` | | X | X |
| `dockerImage` | | X | X |
| `dockerName` | | X | X |
| `dockerOptions` | | X | X |
| `dockerPullImage` | | X | X |
| `dockerVolumeBind` | | X | X |
| `dockerWorkspace` | | X | X |
| `jenkinsKubernetes` | X | X | X |
| `script` | | | |
| `sidecarEnvVars` | | X | X |
| `sidecarImage` | | X | X |
| `sidecarName` | | X | X |
| `sidecarOptions` | | X | X |
| `sidecarPullImage` | | X | X |
| `sidecarVolumeBind` | | X | X |
| `sidecarWorkspace` | | X | X |
| `stashContent` | | X | X |
## Side effects

68
documentation/docs/steps/dockerExecuteOnKubernetes.md
View File

@ -2,7 +2,8 @@
## Description
Content here is generated from corresponding step, see `vars`.
Executes a closure inside a container in a kubernetes pod.
Proxy environment variables defined on the Jenkins machine are also available in the container.
## Prerequisites
@ -13,11 +14,72 @@ Content here is generated from corresponding step, see `vars`.
## Parameters
Content here is generated from corresponding step, see `vars`.
| name | mandatory | default | possible values |
|------|-----------|---------|-----------------|
| `containerCommand` | no | | |
| `containerCommands` | no | | |
| `containerEnvVars` | no | | |
| `containerMap` | no | | |
| `containerName` | no | | |
| `containerPortMappings` | no | | |
| `containerPullImageFlags` | no | | |
| `containerShell` | no | | |
| `containerWorkspaces` | no | | |
| `dockerEnvVars` | no | | |
| `dockerImage` | yes | | |
| `dockerPullImage` | no | `true` | |
| `dockerWorkspace` | no | | |
| `jenkinsKubernetes` | no | `[jnlpAgent:s4sdk/jenkins-agent-k8s:latest]` | |
| `script` | yes | | |
| `stashContent` | no | | |
| `stashExcludes` | no | `[workspace:nohup.out]` | |
| `stashIncludes` | no | `[workspace:**/*]` | |
* `containerCommand` - Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (`/usr/bin/tail -f /dev/null`).
* `containerCommands` - Specifies start command for containers to overwrite Piper default (`/usr/bin/tail -f /dev/null`). If container's defaultstart command should be used provide empty string like: `['selenium/standalone-chrome': '']`.
* `containerEnvVars` - Specifies environment variables per container. If not provided `dockerEnvVars` will be used.
* `containerMap` - A map of docker image to the name of the container. The pod will be created with all the images from this map and they are labled based on the value field of each map entry. Example: `['maven:3.5-jdk-8-alpine': 'mavenExecute', 'selenium/standalone-chrome': 'selenium', 'famiko/jmeter-base': 'checkJMeter', 's4sdk/docker-cf-cli': 'cloudfoundry']`
* `containerName` - Optional configuration in combination with containerMap to define the container where the commands should be executed in.
* `containerPortMappings` - Map which defines per docker image the port mappings, e.g. `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`.
* `containerPullImageFlags` - Specifies the pullImage flag per container.
* `containerShell` - Allows to specify the shell to be executed for container with containerName.
* `containerWorkspaces` - Specifies a dedicated user home directory per container which will be passed as value for environment variable `HOME`. If not provided `dockerWorkspace` will be used.
* `dockerEnvVars` - Environment variables to set in the container, e.g. [http_proxy:'proxy:8080'].
* `dockerImage` - Name of the docker image that should be used. If empty, Docker is not used.
* `dockerPullImage` - Set this to 'false' to bypass a docker image pull. Usefull during development process. Allows testing of images which are available in the local registry only.
* `dockerWorkspace` - Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`.
* `jenkinsKubernetes` -
* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in `script: this`. This allows the function to access the commonPipelineEnvironment for retrieving, for example, configuration parameters.
* `stashContent` - Specific stashes that should be considered for the step execution.
* `stashExcludes` -
* `stashIncludes` -
## Step configuration
Content here is generated from corresponding step, see `vars`.
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections of the config.yml the configuration is possible:
| parameter | general | step | stage |
|-----------|---------|------|-------|
| `containerCommand` | | X | X |
| `containerCommands` | | X | X |
| `containerEnvVars` | | X | X |
| `containerMap` | | X | X |
| `containerName` | | X | X |
| `containerPortMappings` | | X | X |
| `containerPullImageFlags` | | X | X |
| `containerShell` | | X | X |
| `containerWorkspaces` | | X | X |
| `dockerEnvVars` | | X | X |
| `dockerImage` | | X | X |
| `dockerPullImage` | | X | X |
| `dockerWorkspace` | | X | X |
| `jenkinsKubernetes` | X | X | X |
| `script` | | | |
| `stashContent` | | X | X |
| `stashExcludes` | | X | |
| `stashIncludes` | | X | |
## Side effects

29
documentation/docs/steps/npmExecute.md
View File

@ -2,15 +2,38 @@
## Description
Content here is generated from corresponding step, see `vars`.
Executes NPM commands inside a docker container.
Docker image, docker options and npm commands can be specified or configured.
## Parameters
Content here is generated from corresponding step, see `vars`.
| name | mandatory | default | possible values |
|------|-----------|---------|-----------------|
| `defaultNpmRegistry` | no | | |
| `dockerImage` | no | `node:8-stretch` | |
| `dockerOptions` | no | | |
| `npmCommand` | no | | |
| `script` | yes | | |
* `defaultNpmRegistry` - URL of default NPM registry
* `dockerImage` - Name of the docker image that should be used, in which node should be installed and configured. Default value is 'node:8-stretch'.
* `dockerOptions` - Docker options to be set when starting the container.
* `npmCommand` - Which NPM command should be executed.
* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in `script: this`. This allows the function to access the commonPipelineEnvironment for retrieving, for example, configuration parameters.
## Step configuration
Content here is generated from corresponding step, see `vars`.
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections of the config.yml the configuration is possible:
| parameter | general | step | stage |
|-----------|---------|------|-------|
| `defaultNpmRegistry` | | X | X |
| `dockerImage` | | X | X |
| `dockerOptions` | | | X |
| `npmCommand` | | X | X |
| `script` | | | |
## Exceptions

78
documentation/docs/steps/uiVeri5ExecuteTests.md
View File

@ -2,17 +2,89 @@
## Description
Content here is generated from corresponding step, see `vars`.
With this step [UIVeri5](https://github.com/SAP/ui5-uiveri5) tests can be executed.
UIVeri5 describes following benefits on its GitHub page:
* Automatic synchronization with UI5 app rendering so there is no need to add waits and sleeps to your test. Tests are reliable by design.
* Tests are written in synchronous manner, no callbacks, no promise chaining so are really simple to write and maintain.
* Full power of webdriverjs, protractor and jasmine - deferred selectors, custom matchers, custom locators.
* Control locators (OPA5 declarative matchers) allow locating and interacting with UI5 controls.
* Does not depend on testability support in applications - works with autorefreshing views, resizing elements, animated transitions.
* Declarative authentications - authentication flow over OAuth2 providers, etc.
* Console operation, CI ready, fully configurable, no need for java (comming soon) or IDE.
* Covers full ui5 browser matrix - Chrome,Firefox,IE,Edge,Safari,iOS,Android.
* Open-source, modify to suite your specific neeeds.
!!! note "Browser Matrix"
With this step and the underlying Docker image ([selenium/standalone-chrome](https://github.com/SeleniumHQ/docker-selenium/tree/master/StandaloneChrome)) only Chrome tests are possible.
Testing of further browsers can be done with using a custom Docker image.
## Prerequisites
## Parameters
Content here is generated from corresponding step, see `vars`.
| name | mandatory | default | possible values |
|------|-----------|---------|-----------------|
| `dockerEnvVars` | no | | |
| `dockerImage` | no | | |
| `dockerWorkspace` | no | | |
| `failOnError` | no | | `true`, `false` |
| `gitBranch` | no | | |
| `gitSshKeyCredentialsId` | no | | Jenkins credentialId |
| `installCommand` | no | `npm install @ui5/uiveri5 --global --quiet` | |
| `runCommand` | no | `uiveri5 --seleniumAddress='http://${config.seleniumHost}:${config.seleniumPort}/wd/hub'` | |
| `script` | yes | | |
| `seleniumHost` | no | | |
| `seleniumPort` | no | `4444` | |
| `sidecarEnvVars` | no | | |
| `sidecarImage` | no | | |
| `stashContent` | no | `[buildDescriptor, tests]` | |
| `testOptions` | no | | |
| `testRepository` | no | | |
* `dockerEnvVars` - A map of environment variables to set in the container, e.g. [http_proxy:'proxy:8080'].
* `dockerImage` - The name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
* `dockerWorkspace` - Only relevant for Kubernetes case: Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`.
* `failOnError` - With `failOnError` the behavior in case tests fail can be defined.
* `gitBranch` - In case a `testRepository` is provided the branch in this repository can be specified with `gitBranch`.
* `gitSshKeyCredentialsId` - In case a `testRepository` is provided and it is protected, access credentials (as Jenkins credentials) can be provided with `gitSshKeyCredentialsId`. **Note: In case of using a protected repository, `testRepository` should include the ssh link to the repository.**
* `installCommand` - The command that is executed to install the test tool.
* `runCommand` - The command that is executed to start the tests.
* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in `script: this`. This allows the function to access the commonPipelineEnvironment for retrieving, for example, configuration parameters.
* `seleniumHost` - The host of the selenium hub, this is set automatically to `localhost` in a Kubernetes environment (determined by the `ON_K8S` environment variable) of to `selenium` in any other case. The value is only needed for the `runCommand`.
* `seleniumPort` - The port of the selenium hub. The value is only needed for the `runCommand`.
* `sidecarEnvVars` - A map of environment variables to set in the sidecar container, similar to `dockerEnvVars`.
* `sidecarImage` - The name of the docker image of the sidecar container. If empty, no sidecar container is started.
* `stashContent` - If specific stashes should be considered for the tests, their names need to be passed via the parameter `stashContent`.
* `testOptions` - This allows to set specific options for the UIVeri5 execution. Details can be found [in the UIVeri5 documentation](https://github.com/SAP/ui5-uiveri5/blob/master/docs/config/config.md#configuration).
* `testRepository` - With `testRepository` the tests can be loaded from another reposirory.
## Step configuration
Content here is generated from corresponding step, see `vars`.
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections of the config.yml the configuration is possible:
| parameter | general | step | stage |
|-----------|---------|------|-------|
| `dockerEnvVars` | | X | X |
| `dockerImage` | | X | X |
| `dockerWorkspace` | | X | X |
| `failOnError` | | X | X |
| `gitBranch` | | X | X |
| `gitSshKeyCredentialsId` | X | X | X |
| `installCommand` | | X | X |
| `runCommand` | | X | X |
| `script` | | | |
| `seleniumHost` | | X | X |
| `seleniumPort` | | X | X |
| `sidecarEnvVars` | | X | X |
| `sidecarImage` | | X | X |
| `stashContent` | | X | X |
| `testOptions` | | X | X |
| `testRepository` | | X | X |
## Exceptions

127
documentation/docs/steps/whitesourceExecuteScan.md Normal file
View File

@ -0,0 +1,127 @@
# whitesourceExecuteScan
## Description
With this step [WhiteSource](https://www.whitesourcesoftware.com) security and license compliance scans can be executed and assessed.
WhiteSource is a Software as a Service offering based on a so called unified agent that locally determines the dependency
tree of a node.js, Java, Python, Ruby, or Scala based solution and sends it to the WhiteSource server for a policy based license compliance
check and additional Free and Open Source Software Publicly Known Vulnerabilities detection.
!!! note "Docker Images"
The underlying Docker images are public and specific to the solution's programming language(s) and may therefore be exchanged
to fit and suite the relevant scenario. The default Python environment used is i.e. Python 3 based.
## Prerequisites
## Parameters
| name | mandatory | default | possible values |
|------|-----------|---------|-----------------|
| `agentDownloadUrl` | no | `https://github.com/whitesource/unified-agent-distribution/raw/master/standAlone/${config.agentFileName}` | |
| `agentFileName` | no | `wss-unified-agent.jar` | |
| `agentParameters` | no | | |
| `buildDescriptorExcludeList` | no | | |
| `buildDescriptorFile` | no | | |
| `configFilePath` | no | `./wss-unified-agent.config` | |
| `createProductFromPipeline` | no | `true` | |
| `cvssSeverityLimit` | no | `-1` | `-1` to switch failing off, any `positive integer between 0 and 10` to fail on issues with the specified limit or above |
| `dockerImage` | no | | |
| `dockerWorkspace` | no | | |
| `emailAddressesOfInitialProductAdmins` | no | | |
| `jreDownloadUrl` | no | `https://github.com/SAP/SapMachine/releases/download/sapmachine-11.0.2/sapmachine-jre-11.0.2_linux-x64_bin.tar.gz` | |
| `licensingVulnerabilities` | no | `true` | `true`, `false` |
| `orgAdminUserTokenCredentialsId` | no | | |
| `orgToken` | yes | | |
| `parallelLimit` | no | `15` | |
| `productName` | yes | | |
| `productToken` | no | | |
| `productVersion` | no | | |
| `projectNames` | no | | |
| `reporting` | no | `true` | `true`, `false` |
| `scanType` | no | | `maven`, `mta`, `npm`, `pip`, `sbt` |
| `script` | yes | | |
| `securityVulnerabilities` | no | `true` | `true`, `false` |
| `serviceUrl` | yes | | |
| `stashContent` | no | | |
| `timeout` | no | | |
| `userTokenCredentialsId` | yes | | |
| `verbose` | no | | `true`, `false` |
| `vulnerabilityReportFileName` | no | `piper_whitesource_vulnerability_report` | |
| `vulnerabilityReportTitle` | no | `WhiteSource Security Vulnerability Report` | |
* `agentDownloadUrl` - URL used to download the latest version of the WhiteSource Unified Agent.
* `agentFileName` - Locally used name for the Unified Agent jar file after download.
* `agentParameters` - Additional parameters passed to the Unified Agent command line.
* `buildDescriptorExcludeList` - List of build descriptors and therefore modules to exclude from the scan and assessment activities.
* `buildDescriptorFile` - Explicit path to the build descriptor file.
* `configFilePath` - Explicit path to the WhiteSource Unified Agent configuration file.
* `createProductFromPipeline` - Whether to create the related WhiteSource product on the fly based on the supplied pipeline configuration.
* `cvssSeverityLimit` - Limit of tollerable CVSS v3 score upon assessment and in consequence fails the build, defaults to `-1`.
* `dockerImage` - Docker image to be used for scanning.
* `dockerWorkspace` - Docker workspace to be used for scanning.
* `emailAddressesOfInitialProductAdmins` - The list of email addresses to assign as product admins for newly created WhiteSource products.
* `jreDownloadUrl` - URL used for downloading the Java Runtime Environment (JRE) required to run the WhiteSource Unified Agent.
* `licensingVulnerabilities` - Whether license compliance is considered and reported as part of the assessment.
* `orgAdminUserTokenCredentialsId` - Jenkins credentials ID referring to the organization admin's token.
* `orgToken` - WhiteSource token identifying your organization.
* `parallelLimit` - Limit of parallel jobs being run at once in case of `scanType: 'mta'` based scenarios, defaults to `15`.
* `productName` - Name of the WhiteSource product to be created and used for results aggregation.
* `productToken` - Token of the WhiteSource product to be created and used for results aggregation, usually determined automatically.
* `productVersion` - Version of the WhiteSource product to be created and used for results aggregation, usually determined automatically.
* `projectNames` - List of WhiteSource projects to be included in the assessment part of the step, usually determined automatically.
* `reporting` - Whether assessment is being done at all, defaults to `true`.
* `scanType` - Type of development stack used to implement the solution.
* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in `script: this`. This allows the function to access the commonPipelineEnvironment for retrieving, for example, configuration parameters.
* `securityVulnerabilities` - Whether security compliance is considered and reported as part of the assessment.
* `serviceUrl` - URL to the WhiteSource server API used for communication, defaults to `https://saas.whitesourcesoftware.com/api`.
* `stashContent` - List of stashes to be unstashed into the workspace before performing the scan.
* `timeout` - Timeout in seconds until a HTTP call is forcefully terminated.
* `userTokenCredentialsId` - Jenkins credentials ID referring to the product admin's token.
* `verbose` - Whether verbose output should be produced.
* `vulnerabilityReportFileName` - Name of the file the vulnerability report is written to.
* `vulnerabilityReportTitle` - Title of vulnerability report written during the assessment phase.
## Step configuration
We recommend to define values of step parameters via [config.yml file](../configuration.md).
In following sections of the config.yml the configuration is possible:
| parameter | general | step | stage |
|-----------|---------|------|-------|
| `agentDownloadUrl` | | X | X |
| `agentFileName` | | X | X |
| `agentParameters` | | X | X |
| `buildDescriptorExcludeList` | | X | X |
| `buildDescriptorFile` | | X | X |
| `configFilePath` | | X | X |
| `createProductFromPipeline` | | X | X |
| `cvssSeverityLimit` | | X | X |
| `dockerImage` | | X | X |
| `dockerWorkspace` | | X | X |
| `emailAddressesOfInitialProductAdmins` | | X | X |
| `jreDownloadUrl` | | X | X |
| `licensingVulnerabilities` | | X | X |
| `orgAdminUserTokenCredentialsId` | X | X | X |
| `orgToken` | X | X | X |
| `parallelLimit` | | X | X |
| `productName` | X | X | X |
| `productToken` | X | X | X |
| `productVersion` | X | X | X |
| `projectNames` | X | X | X |
| `reporting` | | X | X |
| `scanType` | X | X | X |
| `script` | | | |
| `securityVulnerabilities` | | X | X |
| `serviceUrl` | X | X | X |
| `stashContent` | | X | X |
| `timeout` | | X | X |
| `userTokenCredentialsId` | X | X | X |
| `verbose` | X | X | X |
| `vulnerabilityReportFileName` | | X | X |
| `vulnerabilityReportTitle` | | X | X |
## Exceptions
## Examples

1
documentation/mkdocs.yml
View File

@ -38,6 +38,7 @@ nav:
- transportRequestRelease: steps/transportRequestRelease.md
- transportRequestUploadFile: steps/transportRequestUploadFile.md
- uiVeri5ExecuteTests: steps/uiVeri5ExecuteTests.md
- whitesourceExecuteScan: steps/whitesourceExecuteScan.md
- 'Scenarios':
- 'Build and Deploy Hybrid Applications with Jenkins and SAP Solution Manager': scenarios/changeManagement.md
- 'Build and Deploy SAP UI5 or SAP Fiori Applications on SAP Cloud Platform with Jenkins': scenarios/ui5-sap-cp/Readme.md

4
vars/whitesourceExecuteScan.groovy
View File

@ -166,9 +166,9 @@ import static com.sap.piper.Prerequisites.checkScript
/**
* With this step [WhiteSource](https://www.whitesourcesoftware.com) security and license compliance scans can be executed and assessed.
*
* WhiteSource is a Software as a Service offering based on a so called unified scanning agent that locally determines the dependency
* WhiteSource is a Software as a Service offering based on a so called unified agent that locally determines the dependency
* tree of a node.js, Java, Python, Ruby, or Scala based solution and sends it to the WhiteSource server for a policy based license compliance
* check and additional Free and Open Source Software Publicly Known Vulnerabilities assessment.
* check and additional Free and Open Source Software Publicly Known Vulnerabilities detection.
*
* !!! note "Docker Images"
* The underlying Docker images are public and specific to the solution's programming language(s) and may therefore be exchanged