From fe6cc8867a464efb0220a78184d6893c7ee2ab99 Mon Sep 17 00:00:00 2001 From: Alejandra Ferreiro Vidal Date: Tue, 6 Mar 2018 13:43:53 +0100 Subject: [PATCH] add new configuration documentation --- .../docs/steps/artifactSetVersion.md | 8 +++---- .../docs/steps/checksPublishResults.md | 13 +++++++++++ documentation/docs/steps/dockerExecute.md | 3 +++ documentation/docs/steps/durationMeasure.md | 21 +++++++++--------- .../docs/steps/handlePipelineStepErrors.md | 3 +++ documentation/docs/steps/influxWriteData.md | 22 ++++++++++--------- documentation/docs/steps/mavenExecute.md | 5 +++-- documentation/docs/steps/mtaBuild.md | 6 +++++ documentation/docs/steps/neoDeploy.md | 11 ++++++++++ documentation/docs/steps/pipelineExecute.md | 4 ++++ .../docs/steps/prepareDefaultValues.md | 4 ++++ .../steps/setupCommonPipelineEnvironment.md | 3 +++ documentation/docs/steps/toolValidate.md | 6 ++--- template/step.md | 5 +++++ 14 files changed, 85 insertions(+), 29 deletions(-) diff --git a/documentation/docs/steps/artifactSetVersion.md b/documentation/docs/steps/artifactSetVersion.md index 24e1c38b7..95f8c9520 100644 --- a/documentation/docs/steps/artifactSetVersion.md +++ b/documentation/docs/steps/artifactSetVersion.md @@ -22,6 +22,7 @@ none | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| | script | no | empty `commonPipelineEnvironment` | | +| artifactType | no | | 'appContainer' | | buildTool | no | maven | maven, docker | | commitVersion | no | `true` | `true`, `false` | | dockerVersionSource | no | `''` | FROM, (ENV name),appVersion | @@ -37,6 +38,7 @@ none | versioningTemplate | no | depending on `buildTool`
maven: `${version}-${timestamp}${commitId?"_"+commitId:""}` | | * `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. +* `artifactType` defines the type of the artifact. * `buildTool` defines the tool which is used for building the artifact. * `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. @@ -54,7 +56,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 -Following parameters can also be specified as step parameters using the global configuration file: +The following parameters can also be specified as step parameters using the global configuration file: * `artifactType` * `buildTool` @@ -70,9 +72,7 @@ Following parameters can also be specified as step parameters using the global c * `timestampTemplate` * `versioningTemplate` -## Explanation of pipeline step - -Pipeline step: +## Example ```groovy artifactSetVersion script: this, buildTool: 'maven' diff --git a/documentation/docs/steps/checksPublishResults.md b/documentation/docs/steps/checksPublishResults.md index de2aa0856..38c7de2e2 100644 --- a/documentation/docs/steps/checksPublishResults.md +++ b/documentation/docs/steps/checksPublishResults.md @@ -102,6 +102,19 @@ Each of the parameters `aggregation`, `tasks`, `pmd`, `cpd`, `findbugs`, `checks | archive | no | `true` | `true`, `false` | | thresholds | no | none | see [thresholds](#thresholds) | +## Step configuration +Following parameters can also be specified as step parameters using the global configuration file: + +* `aggregation` +* `tasks` +* `pmd` +* `cpd` +* `findbugs` +* `checkstyle` +* `eslint` +* `pylint` +* `archive` + ### Thresholds It is possible to define thresholds to fail the build on a certain count of findings. To achive this, just define your thresholds a followed for the specific check tool: diff --git a/documentation/docs/steps/dockerExecute.md b/documentation/docs/steps/dockerExecute.md index 0562c3403..5e45ed413 100644 --- a/documentation/docs/steps/dockerExecute.md +++ b/documentation/docs/steps/dockerExecute.md @@ -20,6 +20,9 @@ Proxy environment variables defined on the Jenkins machine are also available in * `dockerOptions` Docker options to be set when starting the container. * `dockerVolumeBind` Volumes that should be mounted into the container. +## Step configuration +None + ## Exceptions None diff --git a/documentation/docs/steps/durationMeasure.md b/documentation/docs/steps/durationMeasure.md index 27ffbe2a1..b13a110ff 100644 --- a/documentation/docs/steps/durationMeasure.md +++ b/documentation/docs/steps/durationMeasure.md @@ -14,16 +14,7 @@ none ## Pipeline configuration none -## Explanation of pipeline step -Usage of pipeline step: - -```groovy -durationMeasure (script: this, measurementName: 'build_duration') { - //execute your build -} -``` - -Available parameters: +## Parameters | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -35,3 +26,13 @@ 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. * `measurementName` defines the name of the measurement which is written to the Influx database. +## Step configuration +none + +## Example + +```groovy +durationMeasure (script: this, measurementName: 'build_duration') { + //execute your build +} +``` diff --git a/documentation/docs/steps/handlePipelineStepErrors.md b/documentation/docs/steps/handlePipelineStepErrors.md index 9abf4a3fe..320a18c60 100644 --- a/documentation/docs/steps/handlePipelineStepErrors.md +++ b/documentation/docs/steps/handlePipelineStepErrors.md @@ -38,6 +38,9 @@ none ---------------------------------------------------------- ``` +## Step configuration +none + ## Return value none diff --git a/documentation/docs/steps/influxWriteData.md b/documentation/docs/steps/influxWriteData.md index 503753afb..1b7ae1031 100644 --- a/documentation/docs/steps/influxWriteData.md +++ b/documentation/docs/steps/influxWriteData.md @@ -80,16 +80,7 @@ You need to define the influxDB server in your pipeline as it is defined in the influxDBServer=jenkins ``` -## Explanation of pipeline step - -Example usage of pipeline step: - -```groovy -influxWriteData script: this -``` - -Available parameters: - +## Parameters | parameter | mandatory | default | possible values | | ----------|-----------|---------|-----------------| @@ -98,6 +89,17 @@ Available parameters: | influxServer | no | `jenkins` | | | influxPrefix | no | `null` | | +## Step configuration +The following parameters can also be specified as step parameters using the global configuration file: + +* `influxServer` +* `influxPrefix` + +## Example + +```groovy +influxWriteData script: this +``` ## Work with InfluxDB and Grafana diff --git a/documentation/docs/steps/mavenExecute.md b/documentation/docs/steps/mavenExecute.md index 794d00903..265522853 100644 --- a/documentation/docs/steps/mavenExecute.md +++ b/documentation/docs/steps/mavenExecute.md @@ -26,8 +26,9 @@ Executes a maven command inside a Docker container. * `m2Path` Path to the location of the local repository that should be used. * `defines` Additional properties. -## Global Configuration -The following parameters can also be specified using the global configuration file: +## Step configuration +The following parameters can also be specified as step parameters using the global configuration file: + * `dockerImage` * `globalSettingsFile` * `projectSettingsFile` diff --git a/documentation/docs/steps/mtaBuild.md b/documentation/docs/steps/mtaBuild.md index 9d41bb43a..a97321d4c 100644 --- a/documentation/docs/steps/mtaBuild.md +++ b/documentation/docs/steps/mtaBuild.md @@ -19,6 +19,12 @@ Executes the SAP MTA Archive Builder to create an mtar archive of the applicatio * `buildTarget` - The target platform to which the mtar can be deployed. * `mtaJarLocation` - The path of the `mta.jar` file. If no parameter is provided, neither at the level of the method call nor via step configuration, the path is retrieved from the Jenkins environment variables using `env.MTA_JAR_LOCATION`. If the Jenkins environment variable is not set it is assumed that `mta.jar` is located in the current working directory. +## Step configuration +The following parameters can also be specified as step parameters using the global configuration file: + +* `buildTarget` +* `mtaJarLocation` + ## Return value The file name of the resulting archive is returned with this step. The file name is extracted from the key `ID` defined in `mta.yaml`. diff --git a/documentation/docs/steps/neoDeploy.md b/documentation/docs/steps/neoDeploy.md index 9b831cbcd..b6705c962 100644 --- a/documentation/docs/steps/neoDeploy.md +++ b/documentation/docs/steps/neoDeploy.md @@ -77,6 +77,17 @@ 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` +* `dockerEnvVars` +* `dockerImage` +* `dockerOptions` +* `host` +* `neoCredentialsId` +* `neoHome` + ## Return value none diff --git a/documentation/docs/steps/pipelineExecute.md b/documentation/docs/steps/pipelineExecute.md index 7e6067c9a..d580f26d5 100644 --- a/documentation/docs/steps/pipelineExecute.md +++ b/documentation/docs/steps/pipelineExecute.md @@ -25,6 +25,10 @@ none * `path` The path to the Jenkinsfile, inside the repository, to be loaded. * `credentialsId` The Jenkins credentials containing user and password needed to access a private git repository. +## Step configuration + +none + ## Return value none diff --git a/documentation/docs/steps/prepareDefaultValues.md b/documentation/docs/steps/prepareDefaultValues.md index fb229afbc..58e61c725 100644 --- a/documentation/docs/steps/prepareDefaultValues.md +++ b/documentation/docs/steps/prepareDefaultValues.md @@ -9,6 +9,10 @@ Afterwards the values can be loaded by the method: `ConfigurationLoader.defaultS None +## Step configuration + +None + ## Exceptions None diff --git a/documentation/docs/steps/setupCommonPipelineEnvironment.md b/documentation/docs/steps/setupCommonPipelineEnvironment.md index 50e42c5ab..cc4ab2e6b 100644 --- a/documentation/docs/steps/setupCommonPipelineEnvironment.md +++ b/documentation/docs/steps/setupCommonPipelineEnvironment.md @@ -20,6 +20,9 @@ Initializes the [`commonPipelineEnvironment`](commonPipelineEnvironment.md), whi * `script` - The reference to the pipeline script (Jenkinsfile). Normally `this` needs to be provided. * `configFile` - Property file defining project specific settings. +## Step configuration +none + ## Return value none diff --git a/documentation/docs/steps/toolValidate.md b/documentation/docs/steps/toolValidate.md index 5204aa416..a3b0675ae 100644 --- a/documentation/docs/steps/toolValidate.md +++ b/documentation/docs/steps/toolValidate.md @@ -16,6 +16,9 @@ none * `tool` The tool that is checked for existence and compatible version. * `home` The location in the file system where Jenkins can access the tool. +## Step configuration +none + ## Return value none @@ -33,6 +36,3 @@ none toolValidate tool: 'neo', home:'/path/to/neo-java-web-sdk' ``` - - - diff --git a/template/step.md b/template/step.md index 87de4704b..9d90b53e0 100644 --- a/template/step.md +++ b/template/step.md @@ -13,6 +13,11 @@ Brief description. * `` - Detailed description of each parameter. +## Step configuration +The following parameters can also be specified as step parameters using the global configuration file: + +* `` + ## Return value none