diff --git a/.editorconfig b/.editorconfig index 037a081ad..b7d3f9493 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,7 +11,7 @@ indent_style = space indent_size = 4 insert_final_newline = true trim_trailing_whitespace = true -[*.{yml,yaml}] +[*.{yml,yaml,md}] indent_size = 2 [*.png] indent_style = none diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index feb76cf38..8b308b01f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,7 @@ # Guidance on how to contribute There are two primary ways to help: + * Using the issue tracker, and * Changing the code-base. @@ -15,13 +16,16 @@ Use the issue tracker to find ways to contribute. Find a bug or a feature, menti Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull-request. All new code should have been thoroughly tested end-to-end in order to validate implemented features and the presence or lack of defects. ### Working with forks + * [Configure this repository as a remote for your own fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/), and * [Sync your fork with this repository](https://help.github.com/articles/syncing-a-fork/) before beginning to work on a new pull-request. ### Tests + All pipeline library coding _must_ come with automated unit tests. ### Documentation + The contract of functionality exposed by a library functionality needs to be documented, so it can be properly used. Implementation of a functionality and its documentation shall happen within the same commit(s). @@ -30,6 +34,7 @@ Implementation of a functionality and its documentation shall happen within the Pipeline steps must not make use of return values. The pattern for sharing parameters between pipeline steps or between a pipeline step and a pipeline script is sharing values via the [`commonPipelineEnvironment`](../vars/commonPipelineEnvironment.groovy). Since there is no return value from a pipeline step the return value of a pipeline step is already `void` rather than `def`. ### Code Style + The code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of guidelines, mimic the styles and patterns in the existing code-base. Variables, methods, types and so on shall have meaningful self describing names. Doing so makes understanding code easier and requires less commenting. It helps people who did not write the code to understand it better. @@ -41,11 +46,13 @@ Code shall contain comments to explain the intention of the code when it is uncl To ensure a common file format, there is a `.editorConfig` file [in place](.editorconfig). To respect this file, [check](http://editorconfig.org/#download) if your editor does support it natively or you need to download a plugin. ### Commit Message Style + Write [meaningful commit messages](http://who-t.blogspot.de/2009/12/on-commit-messages.html) and [adhere to standard formatting](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). Good commit messages speed up the review process and help to keep this project maintainable in the long term. ## Code Style + The intention of this section is to describe the code style for this project. As reference document, the [Groovy's style guide](http://groovy-lang.org/style-guide.html) was taken. For further reading about Groovy's syntax and examples, please refer to this guide. This project is intended to run in Jenkins [[2]](https://jenkins.io/doc/book/getting-started/) as part of a Jenkins Pipeline [[3]](https://jenkins.io/doc/book/pipeline/). It is composed by Jenkins Pipeline's syntax, Groovy's syntax and Java's syntax. @@ -57,18 +64,23 @@ As Groovy supports 99% of Java’s syntax [[1]](http://groovy-lang.org/style-gui ### Omit semicolons ### Use the return keyword + In Groovy it is optional to use the _return_ keyword. Use explicitly the _return_ keyword for better readability. ### Use def + When using _def_ in Groovy, the type is Object. Using _def_ simplifies the code, for example imports are not needed, and therefore the development is faster. ### Do not use a visibility modifier for public classes and methods + By default, classes and methods are public, the use of the public modifier is not needed. ### Do not omit parentheses for Groovy methods + In Groovy is possible to omit parentheses for top-level expressions, but [Jenkins Pipeline's syntax](https://jenkins.io/doc/book/pipeline/syntax/) use a block, specifically `pipeline { }` as top-level expression [[4]](https://jenkins.io/doc/book/pipeline/syntax/). Do not omit parenthesis for Groovy methods because Jenkins will interpret the method as a Pipeline Step. Conversely, do omit parenthesis for Jenkins Pipeline's Steps. ### Omit the .class suffix + In Groovy, the .class suffix is not needed. Omit the .class suffix for simplicity and better readability. e.g. `new ExpectedException().expect(AbortException.class)` @@ -76,9 +88,11 @@ e.g. `new ExpectedException().expect(AbortException.class)` --> `new ExpectedException().expect(AbortException)` ### Omit getters and setters + When declaring a field without modifier inside a Groovy bean, the Groovy compiler generates a private field and a getter and setter. ### Do not initialize beans with named parameters + Do not initialize beans with named parameters, because it is not supported by Jenkins: e.g. `Version javaVersion = new Version( major: 1, minor: 8)` @@ -92,54 +106,72 @@ Use named parameters for Jenkins Pipeline Steps: e.g. `sh returnStdout: true, script: command` ### Do not use _with()_ operator + The _with_ operator is not yet supported by Jenkins, and it must not be used or encapsulated in a @NonCPS method. ### Use _==_ operator + Use Groovy’s `==` instead of Java `equals()` to avoid NullPointerExceptions. To compare the references of objects, instead of `==`, you should use `a.is(b)` [[1]](http://groovy-lang.org/style-guide.html). ### Use GStrings + In Groovy, single quotes create Java Strings, and double quotes can create Java Strings or GStrings, depending if there is or not interpolation of variables [[1]](http://groovy-lang.org/style-guide.html). Using GStrings variable and string concatenation is more simple. #### Do not use curly braces {} for variables or variable.property + For variables, or variable.property, drop the curly braces: e.g. `echo "[INFO] ${name} version ${version.version} is installed."` --> `echo "[INFO] $name version $version.version is installed."` -#### Use 'single quotes' for Strings and constants. -#### Use "double quotes" for GStrings. -#### Use '''triple single quotes''' for multiline Strings. -#### Use """triple double quotes""" for multiline GStrings. -#### Use /slash/ for regular expresions. +#### Use 'single quotes' for Strings and constants + +#### Use "double quotes" for GStrings + +#### Use '''triple single quotes''' for multiline Strings + +#### Use """triple double quotes""" for multiline GStrings + +#### Use /slash/ for regular expresions + This notation avoids to double escape backslashes, making easier working with regex. ### Use native syntax for data structures + Use the native syntax for data structures provided by Groovy like lists, maps, regex, or ranges of values. ### Use aditional Groovy methods + Use the additional methods provided by Groovy to manipulate String, Files, Streams, Collections, and other classes. For a complete description of all available methods, please read the GDK API [[5]](http://groovy-lang.org/groovy-dev-kit.html). ### Use Groovy's switch + Groovy’s switch accepts any kind of type, thereby is more powerful. In this case, the use of _def_ instead of a type is necessary. ### Use alias for import + In Groovy, it is possible to assign an alias to imported packages. Use alias for imported packages to avoid the use of fully-qualified names and increase readability. ### Use Groovy syntax to check objects + In Groovy a null, void, equal to zero, or empty object evaluates to false, and if not, evaluates to true. Instead of writing null and size checks e.g. `if (name != null && name.length > 0) {}`, use just the object `if (name) {}`. ### Use _?._ operator + Use the safe dereference operator _?._, to simplify the code for accessing objects and object members safely. Using this operator, the Groovy compiler checks null objects and null object members, and returns _null_ if the object or the object member is null and never throws a NullPointerException. ### Use _?:_ operator + Use Elvis operator _?:_ to simplify default value validations. ### Use _any_ keyword + If the type of the exception thrown inside a try block is not important, catch any exception using the _any_ keyword. ### Use _assert_ + To check parameters, return values, and more, use the assert statement. ## Reference diff --git a/README.md b/README.md index aec9b07bf..59e8ae3b8 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,10 @@ the most important SAP technologies by means of Jenkins pipelines. Project "Piper" consists of two parts: - * [A shared library][piper-library] containing steps and utilities that are - required by Jenkins pipelines. - * A set of [Jenkins pipelines][piper-pipelines] using the piper library to - implement best practice processes. +* [A shared library][piper-library] containing steps and utilities that are + required by Jenkins pipelines. +* A set of [Jenkins pipelines][piper-pipelines] using the piper library to + implement best practice processes. Please follow [this link to our extended library documentation][piper-library-pages]. @@ -54,13 +54,13 @@ without prior notice. # Requirements - * Java Runtime Environment 8 - * Installation of Jenkins v 2.60.3 or higher running on Linux. We tested with - debian-stretch. - * Jenkins Plugins installed as described in the [Required - Plugin][piper-library-pages-plugins] section. - * A Jenkins user with administration privileges. - * The Jenkins instance has access to [github.com][github]. +* Java Runtime Environment 8 +* Installation of Jenkins v 2.60.3 or higher running on Linux. We tested with + debian-stretch. +* Jenkins Plugins installed as described in the [Required + Plugin][piper-library-pages-plugins] section. +* A Jenkins user with administration privileges. +* The Jenkins instance has access to [github.com][github]. # Download and Installation @@ -83,7 +83,7 @@ To setup the shared library, you need to perform the following steps: Now the library is available as `piper-library-os` and can be used in any `Jenkinsfile` by adding this line: -``` +```groovy @Library('piper-library-os') _ ``` diff --git a/documentation/docs/configuration.md b/documentation/docs/configuration.md index 3655ab2bb..d61db5fb5 100644 --- a/documentation/docs/configuration.md +++ b/documentation/docs/configuration.md @@ -42,10 +42,9 @@ Following data (non-personal) is collected for example: 2. Individual deactivation per step by passing the parameter `collectTelemetryData: false`, like e.g. `setVersion script:this, collectTelemetryData: false` - ## Example configuration -``` +```yaml general: gitSshKeyCredentialsId: GitHub_Test_SSH @@ -69,7 +68,8 @@ Configuration is loaded into `commonPipelineEnvironment` during step [setupCommo You can access the configuration values via `commonPipelineEnvironment.configuration` which will return you the complete configuration map. Thus following access is for example possible (accessing `gitSshKeyCredentialsId` from `general` section): -``` + +```groovy commonPipelineEnvironment.configuration.general.gitSshKeyCredentialsId ``` @@ -78,6 +78,3 @@ commonPipelineEnvironment.configuration.general.gitSshKeyCredentialsId Within library steps the `ConfigurationHelper` object is used. You can see its usage in all the Piper steps, for example [newmanExecute](https://github.com/SAP/jenkins-library/blob/master/vars/newmanExecute.groovy#L23). - - - diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 44505c065..e2a04cea7 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -9,5 +9,4 @@ work. For information on the project and installation of the library, please have a look at our [README.md][piper-pipelines-readme]. - [piper-pipelines-readme]: https://github.com/SAP/jenkins-library/blob/master/README.md diff --git a/documentation/docs/jenkins/requiredPlugins.md b/documentation/docs/jenkins/requiredPlugins.md index 18be05b37..b7a6a5f1a 100644 --- a/documentation/docs/jenkins/requiredPlugins.md +++ b/documentation/docs/jenkins/requiredPlugins.md @@ -54,4 +54,3 @@ The list below contains the plugin Id and version of the plugin. - workflow-scm-step 2.6 - workflow-step-api 2.13 - workflow-support 2.16 - diff --git a/documentation/docs/steps/artifactSetVersion.md b/documentation/docs/steps/artifactSetVersion.md index cd053e888..f1b7e9c05 100644 --- a/documentation/docs/steps/artifactSetVersion.md +++ b/documentation/docs/steps/artifactSetVersion.md @@ -1,6 +1,7 @@ # artifactSetVersion ## Description + The continuous delivery process requires that each build is done with a unique version number. The version generated using this step will contain: @@ -15,6 +16,7 @@ Since you might not want to configure the git credentials in Jenkins, committing If you require strict reproducibility of your builds, this should be used. ## Prerequsites + none ## Parameters @@ -43,9 +45,9 @@ none * `commitVersion` controls if the changed version is committed and pushed to the git repository. If this is enabled (which is the default), you need to provide `gitCredentialsId` and `gitSshUrl`. * `dockerVersionSource` specifies the source to be used for the main version which is used for generating the automatic version. - * This can either be the version of the base image - as retrieved from the `FROM` statement within the Dockerfile, e.g. `FROM jenkins:2.46.2` - * Alternatively the name of an environment variable defined in the Docker image can be used which contains the version number, e.g. `ENV MY_VERSION 1.2.3` - * The third option `appVersion` applies only to the artifactType `appContainer`. Here the version of the app which is packaged into the container will be used as version for the container itself. + * This can either be the version of the base image - as retrieved from the `FROM` statement within the Dockerfile, e.g. `FROM jenkins:2.46.2` + * Alternatively the name of an environment variable defined in the Docker image can be used which contains the version number, e.g. `ENV MY_VERSION 1.2.3` + * The third option `appVersion` applies only to the artifactType `appContainer`. Here the version of the app which is packaged into the container will be used as version for the container itself. * Using `filePath` you could define a custom path to the descriptor file. * `gitCommitId` defines the version prefix of the automatically generated version. By default it will take the long commitId hash. You could pass any other string (e.g. the short commitId hash) to be used. In case you don't want to have the gitCommitId added to the automatic versioning string you could set the value to an empty string: `''`. @@ -56,6 +58,7 @@ none * `timestamp` defines the timestamp to be used in the automatic version string. You could overwrite the default behavior by explicitly setting this string. ## Step configuration + The following parameters can also be specified as step parameters using the global configuration file: * `artifactType` @@ -77,5 +80,3 @@ The following parameters can also be specified as step parameters using the glob ```groovy artifactSetVersion script: this, buildTool: 'maven' ``` - - diff --git a/documentation/docs/steps/batsExecuteTests.md b/documentation/docs/steps/batsExecuteTests.md index fe3545dad..505445dc6 100644 --- a/documentation/docs/steps/batsExecuteTests.md +++ b/documentation/docs/steps/batsExecuteTests.md @@ -26,7 +26,6 @@ You need to have a Bats test file. By default you would put this into directory | testPath | no | `src/test`| | | testRepository | no | | | - Details: * `outputFormat` defines the format of the test result output. `junit` would be the standard for automated build environments but you could use also the option `tap`. @@ -38,7 +37,8 @@ Details: With `envVars` it is possible to pass either fixed values but also templates using [`commonPipelineEnvironment`](commonPipelineEnvironment.md). Example: - ``` + + ```yaml batsExecuteTests script: this, envVars = [ FIX_VALUE: 'my fixed value', CONTAINER_NAME: '${commonPipelineEnvironment.configuration.steps.executeBatsTests.dockerContainerName}', @@ -53,6 +53,7 @@ Details: * The parameter `repository` defines the version of **bats-core** to be used. By default we use the version from the master branch. ## Step configuration + The following parameters can also be specified as step/stage/general parameters using the [global configuration](../configuration.md): * dockerImage @@ -68,7 +69,6 @@ The following parameters can also be specified as step/stage/general parameters * testPath * testRepository - ## Example ```groovy diff --git a/documentation/docs/steps/checkChangeInDevelopment.md b/documentation/docs/steps/checkChangeInDevelopment.md index f47bd79ee..a850cfa07 100644 --- a/documentation/docs/steps/checkChangeInDevelopment.md +++ b/documentation/docs/steps/checkChangeInDevelopment.md @@ -1,6 +1,7 @@ # checkChangeInDevelopment ## Description + 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. @@ -8,9 +9,11 @@ By default the git commit messages between `origin/master` and `HEAD` are scanne range and the pattern can be configured. For details see 'parameters' table. ## Prerequisites + * **[Change Management Client 2.0.0 or compatible version](http://central.maven.org/maven2/com/sap/devops/cmclient/dist.cli/)** - available for download on Maven Central. ## Parameters + | parameter | mandatory | default | possible values | | -------------------|-----------|--------------------------------------------------------|--------------------| | `script` | yes | | | @@ -34,15 +37,16 @@ range and the pattern can be configured. For details see 'parameters' table. * `failIfStatusIsNotInDevelopment` - when set to `false` the step will not fail in case the step is not in status 'in development'. ## Step configuration + The step is configured using a customer configuration file provided as resource in an custom shared library. -``` +```groovy @Library('piper-library-os@master') _ // the shared lib containing the additional configuration // needs to be configured in Jenkins -@Library(foo@master') __ +@Library('foo@master') __ // inside the shared lib denoted by 'foo' the additional configuration file // needs to be located under 'resources' ('resoures/myConfig.yml') @@ -50,10 +54,10 @@ prepareDefaultValues script: this, customDefaults: 'myConfig.yml' ``` -Example content of ```'resources/myConfig.yml'``` in branch ```'master'``` of the repository denoted by -```'foo'```: +Example content of `'resources/myConfig.yml'` in branch `'master'` of the repository denoted by +`'foo'`: -``` +```yaml general: changeManagement: changeDocumentLabel: 'ChangeDocument\s?:' @@ -70,7 +74,7 @@ The properties configured in section `'general/changeManagement'` are shared bet The properties can also be configured on a per-step basis: -``` +```yaml [...] steps: checkChangeInDevelopment: @@ -83,16 +87,20 @@ The properties can also be configured on a per-step basis: The parameters can also be provided when the step is invoked. For examples see below. ## Return value + `true` in case the change document is in status 'in development'. Otherwise an hudson.AbortException is thrown. In case `failIfStatusIsNotInDevelopment` is set to `false`, `false` is returned in case the change document is not in status 'in development' ## Exceptions + * `AbortException`: - * If the change id is not provided via parameter and if the change document id cannot be retrieved from the commit history. - * If the change is not in status `in development`. In this case no exception will be thrown when `failIfStatusIsNotInDevelopment` is set to `false`. + * If the change id is not provided via parameter and if the change document id cannot be retrieved from the commit history. + * If the change is not in status `in development`. In this case no exception will be thrown when `failIfStatusIsNotInDevelopment` is set to `false`. * `IllegalArgumentException`: - * If a mandatory property is not provided. + * If a mandatory property is not provided. + ## Examples + ```groovy // simple case. All mandatory parameters provided via // configuration, changeDocumentId provided via commit @@ -112,4 +120,3 @@ is set to `false`, `false` is returned in case the change document is not in sta ] ] ``` - diff --git a/documentation/docs/steps/checksPublishResults.md b/documentation/docs/steps/checksPublishResults.md index 3a1a308c4..ac9fea128 100644 --- a/documentation/docs/steps/checksPublishResults.md +++ b/documentation/docs/steps/checksPublishResults.md @@ -1,9 +1,11 @@ # checksPublishResults ## Description + This step can publish static check results from various sources. ## Prerequisites + * **static check result files** - To use this step, there must be static check result files available. * installed plugins: * [pmd](https://plugins.jenkins.io/pmd) @@ -14,6 +16,7 @@ This step can publish static check results from various sources. * [core](https://plugins.jenkins.io/core) ## Parameters + | parameter | mandatory | default | possible values | | ---------------|-----------|-----------------------------------|--------------------| | script | yes | | | @@ -38,13 +41,13 @@ This step can publish static check results from various sources. Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checkstyle`, `eslint` and `pylint` can be set to `true` or `false` but also to a map of parameters to hand in different settings for the tools. -**aggregation** +### aggregation | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| | thresholds | no | none | see [thresholds](#thresholds) | -**tasks** +### tasks | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -55,7 +58,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | low | no | | | | thresholds | no | none | see [thresholds](#thresholds) | -**pmd** +### pmd | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -63,7 +66,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | archive | no | `true` | `true`, `false` | | thresholds | no | none | see [thresholds](#thresholds) | -**cpd** +### cpd | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -71,7 +74,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | archive | no | `true` | `true`, `false` | | thresholds | no | none | see [thresholds](#thresholds) | -**findbugs** +### findbugs | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -79,7 +82,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | archive | no | `true` | true, false | | thresholds | no | none | see [thresholds](#thresholds) | -**checkstyle** +### checkstyle | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -87,7 +90,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | archive | no | `true` | `true`, `false` | | thresholds | no | none | see [thresholds](#thresholds) | -**eslint** +### eslint | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -95,7 +98,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | archive | no | `true` | `true`, `false` | | thresholds | no | none | see [thresholds](#thresholds) | -**pylint** +### pylint | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -104,6 +107,7 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | thresholds | no | none | see [thresholds](#thresholds) | ## Step configuration + Following parameters can also be specified as step parameters using the global configuration file: * `aggregation` @@ -141,15 +145,19 @@ checksPublishResults( ![StaticChecks Thresholds](../images/StaticChecks_Threshold.png) ## Return value + none ## Side effects + If both ESLint and PyLint results are published, they are not correctly aggregated in the aggregator plugin. ## Exceptions + none ## Example + ```groovy // publish java results from pmd, cpd, checkstyle & findbugs checksPublishResults archive: true, pmd: true, cpd: true, findbugs: true, checkstyle: true, aggregation: [thresholds: [fail: [high: 0]]] diff --git a/documentation/docs/steps/cloudFoundryDeploy.md b/documentation/docs/steps/cloudFoundryDeploy.md index c1cfaac72..78c0feb12 100644 --- a/documentation/docs/steps/cloudFoundryDeploy.md +++ b/documentation/docs/steps/cloudFoundryDeploy.md @@ -21,7 +21,6 @@ Deployment can be done ![Jenkins credentials configuration](../images/cf_credentials.png) - ## Parameters | parameter | mandatory | default | possible values | @@ -41,13 +40,12 @@ Deployment can be done * `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for retrieving e.g. configuration parameters. * `cloudFoundry` defines a map containing following properties: - - - `apiEndpoint`: Cloud Foundry API endpoint (default: `https://api.cf.eu10.hana.ondemand.com`) - - `appName`: App name of application to be deployed (optional) - - `credentialsId`: Credentials to be used for deployment (mandatory) - - `manifest`: Manifest to be used for deployment - - `org`: Cloud Foundry target organization (mandatory) - - `space`: Cloud Foundry target space (mandatory) + * `apiEndpoint`: Cloud Foundry API endpoint (default: `https://api.cf.eu10.hana.ondemand.com`) + * `appName`: App name of application to be deployed (optional) + * `credentialsId`: Credentials to be used for deployment (mandatory) + * `manifest`: Manifest to be used for deployment + * `org`: Cloud Foundry target organization (mandatory) + * `space`: Cloud Foundry target space (mandatory) Example: `cloudFoundry: [apiEndpoint: 'https://test.server.com', appName:'cfAppName', credentialsId: 'cfCredentialsId', manifest: 'cfManifest', org: 'cfOrg', space: 'cfSpace']` @@ -71,10 +69,10 @@ Deployment can be done * `smokeTestScript` allows to specify a script which performs a check during blue-green deployment. The script gets the FQDN as parameter and returns `exit code 0` in case check returned `smokeTestStatusCode`. More details can be found [here](https://github.com/bluemixgaragelondon/cf-blue-green-deploy#how-to-use)
Currently this option is only considered for deployTool `cf_native`. * `stashContent` defines the stash names which should be unstashed at the beginning of the step. This makes the files available in case the step is started on an empty node. -#### Option cf_native: +### Deployment with cf_native * `appName` in `cloudFoundry` map (or `cfAppName`) defines the name of the application which will be deployed to the Cloud Foundry space. -* `manifest in `cloudFoundry` map` (or `cfManifest`) defines the manifest to be used for Cloud Foundry deployment. +* `manifest` in `cloudFoundry` maps (or `cfManifest`) defines the manifest to be used for Cloud Foundry deployment. !!! note Cloud Foundry supports the deployment of multiple applications using a single manifest file. @@ -83,15 +81,14 @@ Deployment can be done In this case define `appName: ''` since the app name for the individual applications have to be defined via the manifest. You can find details in the [Cloud Foundry Documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html#multi-apps) - -#### MTA Deployment: +### Deployment with mtaDeployPlugin * `mtaPath` define path to *.mtar for deployment. * `mtaExtensionDescriptor` defines additional extension descriptor file for deployment. * `mtaDeployParameters` defines additional parameters passed to mta deployment. - ## Step configuration + The following parameters can also be specified as step/stage/general parameters using the [global configuration](../configuration.md): * cloudFoundry @@ -117,4 +114,3 @@ cloudFoundryDeploy( deployTool: 'cf_native' ) ``` - diff --git a/documentation/docs/steps/commonPipelineEnvironment.md b/documentation/docs/steps/commonPipelineEnvironment.md index 14ab7496b..57dd538ec 100644 --- a/documentation/docs/steps/commonPipelineEnvironment.md +++ b/documentation/docs/steps/commonPipelineEnvironment.md @@ -1,9 +1,11 @@ # commonPipelineEnvironment ## Description + Provides project specific settings. ## Prerequisites + none ## Method details @@ -11,21 +13,27 @@ none ### getArtifactVersion() #### Description + Returns the version of the artifact which is build in the pipeline. #### Parameters + none #### Return value + A `String` containing the version. #### Side effects + none #### Exceptions + none #### Example + ```groovy def myVersion = commonPipelineEnvironment.getArtifactVersion() ``` @@ -33,21 +41,27 @@ def myVersion = commonPipelineEnvironment.getArtifactVersion() ### setArtifactVersion(version) #### Description + Sets the version of the artifact which is build in the pipeline. #### Parameters + none #### Return value + none #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.setArtifactVersion('1.2.3') ``` @@ -55,92 +69,113 @@ commonPipelineEnvironment.setArtifactVersion('1.2.3') ### getConfigProperties() #### Description + Returns the map of project specific configuration properties. No defensive copy is created. Write operations to the map are visible further down in the pipeline. #### Parameters + none #### Return value + A map containing project specific configuration properties. #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.getConfigProperties() ``` - ### setConfigProperties(configuration) #### Description + Sets the map of configuration properties. Any existing map is overwritten. #### Parameters + * `configuration` - A map containing the new configuration #### Return value + none #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.setConfigProperties([DEPLOY_HOST: 'deploy-host.com', DEPLOY_ACCOUNT: 'deploy-account']) ``` - ### getConfigProperty(property) #### Description + Gets a specific value from the configuration property. #### Parameters + * `property` - The key of the property. #### Return value + * The value associated with key `property`. `null` is returned in case the property does not exist. #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.getConfigProperty('DEPLOY_HOST') ``` - ### setConfigProperty(property, value) #### Description + Sets property `property` with value `value`. Any existing property with key `property` is overwritten. #### Parameters + * `property` - The key of the property. * `value` - The value of the property. #### Return value + none #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.setConfigProperty('DEPLOY_HOST', 'my-deploy-host.com') ``` @@ -148,21 +183,27 @@ commonPipelineEnvironment.setConfigProperty('DEPLOY_HOST', 'my-deploy-host.com') ### getInfluxCustomData() #### Description + Returns the Influx custom data which can be collected during pipeline run. #### Parameters + none #### Return value + A `Map` containing the data collected. #### Side effects + none #### Exceptions + none #### Example + ```groovy def myInfluxData = commonPipelineEnvironment.getInfluxCustomData() ``` @@ -170,25 +211,30 @@ def myInfluxData = commonPipelineEnvironment.getInfluxCustomData() ### getInfluxCustomDataMap() #### Description + Returns the Influx custom data map which can be collected during pipeline run. It is used for example by step [`influxWriteData`](../steps/influxWriteData.md). The data map is a map of maps, like `[pipeline_data: [:], my_measurement: [:]]` Each map inside the map represents a dedicated measurement in the InfluxDB. - #### Parameters + none #### Return value + A `Map` containing a `Map`s with data collected. #### Side effects + none #### Exceptions + none #### Example + ```groovy def myInfluxDataMap = commonPipelineEnvironment.getInfluxCustomDataMap() ``` @@ -196,21 +242,27 @@ def myInfluxDataMap = commonPipelineEnvironment.getInfluxCustomDataMap() ### getMtarFileName() #### Description + Returns the path of the mtar archive file. #### Parameters + none #### Return value + The path of the mtar archive file. #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.getMtarFileName() ``` @@ -218,18 +270,23 @@ commonPipelineEnvironment.getMtarFileName() ### setMtarFileName(name) #### Description + Sets the path of the mtar archive file. Any old value is discarded. #### Parameters + * `mtarFilePath` - The path of the mtar archive file name. #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.setMtarFileName('path/to/foo.mtar') ``` @@ -237,22 +294,28 @@ commonPipelineEnvironment.setMtarFileName('path/to/foo.mtar') ### getPipelineMeasurement(measurementName) #### Description + Returns the value of a specific pipeline measurement. The measurements are collected with step [`durationMeasure`](../steps/durationMeasure.md) #### Parameters + Name of the measurement #### Return value + Value of the measurement #### Side effects + none #### Exceptions + none #### Example + ```groovy def myMeasurementValue = commonPipelineEnvironment.getPipelineMeasurement('build_stage_duration') ``` @@ -260,23 +323,29 @@ def myMeasurementValue = commonPipelineEnvironment.getPipelineMeasurement('build ### setPipelineMeasurement(measurementName, value) #### Description + **This is an internal function!** Sets the value of a specific pipeline measurement. Please use the step [`durationMeasure`](../steps/durationMeasure.md) in a pipeline, instead. #### Parameters + Name of the measurement and its value. #### Return value + none #### Side effects + none #### Exceptions + none #### Example + ```groovy commonPipelineEnvironment.setPipelineMeasurement('build_stage_duration', 2345) ``` diff --git a/documentation/docs/steps/dockerExecute.md b/documentation/docs/steps/dockerExecute.md index 5fc13837e..1a1529f3d 100644 --- a/documentation/docs/steps/dockerExecute.md +++ b/documentation/docs/steps/dockerExecute.md @@ -41,8 +41,8 @@ Proxy environment variables defined on the Jenkins machine are also available in * `sidecarVolumeBind`: as `dockerVolumeBind` for the sidecar container * `sidecarWorkspace`: as `dockerWorkspace` for the sidecar container - ## Kubernetes support + If the Jenkins is setup on a Kubernetes cluster, then you can execute the closure inside a container of a pod by setting an environment variable `ON_K8S` to `true`. However, it will ignore `containerPortMappings`, `dockerOptions` and `dockerVolumeBind` values. ## Step configuration @@ -69,14 +69,16 @@ In following sections the configuration is possible: |sidecarVolumeBind||X|X| |sidecarWorkspace||X|X| - ## Return value + none ## Side effects + none ## Exceptions + none ## Example 1: Run closure inside a docker container @@ -86,6 +88,7 @@ dockerExecute(dockerImage: 'maven:3.5-jdk-7'){ sh "mvn clean install" } ``` + ## Example 2: Run closure inside a container in a kubernetes pod ```sh @@ -101,7 +104,7 @@ dockerExecute(script: this, dockerImage: 'maven:3.5-jdk-7'){ In the above example, the `dockerEcecute` step will internally invoke [dockerExecuteOnKubernetes](dockerExecuteOnKubernetes.md) step and execute the closure inside a pod. -## Example 3: Run closure inside a container which is attached to a sidecar container (as for example used in [seleniumExecuteTests](seleniumExecuteTests.md): +## Example 3: Run closure inside a container which is attached to a sidecar container (as for example used in [seleniumExecuteTests](seleniumExecuteTests.md) ```groovy dockerExecute( @@ -119,7 +122,3 @@ dockerExecute( ''' } ``` - - - - diff --git a/documentation/docs/steps/dockerExecuteOnKubernetes.md b/documentation/docs/steps/dockerExecuteOnKubernetes.md index ac4b3babf..9e0dbce92 100644 --- a/documentation/docs/steps/dockerExecuteOnKubernetes.md +++ b/documentation/docs/steps/dockerExecuteOnKubernetes.md @@ -5,6 +5,7 @@ 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 + * The Jenkins should be running on kubernetes. * An environment variable `ON_K8S` should be created on Jenkins and initialized to `true`. This could for example be done via _Jenkins_ - _Manage Jenkins_ - _Configure System_ - _Global properties_ - _Environment variables_ @@ -64,15 +65,19 @@ In following sections the configuration is possible: |stashIncludes||X|X| ## Return value + none ## Side effects + none ## Exceptions + none ## Example 1: Run a closure in a single container pod + ```sh # set environment variable export ON_K8S=true" @@ -87,6 +92,7 @@ dockerExecuteOnKubernetes(script: script, dockerImage: 'maven:3.5-jdk-7'){ In the above example, a pod will be created with a docker container of image `maven:3.5-jdk-7`. The closure will be then executed inside the container. ## Example 2: Run a closure in a multi-container pod + ```sh # set environment variable export ON_K8S=true" diff --git a/documentation/docs/steps/durationMeasure.md b/documentation/docs/steps/durationMeasure.md index e24ba7972..3145b114c 100644 --- a/documentation/docs/steps/durationMeasure.md +++ b/documentation/docs/steps/durationMeasure.md @@ -1,6 +1,7 @@ # durationMeasure ## Description + This step is used to measure the duration of a set of steps, e.g. a certain stage. The duration is stored in a Map. The measurement data can then be written to an Influx database using step [influxWriteData](influxWriteData.md). @@ -9,9 +10,11 @@ The duration is stored in a Map. The measurement data can then be written to an This then helps to counter identified issues with respective optimization measures, e.g parallelization of tests. ## Prerequisites + none ## Pipeline configuration + none ## Parameters @@ -27,6 +30,7 @@ Details: * `measurementName` defines the name of the measurement which is written to the Influx database. ## Step configuration + none ## Example diff --git a/documentation/docs/steps/gaugeExecuteTests.md b/documentation/docs/steps/gaugeExecuteTests.md index ba240a62f..53403e966 100644 --- a/documentation/docs/steps/gaugeExecuteTests.md +++ b/documentation/docs/steps/gaugeExecuteTests.md @@ -1,8 +1,10 @@ # gaugeExecuteTests ## Description + In this step Gauge ([getgauge.io](http:getgauge.io)) acceptance tests are executed. Using Gauge it will be possible to have a three-tier test layout: + * Acceptance Criteria * Test implemenation layer * Application driver layer @@ -11,7 +13,7 @@ This layout is propagated by Jez Humble and Dave Farley in their book "Continuou Using Gauge it is possible to write test specifications in [Markdown syntax](http://daringfireball.net/projects/markdown/syntax) and therefore allow e.g. product owners to write the relevant acceptance test specifications. At the same time it allows the developer to implement the steps described in the specification in her development environment. -You can use the sample projects of Gauge, for example: https://github.com/getgauge/gauge-mvn-archetypes +You can use the [sample projects](https://github.com/getgauge/gauge-mvn-archetypes) of Gauge. !!! note "Make sure to run against a Selenium Hub configuration" In the test example of _gauge-archetype-selenium_ please make sure to allow it to run against a Selenium hub: @@ -35,11 +37,11 @@ none ## Example Pipeline step: + ```groovy gaugeExecuteTests script: this, testServerUrl: 'http://test.url' ``` - ## Parameters | parameter | mandatory | default | possible values | @@ -49,7 +51,7 @@ gaugeExecuteTests script: this, testServerUrl: 'http://test.url' |dockerEnvVars|no|`[HUB:TRUE, HUB_URL:http://localhost:4444/wd/hub]`|| |dockerImage|no|buildTool=`maven`: `maven:3.5-jdk-8`
buildTool=`npm`: `node:8-stretch`
|| |dockerName|no|buildTool=`maven`: `maven`
buildTool=`npm`: `npm`
|| -|dockerWorkspace|no|buildTool=`maven`: ``
buildTool=`npm`: `/home/node`
|| +|dockerWorkspace|no|buildTool=`maven`:
buildTool=`npm`: `/home/node`
|| |failOnError|no|`false`|| |gitBranch|no||| |gitSshKeyCredentialsId|no|``|| @@ -61,7 +63,6 @@ gaugeExecuteTests script: this, testServerUrl: 'http://test.url' |testRepository|no||| |testServerUrl|no||| - Details: * `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. diff --git a/documentation/docs/steps/githubPublishRelease.md b/documentation/docs/steps/githubPublishRelease.md index 5a18a4f5a..9bdcf5fa2 100644 --- a/documentation/docs/steps/githubPublishRelease.md +++ b/documentation/docs/steps/githubPublishRelease.md @@ -1,6 +1,7 @@ # githubPublishRelease ## Description + This step creates a tag in your GitHub repository together with a release. The release can be filled with text plus additional information like: @@ -14,6 +15,7 @@ The result looks like ![Example release](../images/githubRelease.png) ## Prerequisites + You need to create a personal access token within GitHub and add this to the Jenkins credentials store. Please see [GitHub documentation for details about creating the personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). diff --git a/documentation/docs/steps/handlePipelineStepErrors.md b/documentation/docs/steps/handlePipelineStepErrors.md index 320a18c60..67bea9c07 100644 --- a/documentation/docs/steps/handlePipelineStepErrors.md +++ b/documentation/docs/steps/handlePipelineStepErrors.md @@ -1,12 +1,15 @@ # handlePipelineStepErrors ## Description + Used by other steps to make error analysis easier. Lists parameters and other data available to the step in which the error occurs. ## Prerequisites + none ## Parameters + | parameter | mandatory | default | possible values | | -----------------|-----------|---------|-----------------| | `stepParameters` | yes | | | @@ -18,8 +21,9 @@ none * `echoDetails` - If set to true the following will be output to the console: 1. Step beginning: `--- BEGIN LIBRARY STEP: ${stepName}.groovy ---` 2. Step end: `--- END LIBRARY STEP: ${stepName}.groovy ---` - 3. Step errors: - ``` + 3. Step errors: + + ```log ---------------------------------------------------------- --- ERROR OCCURED IN LIBRARY STEP: ${stepName} ---------------------------------------------------------- @@ -39,18 +43,23 @@ none ``` ## Step configuration + none ## Return value + none ## Side effects + none ## Exceptions + none ## Example + ```groovy handlePipelineStepErrors (stepName: 'executeHealthCheck', stepParameters: parameters) { def url = new Utils().getMandatoryParameter(parameters, 'url', null) diff --git a/documentation/docs/steps/healthExecuteCheck.md b/documentation/docs/steps/healthExecuteCheck.md index ca0cf1c08..6d140c3da 100644 --- a/documentation/docs/steps/healthExecuteCheck.md +++ b/documentation/docs/steps/healthExecuteCheck.md @@ -1,6 +1,7 @@ # healthExecuteCheck ## Description + Calls the health endpoint url of the application. The intention of the check is to verify that a suitable health endpoint is available. Such a health endpoint is required for operation purposes. @@ -14,8 +15,6 @@ This check is used as a real-life test for your productive health endpoints. This is in line with health check capabilities of platforms which are used for example in load balancing scenarios. Here you can find an [example for Amazon AWS](http://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-healthchecks.html). - - ## Prerequisites Endpoint for health check is configured. @@ -26,7 +25,6 @@ Endpoint for health check is configured. !!! tip If using Spring Boot framework, ideally the provided `/health` endpoint is used and extended by development. Further information can be found in the [Spring Boot documenation for Endpoints](http://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html) - ## Example Pipeline step: @@ -43,8 +41,8 @@ healthExecuteCheck testServerUrl: 'https://testserver.com' |healthEndpoint|no|``|| |testServerUrl|no||| - Details: + * `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. * Health check function is called providing full qualified `testServerUrl` (and optionally with `healthEndpoint` if endpoint is not the standard url) to the health check. * In case response of the call is different than `HTTP 200 OK` the **health check fails and the pipeline stops**. diff --git a/documentation/docs/steps/influxWriteData.md b/documentation/docs/steps/influxWriteData.md index 674ff7b97..a61a35243 100644 --- a/documentation/docs/steps/influxWriteData.md +++ b/documentation/docs/steps/influxWriteData.md @@ -1,6 +1,7 @@ # influxWriteData ## Description + Since your Continuous Delivery Pipeline in Jenkins provides your productive development and delivery infrastructure you should monitor the pipeline to ensure it runs as expected. How to setup this monitoring is described in the following. You basically need three components: @@ -33,7 +34,6 @@ For more advanced setup please reach out to the respective documentation: - https://hub.docker.com/_/influxdb/ (and https://github.com/docker-library/docs/tree/master/influxdb) - https://hub.docker.com/r/grafana/grafana/ (and https://github.com/grafana/grafana-docker) - After you have started your InfluxDB docker you need to create a database: - in a Webbrowser open the InfluxDB Web-UI using the following URL: <host of your docker>:8083 (port 8083 is used for access via Web-UI, for Jenkins you use port 8086 to access the DB) @@ -42,16 +42,15 @@ After you have started your InfluxDB docker you need to create a database: !!! hint "With InfluxDB version 1.1 the InfluxDB Web-UI is deprecated" - You can perform the above steps via commandline: - - The following command will create a database with name <databasename> +- The following command will create a database with name <databasename> - `curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE DATABASE \"` + `curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE DATABASE \"` - - The admin user with the name <adminusername> and the password <adminuserpwd> can be created with +- The admin user with the name <adminusername> and the password <adminuserpwd> can be created with - `curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE USER \ WITH PASSWORD '\' WITH ALL PRIVILEGES"` + `curl -i -XPOST http://localhost:8086/query --data-urlencode "q=CREATE USER \ WITH PASSWORD '\' WITH ALL PRIVILEGES"` Once you have started both docker containers and Influx and Grafana are running you need to configure the Jenkins Plugin according to your settings. @@ -66,8 +65,8 @@ To setup your Jenkins you need to do two configuration steps: Once the plugin is available in your Jenkins: -* go to "Manage Jenkins" > "Configure System" > scroll down to section "influxdb target" -* maintain Influx data +- go to "Manage Jenkins" > "Configure System" > scroll down to section "influxdb target" +- maintain Influx data !!! note "Jenkins as a Service" For Jenkins as a Service instances this is already preset to the local InfluxDB with the name `jenkins`. In this case there is not need to do any additional configuration. @@ -90,10 +89,11 @@ influxDBServer=jenkins | influxPrefix | no | `null` | | ## Step configuration + The following parameters can also be specified as step parameters using the global configuration file: -* `influxServer` -* `influxPrefix` +- `influxServer` +- `influxPrefix` ## Example @@ -107,28 +107,28 @@ You can access your **Grafana** via Web-UI: <host of your grafana(-docker)> (or another port in case you have defined another one when starting your docker) As a first step you need to add your InfluxDB as Data source to your Grafana: + - Login as user admin (PW as defined when starting your docker) - in the navigation go to data sources -> add data source: - name - type: InfluxDB - - Url: \http://<host of your InfluxDB server>:<port> + - Url: `http://:` - Access: direct (not via proxy) - - database: <name of the DB as specified above> - - User: <name of the admin user as specified in step above> - - Password: <password of the admin user as specified in step above> + - database: `` + - User: `` + - Password: `` !!! note "Jenkins as a Service" For Jenkins as a Service the data source configuration is already available. Therefore no need to go through the data source configuration step unless you want to add addtional data sources. - ## Data collected in InfluxDB The Influx plugin collects following data in the Piper context: -* All data as per default [InfluxDB plugin capabilities](https://wiki.jenkins.io/display/JENKINS/InfluxDB+Plugin) -* Additional data collected via `commonPipelineEnvironment.setInfluxCustomDataProperty()` and via `commonPipelineEnvironment.setPipelineMeasurement()` +- All data as per default [InfluxDB plugin capabilities](https://wiki.jenkins.io/display/JENKINS/InfluxDB+Plugin) +- Additional data collected via `commonPipelineEnvironment.setInfluxCustomDataProperty()` and via `commonPipelineEnvironment.setPipelineMeasurement()` !!! note "Add custom information to your InfluxDB" You can simply add custom data collected during your pipeline runs via available data objects. @@ -140,6 +140,7 @@ The Influx plugin collects following data in the Piper context: ``` ### Collected InfluxDB measurements + Measurements are potentially pre-fixed - see parameter `influxPrefix` above. | Measurement name | data column | description | @@ -154,7 +155,6 @@ Measurements are potentially pre-fixed - see parameter `influxPrefix` above. | pipeline_data | Examples from the Piper templates:
  • build_duration
  • opa_duration
  • deploy_test_duration
  • deploy_test_duration
  • fortify_duration
  • release_duration
  • ...
