Add documentation + groovy file for the abapEnvironmentCheckoutBranch step (#1887)

* Add abaputils pkg and go files

* Add ReadServiceKeyAbapEnvironment function

* Fixes

* Add structs for SC, Pull and Branch

* Minor Improvements

* Adapt unit tests to new abaputils pkg

* Fixes

* Add adapted tests

* Fixes

* Fix cloudfoundry test

* Add check for host prefix (HTTPS)

* Fix tests + cleanup

* Fixes

* Fixes

* Fix

* Add mock for abaputils pkg unit tests

* Adapt abaputils comments

* Add abapEnvironmentCheckoutBranch step setup

* Change description of abapEnvCheckoutBranch step

* Add http client code

* Disable code due to missing interace

* Add coding for use of abaputils

* Adapt checkout branch step

* Adapt URL for checkout_branch function import

* Fixes

* Add unit test for missing params case

* Fix for missing mapping of CfSpace

* Fix for missing mapping of CfSpace

* Add working code for a Branch Checkout

* Fix host schema

* Remove LogoutOption param of unit tests and steps

* Fix unit test

* Fix unit test CF ReadServiceKey

* Add abapEnvironmentCheckoutBranch step setup

* Change description of abapEnvCheckoutBranch step

* Add http client code

* Disable code due to missing interace

* Add coding for use of abaputils

* Adapt checkout branch step

* Adapt URL for checkout_branch function import

* Fixes

* Fix for missing mapping of CfSpace

* Add working code for a Branch Checkout

* Adapt changes of abautils pkg

* Add test for polling

* Minor fix

* Fix yaml spacing

* Add longdescription to yaml

* Refactor abaputil methods

* Refactoring

* Refactoring

* Minor fix

* Minor fixeds

* Adapt to new abaputils.AUtilsMock

* Delete obsolete initial checks for params

* Fix manageGitRepoUtils_test.go

* Adjust pollEntity tests

* Add abapEnvironmentCheckoutBranch.groovy file

* Add documentation for abapEnvCheckoutBranch step

* Add step to whitelist in commonStepsTest.groovy

* Add GENERAL scope to host parameter

* Fix generated.go file

Co-authored-by: Daniel Mieg <56156797+DanielMieg@users.noreply.github.com>

cmd/abapEnvironmentCheckoutBranch_generated.go

@@ -150,7 +150,7 @@ func abapEnvironmentCheckoutBranchMetadata() config.StepData {
 					{
 						Name:        "host",
 						ResourceRef: []config.ResourceReference{},
-						Scope:       []string{"PARAMETERS", "STAGES", "STEPS"},
+						Scope:       []string{"PARAMETERS", "STAGES", "STEPS", "GENERAL"},
 						Type:        "string",
 						Mandatory:   false,
 						Aliases:     []config.Alias{},

documentation/docs/steps/abapEnvironmentCheckoutBranch.md

@@ -0,0 +1,81 @@
+# ${docGenStepName}
+
+## ${docGenDescription}
+
+## Prerequisites
+
+A SAP Cloud Platform ABAP Environment system is available.
+On this system, a [Communication User](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/0377adea0401467f939827242c1f4014.html), a [Communication System](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/1bfe32ae08074b7186e375ab425fb114.html) and a [Communication Arrangement](https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/a0771f6765f54e1c8193ad8582a32edb.html) is setup for the Communication Scenario "SAP Cloud Platform ABAP Environment - Software Component Test Integration (SAP_COM_0510)". This can be done manually through the respective applications on the SAP Cloud Platform ABAP Environment System or through creating a service key for the system on cloud foundry with the parameters {"scenario_id": "SAP_COM_0510", "type": "basic"}. In a pipeline, you can do this with the step [cloudFoundryCreateServiceKey](https://sap.github.io/jenkins-library/steps/cloudFoundryCreateServiceKey/). In addition, the software component should be cloned into the system instance. You can do this with the step [abapEnvironmentPullGitRepo](https://sap.github.io/jenkins-library/steps/abapEnvironmentPullGitRepo/).
+
+## ${docGenParameters}
+
+## ${docGenConfiguration}
+
+## ${docJenkinsPluginDependencies}
+
+## Example: Configuration in the config.yml
+
+The recommended way to configure your pipeline is via the config.yml file. In this case, calling the step in the Jenkinsfile is reduced to one line:
+
+```groovy
+abapEnvironmentCheckoutBranch script: this
+```
+
+If you want to provide the host and credentials of the Communication Arrangement directly, the configuration could look as follows:
+
+```yaml
+
+steps:
+  abapEnvironmentCheckoutBranch:
+    repositoryName: '/DMO/GIT_REPOSITORY'
+    branchName: 'my-demo-branch'
+    abapCredentialsId: 'abapCredentialsId'
+    host: '1234-abcd-5678-efgh-ijk.abap.eu10.hana.ondemand.com'
+```
+Please note that the branchName parameter specifies the target branch you want to switch on. Also keep in mind that the repositoryName parameter must define a single repository.
+
+If you want to read the host and credentials from the cloud foundry service key of the respective instance, the configuration could look as follows:
+
+```yaml
+steps:
+  abapEnvironmentCheckoutBranch:
+    repositoryName: '/DMO/GIT_REPOSITORY'
+    branchName: 'my-demo-branch'
+    cfCredentialsId: 'cfCredentialsId'
+    cfApiEndpoint: 'https://test.server.com'
+    cfOrg: 'cfOrg'
+    cfSpace: 'cfSpace'
+    cfServiceInstance: 'cfServiceInstance'
+    cfServiceKeyName: 'cfServiceKeyName'
+```
+
+## Example: Configuration in the Jenkinsfile
+
+It is also possible to call the steps - including all parameters - directly in the Jenkinsfile.
+In the first example, the host and the credentialsId of the Communication Arrangement are directly provided.
+
+```groovy
+abapEnvironmentCheckoutBranach (
+  script: this,
+  repositoryName: '/DMO/GIT_REPOSITORY',
+  branchName: 'my-demo-branch',
+  abapCredentialsId: 'abapCredentialsId',
+  host: '1234-abcd-5678-efgh-ijk.abap.eu10.hana.ondemand.com'
+)
+```
+
+In the second example, the host and credentialsId will be read from the provided cloud foundry service key of the specified service instance.
+
+```groovy
+abapEnvironmentCheckoutBranch (
+  script: this,
+  repositoryName: '/DMO/GIT_REPOSITORY',
+  branchName: 'my-demo-branch'
+  abapCredentialsId: 'cfCredentialsId',
+  cfApiEndpoint: 'https://test.server.com',
+  cfOrg: 'cfOrg',
+  cfSpace: 'cfSpace',
+  cfServiceInstance: 'cfServiceInstance',
+  cfServiceKeyName: 'cfServiceKeyName'
+)
+```

documentation/mkdocs.yml

@@ -39,6 +39,7 @@ nav:
         - 'Build an SAP Fiori Application and Attach It to a Transport Request on an ABAP System with Jenkins': scenarios/upload-to-transportrequest/Readme.md
     - Extensibility: extensibility.md
     - 'Library steps':
+        - abapEnvironmentCheckoutBranch: steps/abapEnvironmentCheckoutBranch.md
         - abapEnvironmentPullGitRepo: steps/abapEnvironmentPullGitRepo.md
         - abapEnvironmentRunATCCheck: steps/abapEnvironmentRunATCCheck.md
         - artifactPrepareVersion: steps/artifactPrepareVersion.md

resources/metadata/abapEnvironmentCheckoutBranch.yaml

@@ -60,6 +60,7 @@ spec:
         - PARAMETERS
         - STAGES
         - STEPS
+        - GENERAL
       - name: cfApiEndpoint
         type: string
         description: Cloud Foundry API Enpoint

test/groovy/CommonStepsTest.groovy

@@ -149,7 +149,8 @@ public class CommonStepsTest extends BasePiperTest{
         'gctsDeploy', //implementing new golang pattern without fields
         'containerSaveImage', //implementing new golang pattern without fields
         'detectExecuteScan', //implementing new golang pattern without fields
-        'kanikoExecute' //implementing new golang pattern without fields
+        'kanikoExecute', //implementing new golang pattern without fields
+        'abapEnvironmentCheckoutBranch' //implementing new golang pattern without fields
 
     ]
 

vars/abapEnvironmentCheckoutBranch.groovy

@@ -0,0 +1,11 @@
+import groovy.transform.Field
+
+@Field String STEP_NAME = getClass().getName()
+@Field String METADATA_FILE = 'metadata/abapEnvironmentCheckoutBranch.yaml'
+
+void call(Map parameters = [:]) {
+    List credentials = [
+        [type: 'usernamePassword', id: 'abapCredentialsId', env: ['PIPER_username', 'PIPER_password']]
+    ]
+    piperExecuteBin(parameters, STEP_NAME, METADATA_FILE, credentials, false, false, true)
+}