We have a strong focus on high quality software and contributions without adequate tests will not be accepted. There is an excellent resource which teaches Go using a test-driven approach: Learn Go with Tests

Checkout your fork

The project uses Go modules. Thus please make sure to NOT checkout the project into your GOPATH.

To check out this repository:

Create your own fork of this repo
Clone it to your machine, for example like:

mkdir -p ${HOME}/projects/jenkins-library
cd ${HOME}/projects
git clone git@github.com:${YOUR_GITHUB_USERNAME}/jenkins-library.git
cd jenkins-library
git remote add upstream git@github.com:sap/jenkins-library.git
git remote set-url --push upstream no_push

Jenkins environment

If you want to contribute also to the Jenkins-specific parts like

Jenkins library step
Jenkins pipeline integration

you need to do the following in addition:

Install Groovy
Install Maven
Get a local Jenkins installed: Use for example cx-server

Jenkins pipelines

The Jenkins related parts depend on

You should get familiar with these concepts for contributing to the Jenkins-specific parts.

Build the project

Build the executable suitable for the CI/CD Linux target environments

Use Docker:

docker build -t piper:latest .

You can extract the binary using Docker means to your local filesystem:

docker create --name piper piper:latest
docker cp piper:/piper .
docker rm piper

Generating step framework

The steps are generated based on the yaml files in resources/metadata/ with the following command go run pkg/generator/step-metadata.go.

The yaml format is kept pretty close to Tekton's task format. Where the Tekton format was not sufficient some extenstions have been made.

Examples are:

matadata - longDescription
spec - inputs - secrets
spec - containers
spec - sidecars

There are certain extensions:

aliases allow alternative parameter names also supporting deeper configuration structures. Example
resources allow to read for example from a shared commonPipelineEnvironment which contains information which has been provided by a previous step in the pipeline via an output. Example
secrets allow to specify references to Jenkins credentials which can be used in the groovy library. Example
outputs allow to write to dedicated outputs like
- Influx metrics. Example
- Sharing data via commonPipelineEnvironment which can be used by another step as input
conditions allow for example to specify in which case a certain container is used (depending on a configuration parameter). Example

Logging

Logging is done through sirupsen/logrus framework. It can conveniently be accessed through:

import (
    "github.com/SAP/jenkins-library/pkg/log"
)

func myStep ...
    ...
    log.Entry().Info("This is my info.")
    ...
}

If a fatal error occurs your code should act similar to:

    ...
    if err != nil {
        log.Entry().
            WithError(err).
            Fatal("failed to execute step ...")
    }

Calling Fatal results in an os.Exit(0) and before exiting some cleanup actions (e.g. writing output data, writing telemetry data if not deactivated by the user, ...) are performed.

Error handling

In order to better understand the root cause of errors that occur we wrap errors like

    f, err := os.Open(path)
    if err != nil {
        return errors.Wrapf(err, "open failed for %v", path)
    }
    defer f.Close()

We use github.com/pkg/errors for that.

Testing

Unit tests are done using basic golang means.

Additionally we encourage you to use github.com/stretchr/testify/assert in order to have slimmer assertions if you like.

Debugging

Debugging can be initiated with VS code fairly easily. Compile the binary with spcific compiler flags to turn off optimizations go build -gcflags "all=-N -l" -o piper.exe.

Modify the launch.json located in folder .vscode of your project root to point with program exatly to the binary that you just built with above command - must be an absolute path. In addition add any arguments required for the execution of the Piper step to args. What is separated with a blank on the command line must go into a separate string.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch",
            "type": "go",
            "request": "launch",
            "mode": "exec",
            "program": "C:/CF@HCP/git/jenkins-library-public/piper.exe",
            "env": {},
            "args": ["checkmarxExecuteScan", "--password", "abcd", "--username", "1234", "--projectName", "testProject4711", "--serverUrl", "https://cx.server.com/"]
        }
    ]
}

Finally set your breakpoints and use the Launch button in the VS code UI to start debugging.

Release

Releases are performed using Project "Piper" Action. We release on schedule (once a week) and on demand. To perform a release, the respective action must be invoked for which a convenience script is available in contrib/perform-release.sh. It requires a personal access token for GitHub with repo scope. Example usage PIPER_RELEASE_TOKEN=THIS_IS_MY_TOKEN contrib/perform-release.sh.

7.8 KiB Raw Blame History

Development

Getting started

Ramp up

Go basics