| filled by step [`measureDuration`](durationMeasure.md) using parameter `measurementName`| | step_data | Considered, e.g.:
  • build_quality (Milestone/Release)
  • build_url
  • bats
  • checkmarx
  • fortify
  • gauge
  • nsp
  • opa
  • opensourcedependency
  • ppms
  • jmeter
  • supa
  • snyk
  • sonar
  • sourceclear
  • uiveri5
  • vulas
  • whitesource
  • traceability
  • ...
  • xmakestage
  • xmakepromote
| filled by `commonPipelineEnvironment.setInfluxStepData()` | - ### Examples for InfluxDB queries which can be used in Grafana !!! caution "Project Names containing dashes (-)" @@ -162,29 +162,27 @@ Measurements are potentially pre-fixed - see parameter `influxPrefix` above. Please keep this in mind when specifying your project_name for a InfluxDB query. - #### Example 1: Select last 10 successful builds -``` +```sql select top(build_number,10), build_result from jenkins_data WHERE build_result = 'SUCCESS' ``` #### Example 2: Select last 10 step names of failed builds - -``` +```sql select top(build_number,10), build_result, build_step from jenkins_custom_data WHERE build_result = 'FAILURE' ``` #### Example 3: Select build duration of step for a specific project -``` +```sql select build_duration / 1000 from "pipeline_data" WHERE project_name='PiperTestOrg_piper_test_master' ``` #### Example 4: Get transparency about successful/failed steps for a specific project -``` +```sql select top(build_number,10) AS "Build", build_url, build_quality, fortify, gauge, vulas, opa from step_data WHERE project_name='PiperTestOrg_piper_test_master' ``` @@ -192,6 +190,3 @@ select top(build_number,10) AS "Build", build_url, build_quality, fortify, gauge With this query you can create transparency about which steps ran successfully / not successfully in your pipeline and which ones were not executed at all. By specifying all the steps you consider relevant in your select statement it is very easy to create this transparency. - - - diff --git a/documentation/docs/steps/mailSendNotification.md b/documentation/docs/steps/mailSendNotification.md index fce498dbd..6c7a2650c 100644 --- a/documentation/docs/steps/mailSendNotification.md +++ b/documentation/docs/steps/mailSendNotification.md @@ -1,6 +1,7 @@ # mailSendNotification ## Description + Sends notifications to all potential culprits of a current or previous build failure plus to fixed list of recipients. It will attach the current build log to the email. @@ -10,6 +11,7 @@ Notifications are sent in following cases: * current build is successful and previous build failed or was unstable ## Prerequsites + none ## Example @@ -20,7 +22,6 @@ Usage of pipeline step: mailSendNotification script: this ``` - ## Parameters | parameter | mandatory | default | possible values | @@ -37,7 +38,7 @@ mailSendNotification script: this |projectName|no||| |wrapInNode|no|`false`|| -### Details: +### Details * `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. * `buildResult` may be used to overrule the build result coming from `currentBuild.result`. This is for example used in the step `pipelineRestartSteps` @@ -56,7 +57,6 @@ mailSendNotification script: this * `projectName` may be used to specify a different name in the email subject. * `wrapInNode` needs to be set to `true` if step is used outside of a node context, e.g. post actions in a declarative pipeline script. - ## Step configuration We recommend to define values of step parameters via [config.yml file](../configuration.md). @@ -78,19 +78,13 @@ In following sections the configuration is possible: |wrapInNode||X|X| ## Return value + none ## Side effects + none ## Exceptions + none - - - - - - - - - diff --git a/documentation/docs/steps/mavenExecute.md b/documentation/docs/steps/mavenExecute.md index d55ba61f1..47400bbc3 100644 --- a/documentation/docs/steps/mavenExecute.md +++ b/documentation/docs/steps/mavenExecute.md @@ -24,7 +24,7 @@ Executes a maven command inside a Docker container. to access the commonPipelineEnvironment for retrieving, for example, configuration parameters. * `dockerImage` Name of the docker image that should be used. -* `globalSettingsFile` Path or url to the mvn settings file that should be used as global settings file. +* `globalSettingsFile` Path or url to the mvn settings file that should be used as global settings file. * `projectSettingsFile` Path or url to the mvn settings file that should be used as project settings file. * `pomPath` Path to the pom file that should be used. * `flags` Flags to provide when running mvn. @@ -34,6 +34,7 @@ Executes a maven command inside a Docker container. * `logSuccessfulMavenTransfers` configures maven to log successful downloads. This is set to `false` by default to reduce the noise in build logs. ## Step configuration + The following parameters can also be specified as step parameters using the global configuration file: * `dockerImage` @@ -51,7 +52,3 @@ None ```groovy mavenExecute script: this, goals: 'clean install' ``` - - - - diff --git a/documentation/docs/steps/mtaBuild.md b/documentation/docs/steps/mtaBuild.md index 58da03080..206ee3ff6 100644 --- a/documentation/docs/steps/mtaBuild.md +++ b/documentation/docs/steps/mtaBuild.md @@ -1,6 +1,7 @@ # mtaBuild ## Description + Executes the SAP Multitarget Application Archive Builder to create an mtar archive of the application. Before doing this, validates that SAP Multitarget Application Archive Builder exists and the version is compatible. @@ -8,12 +9,14 @@ Before doing this, validates that SAP Multitarget Application Archive Builder ex Note that a version is formed by `major.minor.patch`, and a version is compatible to another version if the minor and patch versions are higher, but the major version is not, e.g. if 3.39.10 is the expected version, 3.39.11 and 3.40.1 would be compatible versions, but 4.0.1 would not be a compatible version. ## Prerequisites + * A docker image meeting the following requirements - * **SAP MTA Archive Builder 1.0.6 or compatible version** - can be downloaded from [SAP Development Tools](https://tools.hana.ondemand.com/#cloud). - * **Java 8 or compatible version** - necessary to run the `mta.jar` file. - * **NodeJS installed** - the MTA Builder uses `npm` to download node module dependencies such as `grunt`. + * **SAP MTA Archive Builder 1.0.6 or compatible version** - can be downloaded from [SAP Development Tools](https://tools.hana.ondemand.com/#cloud). + * **Java 8 or compatible version** - necessary to run the `mta.jar` file. + * **NodeJS installed** - the MTA Builder uses `npm` to download node module dependencies such as `grunt`. ## Parameters + | parameter | mandatory | default | possible values | | -----------------|-----------|--------------------------------------------------------|--------------------| | `script` | yes | | | @@ -31,11 +34,12 @@ Note that a version is formed by `major.minor.patch`, and a version is compatibl * `dockerOptions` Docker options to be set when starting the container. It can be a list or a string. * `buildTarget` - The target platform to which the mtar can be deployed. * `extension` - The path to the extension descriptor file. -* `mtaJarLocation` - The location of the SAP Multitarget Application Archive Builder jar file, including file name and extension. First, the location is retrieved from the environment variables using the environment variable`MTA_JAR_LOCATION`. If no environment variable is provided, the location is retrieved from the parameters, or the step configuration using the key `mtaJarLocation`. If SAP Multitarget Application Archive Builder is not found on one of the previous locations an AbortException is thrown. -Note that the environment variable `MTA_JAR_LOCATION` has priority. In case that the script runs on multiple nodes, SAP Multitarget Application Archive Builder must be located on all the nodes, therefore the environment variable must be also configured on all the nodes. +* `mtaJarLocation` - The location of the SAP Multitarget Application Archive Builder jar file, including file name and extension. First, the location is retrieved from the environment variables using the environment variable `MTA_JAR_LOCATION`. If no environment variable is provided, the location is retrieved from the parameters, or the step configuration using the key `mtaJarLocation`. If SAP Multitarget Application Archive Builder is not found on one of the previous locations an AbortException is thrown. + Note that the environment variable `MTA_JAR_LOCATION` has priority. In case that the script runs on multiple nodes, SAP Multitarget Application Archive Builder must be located on all the nodes, therefore the environment variable must be also configured on all the nodes. * `applicationName` - The name of the application which is being built. If the parameter has been provided and no `mta.yaml` exists, the `mta.yaml` will be automatically generated using this parameter and the information (`name` and `version`) from `package.json` before the actual build starts. ## Step configuration + The following parameters can also be specified as step parameters using the global configuration file: * `dockerImage` @@ -45,22 +49,25 @@ The following parameters can also be specified as step parameters using the glob * `applicationName` ## Return value + none ## Side effects + 1. The file name of the resulting archive is written to the `commonPipelineEnvironment` with variable name `mtarFileName`. ## Exceptions + * `AbortException`: - * If SAP Multitarget Application Archive Builder is not found. - * If there is an invalid `buildTarget`. - * If there is no key `ID` inside the `mta.yaml` file. + * If SAP Multitarget Application Archive Builder is not found. + * If there is an invalid `buildTarget`. + * If there is no key `ID` inside the `mta.yaml` file. ## Example + ```groovy def mtarFileName dir('/path/to/FioriApp'){ mtarFileName = mtaBuild script:this, buildTarget: 'NEO' } ``` - diff --git a/documentation/docs/steps/neoDeploy.md b/documentation/docs/steps/neoDeploy.md index 75ccf15be..3dd37032c 100644 --- a/documentation/docs/steps/neoDeploy.md +++ b/documentation/docs/steps/neoDeploy.md @@ -1,6 +1,7 @@ # neoDeploy ## Description + Deploys an Application to SAP Cloud Platform (SAP CP) using the SAP Cloud Platform Console Client (Neo Java Web SDK). Before doing this, validates that SAP Cloud Platform Console Client is installed and the version is compatible. @@ -8,19 +9,19 @@ Before doing this, validates that SAP Cloud Platform Console Client is installed Note that a version is formed by `major.minor.patch`, and a version is compatible to another version if the minor and patch versions are higher, but the major version is not, e.g. if 3.39.10 is the expected version, 3.39.11 and 3.40.1 would be compatible versions, but 4.0.1 would not be a compatible version. ## Prerequisites + * **SAP CP account** - the account to where the application is deployed. * **SAP CP user for deployment** - a user with deployment permissions in the given account. * **Jenkins credentials for deployment** - must be configured in Jenkins credentials with a dedicated Id. ![Jenkins credentials configuration](../images/neo_credentials.png) -* **Neo Java Web SDK 3.39.10 or compatible version** - can be downloaded from [Maven Central](http://central.maven.org/maven2/com/sap/cloud/neo-java-web-sdk/). The Neo Java Web SDK -needs to be extracted into the folder provided by `neoHome`. In case this parameters is not provided and there is no NEO_HOME parameter in the environment -`/tools` needs to be in the `PATH`. This step is also capable of triggering the neo deploy tool provided inside a docker image. +* **Neo Java Web SDK 3.39.10 or compatible version** - can be downloaded from [Maven Central](http://central.maven.org/maven2/com/sap/cloud/neo-java-web-sdk/). The Neo Java Web SDK needs to be extracted into the folder provided by `neoHome`. In case this parameters is not provided and there is no NEO_HOME parameter in the environment `/tools` needs to be in the `PATH`. This step is also capable of triggering the neo deploy tool provided inside a docker image. * **Java 8 or compatible version** - needed by the *Neo-Java-Web-SDK* ## Parameters when using MTA deployment method (default - MTA) + | parameter | mandatory | default | possible values | | -------------------|-----------|-------------------------------|-------------------------------------------------| | `account` | no | | | @@ -34,6 +35,7 @@ needs to be extracted into the folder provided by `neoHome`. In case this parame | `script` | yes | | | ## Parameters when using WAR file deployment method with .properties file (WAR_PROPERTIESFILE) + | parameter | mandatory | default | possible values | | -------------------|-----------|-------------------------------|-------------------------------------------------| | `archivePath` | no | | | @@ -45,6 +47,7 @@ needs to be extracted into the folder provided by `neoHome`. In case this parame | `warAction` | yes | `'deploy'` | `'deploy'`, `'rolling-update'` | ## Parameters when using WAR file deployment method witout .properties file - with parameters (WAR_PARAMS) + | parameter | mandatory | default | possible values | | -------------------|-----------|-------------------------------|-------------------------------------------------| | `account` | no | | | @@ -62,7 +65,6 @@ needs to be extracted into the folder provided by `neoHome`. In case this parame | `vmSize` | no | `'lite'` | `'lite'`, `'pro'`, `'prem'`, `'prem-plus'` | | `warAction` | yes | `'deploy'` | `'deploy'`, `'rolling-update'` | - * `account` - The SAP Cloud Platform account to deploy to. * `applicationName` - Name of the application you want to manage, configure, or deploy * `archivePath`- The path to the archive for deployment to SAP CP. If not provided `mtarFilePath` from commom pipeline environment is used instead. @@ -82,6 +84,7 @@ needs to be extracted into the folder provided by `neoHome`. In case this parame The step is prepared for being executed in docker. The corresponding parameters can be applied. See step `dockerExecute` for details. ## Step configuration + The following parameters can also be specified as step parameters using the global configuration file: * `account` @@ -93,33 +96,37 @@ The following parameters can also be specified as step parameters using the glob * `neoHome` ## Return value + none ## Side effects + none ## Exceptions + * `Exception`: - * If `archivePath` is not provided. - * If `propertiesFile` is not provided (when using `'WAR_PROPERTIESFILE'` deployment mode). - * If `applicationName` is not provided (when using `'WAR_PARAMS'` deployment mode). - * If `runtime` is not provided (when using `'WAR_PARAMS'` deployment mode). - * If `runtime-version` is not provided (when using `'WAR_PARAMS'` deployment mode). + * If `archivePath` is not provided. + * If `propertiesFile` is not provided (when using `'WAR_PROPERTIESFILE'` deployment mode). + * If `applicationName` is not provided (when using `'WAR_PARAMS'` deployment mode). + * If `runtime` is not provided (when using `'WAR_PARAMS'` deployment mode). + * If `runtime-version` is not provided (when using `'WAR_PARAMS'` deployment mode). * `AbortException`: - * If neo-java-web-sdk is not installed, or `neoHome`is wrong. - * If `deployHost` is wrong. - * If `deployAccount` is wrong. + * If neo-java-web-sdk is not installed, or `neoHome`is wrong. + * If `deployHost` is wrong. + * If `deployAccount` is wrong. * `CredentialNotFoundException`: - * If the credentials cannot be resolved. + * If the credentials cannot be resolved. ## Example + ```groovy neoDeploy script: this, archivePath: 'path/to/archiveFile.mtar', credentialsId: 'my-credentials-id' ``` Example configuration: -``` +```yaml steps: <...> neoDeploy: diff --git a/documentation/docs/steps/pipelineExecute.md b/documentation/docs/steps/pipelineExecute.md index d580f26d5..5aabc3129 100644 --- a/documentation/docs/steps/pipelineExecute.md +++ b/documentation/docs/steps/pipelineExecute.md @@ -1,6 +1,7 @@ # pipelineExecute ## Description + Loads a pipeline from a git repository. The idea is to set up a pipeline job in Jenkins that loads a minimal pipeline, which in turn loads the shared library and then uses this step to load the actual pipeline. A centrally maintained pipeline script (Jenkinsfile) can be re-used by @@ -40,7 +41,7 @@ none ## Exceptions * `Exception` - * If `repoUrl` is not provided. + * If `repoUrl` is not provided. ## Example diff --git a/documentation/docs/steps/pipelineRestartSteps.md b/documentation/docs/steps/pipelineRestartSteps.md index 20093ce24..8a13ed6eb 100644 --- a/documentation/docs/steps/pipelineRestartSteps.md +++ b/documentation/docs/steps/pipelineRestartSteps.md @@ -1,6 +1,7 @@ # pipelineRestartSteps ## Description + Support of restarting failed stages or steps in a pipeline is limited in Jenkins. This has been documented in the [Jenkins Jira issue JENKINS-33846](https://issues.jenkins-ci.org/browse/JENKINS-33846). @@ -16,8 +17,8 @@ The step `pipelineRestartSteps` aims to address this gap and allows individual p This is done in a way that the pipeline waits for user input to restart the pipeline in case of a failure. In case this user input is not provided the pipeline stops after a timeout which can be configured. ## Prerequisites -none +none ## Example @@ -36,7 +37,6 @@ pipelineRestartSteps (script: this) { In case you cannot use `node` inside this step, please choose the parameter `timeoutInSeconds` carefully! - ## Parameters | parameter | mandatory | default | possible values | @@ -45,13 +45,12 @@ pipelineRestartSteps (script: this) { |sendMail|no|`true`|| |timeoutInSeconds|no|`900`|| -### Details: +### Details * `script` defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. * If `sendMail: true` the step `mailSendNotification` will be triggered in case of an error * `timeoutInSeconds` defines the time period where the job waits for input. Default is 15 minutes. Once this time is passed the job enters state FAILED. - ## Step configuration We recommend to define values of step parameters via [config.yml file](../configuration.md). @@ -65,11 +64,13 @@ In following sections the configuration is possible: |timeoutInSeconds|X|X|X| ## Return value + none ## Side effects + none ## Exceptions -none +none diff --git a/documentation/docs/steps/pipelineStashFiles.md b/documentation/docs/steps/pipelineStashFiles.md index ff8b7fe68..1fa86164a 100644 --- a/documentation/docs/steps/pipelineStashFiles.md +++ b/documentation/docs/steps/pipelineStashFiles.md @@ -1,9 +1,11 @@ # pipelineStashFiles ## Description + This step stashes files that are needed in other build steps (on other nodes). ## Prerequsites + none ## Parameters @@ -41,6 +43,7 @@ The step is stashing files before and after the build. This is due to the fact, * `stashExcludes: [tests: '**/NOTRELEVANT.*]` ## Step configuration + The following parameters can also be specified as step parameters using the global configuration file: * runOpaTests @@ -48,7 +51,6 @@ The following parameters can also be specified as step parameters using the glob * stashExcludes * stashIncludes - ## Explanation of pipeline step Usage of pipeline step: @@ -58,5 +60,3 @@ pipelineStashFiles script: this { mavenExecute script: this, ... } ``` - - diff --git a/documentation/docs/steps/prepareDefaultValues.md b/documentation/docs/steps/prepareDefaultValues.md index 58e61c725..208d4c385 100644 --- a/documentation/docs/steps/prepareDefaultValues.md +++ b/documentation/docs/steps/prepareDefaultValues.md @@ -3,7 +3,7 @@ ## Description Loads the pipeline library default values from the file `resources/default_pipeline_environment.yml`. -Afterwards the values can be loaded by the method: `ConfigurationLoader.defaultStepConfiguration` +Afterwards the values can be loaded by the method: `ConfigurationLoader.defaultStepConfiguration` ## Parameters @@ -22,7 +22,3 @@ None ```groovy prepareDefaultValues() ``` - - - - diff --git a/documentation/docs/steps/seleniumExecuteTests.md b/documentation/docs/steps/seleniumExecuteTests.md index a575ec547..5a92d737a 100644 --- a/documentation/docs/steps/seleniumExecuteTests.md +++ b/documentation/docs/steps/seleniumExecuteTests.md @@ -7,6 +7,7 @@ Enables UI test execution with Selenium in a sidecar container. The step executes a closure (see example below) connecting to a sidecar container with a Selenium Server. When executing in a + * local Docker environment, please make sure to set Selenium host to **`selenium`** in your tests. * Kubernetes environment, plese make sure to set Seleniums host to **`localhost`** in your tests. @@ -32,7 +33,8 @@ seleniumExecuteTests (script: this) { Example based on http://webdriver.io/guide/getstarted/modes.html and http://webdriver.io/guide.html #### Configuration for Local Docker Environment -``` + +```js var webdriverio = require('webdriverio'); var options = { host: 'selenium', @@ -42,8 +44,10 @@ var options = { } }; ``` + #### Configuration for Kubernetes Environment -``` + +```js var webdriverio = require('webdriverio'); var options = { host: 'localhost', @@ -56,7 +60,7 @@ var options = { #### Test Code (index.js) -``` +```js // ToDo: add configuration from above webdriverio @@ -82,7 +86,7 @@ webdriverio |dockerEnvVars|no||| |dockerImage|no|buildTool=`maven`: `maven:3.5-jdk-8`
buildTool=`npm`: `node:8-stretch`
|| |dockerName|no|buildTool=`maven`: `maven`
buildTool=`npm`: `npm`
|| -|dockerWorkspace|no|buildTool=`maven`: ``
buildTool=`npm`: `/home/node`
|| +|dockerWorkspace|no|buildTool=`maven`:
buildTool=`npm`: `/home/node`
|| |failOnError|no|`true`|| |gitBranch|no||| |gitSshKeyCredentialsId|no|``|| @@ -134,10 +138,13 @@ In following sections the configuration is possible: |testRepository|X|X|X| ## Return value + none ## Side effects + none ## Exceptions + none diff --git a/documentation/docs/steps/setupCommonPipelineEnvironment.md b/documentation/docs/steps/setupCommonPipelineEnvironment.md index cc4ab2e6b..60b2d37fe 100644 --- a/documentation/docs/steps/setupCommonPipelineEnvironment.md +++ b/documentation/docs/steps/setupCommonPipelineEnvironment.md @@ -1,6 +1,7 @@ # setupCommonPipelineEnvironment ## Description + Initializes the [`commonPipelineEnvironment`](commonPipelineEnvironment.md), which is used throughout the complete pipeline. !!! tip @@ -8,6 +9,7 @@ Initializes the [`commonPipelineEnvironment`](commonPipelineEnvironment.md), whi Then subsequent pipeline steps consume the information from `commonPipelineEnvironment`; it does not need to be passed to pipeline steps explicitly. ## Prerequisites + * A **configuration file** with properties (default location: `.pipeline/config.properties`). The property values are used as default values in many pipeline steps. ## Parameters @@ -21,18 +23,23 @@ Initializes the [`commonPipelineEnvironment`](commonPipelineEnvironment.md), whi * `configFile` - Property file defining project specific settings. ## Step configuration + none ## Return value + none ## Side effects + none ## Exceptions -none + +none ## Example + ```groovy setupCommonPipelineEnvironment script: this ``` diff --git a/documentation/docs/steps/testsPublishResults.md b/documentation/docs/steps/testsPublishResults.md index f2da7d8f2..6e0e9d012 100644 --- a/documentation/docs/steps/testsPublishResults.md +++ b/documentation/docs/steps/testsPublishResults.md @@ -1,6 +1,7 @@ # testsPublishResults ## Description + This step can publish test results from various sources. ## Prerequsites @@ -49,7 +50,7 @@ Available parameters: Each of the parameters `junit`, `jacoco`, `cobertura` and `jmeter` can be set to `true` or `false` but also to a map of parameters to hand in different settings for the tools. -**junit** +### junit | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -58,7 +59,7 @@ Each of the parameters `junit`, `jacoco`, `cobertura` and `jmeter` can be set to | updateResults | no | `false` | true, false | | allowEmptyResults | no | `true` | true, false | -**jacoco** +### jacoco | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -68,7 +69,7 @@ Each of the parameters `junit`, `jacoco`, `cobertura` and `jmeter` can be set to | archive | no | `false` | true, false | | allowEmptyResults | no | `true` | true, false | -**cobertura** +### cobertura | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -77,7 +78,7 @@ Each of the parameters `junit`, `jacoco`, `cobertura` and `jmeter` can be set to | allowEmptyResults | no | `true` | true, false | | onlyStableBuilds | no | `true` | true, false | -**jmeter** +### jmeter | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -99,6 +100,7 @@ Each of the parameters `junit`, `jacoco`, `cobertura` and `jmeter` can be set to | allowEmptyResults | no | `true` | true, false | ## Step configuration + Following parameters can also be specified as step parameters using the global configuration file: * `junit` @@ -107,15 +109,19 @@ Following parameters can also be specified as step parameters using the global c * `jmeter` ## Return value + none ## Side effects + none ## Exceptions + none ## Example + ```groovy // publish test results with coverage testsPublishResults( diff --git a/documentation/docs/steps/toolValidate.md b/documentation/docs/steps/toolValidate.md index a3b0675ae..7fe71667f 100644 --- a/documentation/docs/steps/toolValidate.md +++ b/documentation/docs/steps/toolValidate.md @@ -1,13 +1,16 @@ # toolValidate ## Description + Checks the existence and compatibility of a tool, necessary for a successful pipeline execution. In case a violation is found, an exception is raised. ## Prerequisites + none ## Parameters + | parameter | mandatory | default | possible values | | -----------------|-----------|-----------------------------------|----------------------------| | `tool` | yes | | 'java', 'mta', 'neo' | @@ -17,22 +20,26 @@ none * `home` The location in the file system where Jenkins can access the tool. ## Step configuration + none ## Return value + none ## Side effects + none ## Exceptions + * `IllegalArgumentException`: - * If at least one of the parameters `tool`, `home` is not provided. + * If at least one of the parameters `tool`, `home` is not provided. * `AbortException`: - * If `tool` is not supported. + * If `tool` is not supported. ## Example + ```groovy toolValidate tool: 'neo', home:'/path/to/neo-java-web-sdk' ``` - diff --git a/documentation/docs/steps/transportRequestCreate.md b/documentation/docs/steps/transportRequestCreate.md index d5ee24042..a5f44a865 100644 --- a/documentation/docs/steps/transportRequestCreate.md +++ b/documentation/docs/steps/transportRequestCreate.md @@ -1,15 +1,18 @@ # transportRequestCreate ## Description + Creates * a Transport Request for a Change Document on the Solution Manager (type `SOLMAN`) or * a Transport Request inside an ABAP system (type`CTS`) ## Prerequisites + * **[Change Management Client 2.0.0 or compatible version](http://central.maven.org/maven2/com/sap/devops/cmclient/dist.cli/)** - available for download on Maven Central. ## Parameters + | parameter | mandatory | default | possible values | | -----------------|-----------|--------------------------------------------------------|--------------------| | `script` | yes | | | @@ -41,15 +44,16 @@ Creates * `transportType` - for type `CTS` only. Typically `W` (workbench) or `C` customizing. ## Step configuration + The step is configured using a customer configuration file provided as resource in an custom shared library. -``` +```groovy @Library('piper-library-os@master') _ // the shared lib containing the additional configuration // needs to be configured in Jenkins -@Library(foo@master') __ +@Library('foo@master') __ // inside the shared lib denoted by 'foo' the additional configuration file // needs to be located under 'resources' ('resoures/myConfig.yml') @@ -57,10 +61,10 @@ prepareDefaultValues script: this, customDefaults: 'myConfig.yml' ``` -Example content of ```'resources/myConfig.yml'``` in branch ```'master'``` of the repository denoted by -```'foo'```: +Example content of `'resources/myConfig.yml'` in branch `'master'` of the repository denoted by +`'foo'`: -``` +```yaml general: changeManagement: changeDocumentLabel: 'ChangeDocument\s?:' @@ -79,7 +83,7 @@ all change managment related steps. The properties can also be configured on a per-step basis: -``` +```yaml [...] steps: transportRequestCreate: @@ -92,15 +96,18 @@ The properties can also be configured on a per-step basis: The parameters can also be provided when the step is invoked. For examples see below. ## Return value + The id of the Transport Request that has been created. ## Exceptions + * `AbortException`: - * If the creation of the transport request fails. + * If the creation of the transport request fails. * `IllegalStateException`: - * If the change id is not provided. + * If the change id is not provided. ## Example + ```groovy // SOLMAN def transportRequestId = transportRequestCreate script:this, @@ -119,4 +126,3 @@ def transportRequestId = transportRequestCreate script:this, endpoint: 'https://example.org/cm' ] ``` - diff --git a/documentation/docs/steps/transportRequestRelease.md b/documentation/docs/steps/transportRequestRelease.md index e4baeda24..59afc7f72 100644 --- a/documentation/docs/steps/transportRequestRelease.md +++ b/documentation/docs/steps/transportRequestRelease.md @@ -1,12 +1,15 @@ # transportRequestRelease ## Description + Releases a Transport Request. ## Prerequisites + * **[Change Management Client 2.0.0 or compatible version](http://central.maven.org/maven2/com/sap/devops/cmclient/dist.cli/)** - available for download on Maven Central. ## Parameters + | parameter | mandatory | default | possible values | | -----------------|-----------|--------------------------------------------------------|--------------------| | `script` | yes | | | @@ -33,15 +36,16 @@ Releases a Transport Request. * `changeManagement/git/format` - Specifies what part of the commit is scanned. By default the body of the commit message is scanned. ## Step configuration + The step is configured using a customer configuration file provided as resource in an custom shared library. -``` +```groovy @Library('piper-library-os@master') _ // the shared lib containing the additional configuration // needs to be configured in Jenkins -@Library(foo@master') __ +@Library('foo@master') __ // inside the shared lib denoted by 'foo' the additional configuration file // needs to be located under 'resources' ('resoures/myConfig.yml') @@ -49,10 +53,10 @@ prepareDefaultValues script: this, customDefaults: 'myConfig.yml' ``` -Example content of ```'resources/myConfig.yml'``` in branch ```'master'``` of the repository denoted by -```'foo'```: +Example content of `'resources/myConfig.yml'` in branch `'master'` of the repository denoted by +`'foo'`: -``` +```yaml general: changeManagement: changeDocumentLabel: 'ChangeDocument\s?:' @@ -70,7 +74,7 @@ The properties configured in section `'general/changeManagement'` are shared bet The properties can also be configured on a per-step basis: -``` +```yaml [...] steps: transportRequestRelease: @@ -83,16 +87,19 @@ The properties can also be configured on a per-step basis: The parameters can also be provided when the step is invoked. For examples see below. ## Return value + None. ## Exceptions + * `IllegalArgumentException`: - * If the change id is not provided (`SOLMAN` only) - * If the transport request id is not provided. + * If the change id is not provided (`SOLMAN` only) + * If the transport request id is not provided. * `AbortException`: - * If the release of the transport request fails. + * If the release of the transport request fails. ## Example + ```groovy // SOLMAN transportRequestRelease script:this, @@ -110,4 +117,3 @@ transportRequestRelease script:this, endpoint: 'https://example.org/cm' ] ``` - diff --git a/documentation/docs/steps/transportRequestUploadFile.md b/documentation/docs/steps/transportRequestUploadFile.md index e4a9da916..88eee8a44 100644 --- a/documentation/docs/steps/transportRequestUploadFile.md +++ b/documentation/docs/steps/transportRequestUploadFile.md @@ -1,12 +1,15 @@ # transportRequestUploadFile ## Description + Uploads a file to a Transport Request. ## Prerequisites + * **[Change Management Client 2.0.0 or compatible version](http://central.maven.org/maven2/com/sap/devops/cmclient/dist.cli/)** - available for download on Maven Central. ## Parameters + | parameter | mandatory | default | possible values | | -----------------|-----------|--------------------------------------------------------|--------------------| | `script` | yes | | | @@ -38,15 +41,16 @@ Uploads a file to a Transport Request. * `changeManagement/git/format` - Specifies what part of the commit is scanned. By default the body of the commit message is scanned. ## Step configuration + The step is configured using a customer configuration file provided as resource in an custom shared library. -``` +```groovy @Library('piper-library-os@master') _ // the shared lib containing the additional configuration // needs to be configured in Jenkins -@Library(foo@master') __ +@Library('foo@master') __ // inside the shared lib denoted by 'foo' the additional configuration file // needs to be located under 'resources' ('resoures/myConfig.yml') @@ -54,10 +58,10 @@ prepareDefaultValues script: this, customDefaults: 'myConfig.yml' ``` -Example content of ```'resources/myConfig.yml'``` in branch ```'master'``` of the repository denoted by -```'foo'```: +Example content of `'resources/myConfig.yml'` in branch `'master'` of the repository denoted by +`'foo'`: -``` +```yaml general: changeManagement: changeDocumentLabel: 'ChangeDocument\s?:' @@ -75,7 +79,7 @@ The properties configured in section `'general/changeManagement'` are shared bet The properties can also be configured on a per-step basis: -``` +```yaml [...] steps: transportRequestUploadFile: @@ -89,18 +93,21 @@ The properties can also be configured on a per-step basis: The parameters can also be provided when the step is invoked. For examples see below. ## Return value + None. ## Exceptions + * `IllegalArgumentException`: - * If the change id is not provided (`SOLMAN` only). - * If the transport request id is not provided. - * If the application id is not provided (`SOLMAN` only). - * If the file path is not provided. + * If the change id is not provided (`SOLMAN` only). + * If the transport request id is not provided. + * If the application id is not provided (`SOLMAN` only). + * If the file path is not provided. * `AbortException`: - * If the upload fails. + * If the upload fails. ## Example + ```groovy // SOLMAN transportRequestUploadFile script:this, @@ -121,4 +128,3 @@ transportRequestUploadFile script:this, endpoint: 'https://example.org/cm' ] ``` - diff --git a/template/script.md b/template/script.md index 2aae812ba..9e2a60b19 100644 --- a/template/script.md +++ b/template/script.md @@ -1,6 +1,7 @@ #