{"id":15083699,"url":"https://github.com/ebay/jenkins-pipeline-utils","last_synced_at":"2025-10-05T14:31:37.545Z","repository":{"id":51748913,"uuid":"142195637","full_name":"eBay/Jenkins-Pipeline-Utils","owner":"eBay","description":"Global Jenkins Pipeline Library with common utilities.","archived":true,"fork":false,"pushed_at":"2021-05-10T06:47:20.000Z","size":27,"stargazers_count":39,"open_issues_count":0,"forks_count":20,"subscribers_count":8,"default_branch":"1.x","last_synced_at":"2024-09-25T06:31:17.928Z","etag":null,"topics":["docker-compose","jenkins-pipeline","shared-library","utilities"],"latest_commit_sha":null,"homepage":"","language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eBay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-24T18:08:27.000Z","updated_at":"2023-11-10T07:17:39.000Z","dependencies_parsed_at":"2022-08-23T05:31:06.460Z","dependency_job_id":null,"html_url":"https://github.com/eBay/Jenkins-Pipeline-Utils","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJenkins-Pipeline-Utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJenkins-Pipeline-Utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJenkins-Pipeline-Utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJenkins-Pipeline-Utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eBay","download_url":"https://codeload.github.com/eBay/Jenkins-Pipeline-Utils/tar.gz/refs/heads/1.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219871465,"owners_count":16554416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-compose","jenkins-pipeline","shared-library","utilities"],"created_at":"2024-09-25T06:31:31.130Z","updated_at":"2025-10-05T14:31:37.236Z","avatar_url":"https://github.com/eBay.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jenkins Pipeline Utilities\n![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)\n  \nGlobal Jenkins Pipeline Library with common utilities.  \nFor basic instructions, see [Usage](#usage), [Prerequisites](#prerequisites) and [Configuration](#configuration) sections below.\n\nDefines the following global [steps](#steps):\n* [`withCommonPipelineSettings`](#withcommonpipelinesettings)\n* [`withDockerEx`](#withdockerex)\n* [`waitForPort`](#waitforport)\n* [`waitForEndpoint`](#waitforendpoint)\n* [`withUsernamePassword`](#withusernamepassword)\n* [`withSecretText`](#withsecrettext)\n* [`withSecretFile`](#withsecretfile)\n* [`failAsUnstable`](#failasunstable)\n* [`shEx`](#shex)\n* [`interactiveShell`](#interactiveshell)\n* [`interactiveGroovyShell`](#interactivegroovyshell)\n\nAlso defines the following [properties](#properties):\n* [`discardOldBuildsProperty`](#discardoldbuildsproperty)\n\nFor utilities for testing global pipeline libraries, see: [TESTING.md](TESTING.md)\n\n## Usage\n\n**Basic `Jenkinsfile` Example:**\n```groovy\n@Library('pipeline-utils@1.x') _\n\nproperties([\n  discardOldBuildsProperty()\n])\n\nwithCommonPipelineSettings {\n  node('node-with-docker-compose') {\n    stage('Setup') {\n      checkout scm\n    }\n        \n    stage('Build') {\n      // Build ...\n    }\n        \n    stage('Unit Tests') {\n      // Unit tests ...\n    }\n        \n    stage('Publish') {\n      // Publish ...\n    }\n        \n    failAsUnstable {\n      withDockerEx { dockerEx -\u003e\n        def sidecarIp\n        stage('Start Sidecars') {\n          def sidecar = dockerEx.compose('sidecar', file: 'path/to/sidecar.yml')\n          sidecar.up().ps()\n          sidecarIp = sidecar.inspectGateway()\n          echo \"Sidecar IP: $sidecarIp\"\n        }\n                \n        stage('Integration Tests') {\n          // Run integration tests using the sidecar IP\n        }\n      }\n    }\n  }\n}\n```\n\n### Prerequisites\n1. Only Linux OS based Jenkins nodes are supported\n1. Some steps require tools to be pre-installed (e.g. `docker`, `docker-compose`, `curl`, `nc`, etc.)\n\n### Configuration\nTo use this Global Jenkins Pipeline Library you first need to add it to your Jenkins instance:\n1. Go to: \"Manage Jenkins\" -\u003e \"Configure System\" -\u003e \"Global Pipeline Library\"  \n1. Add a new library with:  \n**Name:** `pipeline-utils` (or any other name)  \n**Default version:** `\u003cempty\u003e`  \n**Load implicitly:** `[ ]` (unchecked)  \n**Allow override:** `[v]`  \n**Source Code Management:** Point to this repository and give credentials\n\nAfter that, you can include this library from your jenkins pipeline script:\n```groovy\n@Library('pipeline-utils@1.x') _\n```  \n\n### Steps\n\n#### `withCommonPipelineSettings`\nSetup common pipeline settings, including `timestamps` and `timeout`.\n\n**Arguments:**  \n* `timeout` - (Map) the timeout settings. See [basic timeout step documentation](https://jenkins.io/doc/pipeline/steps/workflow-basic-steps/#code-timeout-code-enforce-time-limit) for more details.  \n  (optional, default: `[time: 1, unit: 'HOURS']`)\n\n**Example:**  \n```groovy\nwithCommonPipelineSettings {\n  // Do your magic\n}\n``` \n\n#### `withDockerEx`\nStart a docker extension context.\n  \n**Example:**\n```groovy\nwithDockerEx { dockerEx -\u003e\n  // Assuming there is a docker compose file named 'my-project.yml' in the current directory \n  def myProj = dockerEx.compose('my-project', [file: 'my-project.yml'])\n  // Spin the composition up and print its status\n  myProj.up().ps()\n  // Get the public gateway IP of the composition\n  def myProjIp = myProj.inspectGateway()\n  // Wait for a specific port in the composition to be responsive\n  waitForPort host: myProjIp, port: 8080\n  \n  // Do something with the composition ...\n  \n  // Stop and remove the composition\n  myProj.down()\n}\n```\n*Note-*  \n`withDockerEx` closes its context automatically when the closure ends \n(this includes stopping and removing the composition) \nso calling `myProj.down()` explicitly is not really necessary.\n\n**Requirements:**\n* `docker`\n* `docker-compose`\n\n#### `waitForPort`\nWait for a port to be responsive or for a timeout.\n\n**Arguments:**\n* `host` - (String) the host or IP to check\n* `port` - (int) the port to check\n* `timeout` - (Map) the timeout settings. See [basic timeout step documentation](https://jenkins.io/doc/pipeline/steps/workflow-basic-steps/#code-timeout-code-enforce-time-limit) for more details.  \n  (optional, default: `[time: 20, unit: 'SECONDS']`)\n  \n**Example:**\n```groovy\nwaitForPort host: 'the-host', port: 1234\n```\n\n**Requirements:**\n* `nc` (NetCat)\n\n#### `waitForEndpoint`\nWait for an HTTP endpoint to be responsive. \nIssues a GET request to a given URL endpoint and waits until it responds (no matter the response status). \n\n**Arguments:**\n* `url` - (String) the URL endpoint to check\n* `timeout` - (Map) the timeout settings. See [basic timeout step documentation](https://jenkins.io/doc/pipeline/steps/workflow-basic-steps/#code-timeout-code-enforce-time-limit) for more details.  \n  (optional, default: `[time: 20, unit: 'SECONDS']`)\n* `requestTimeoutSec` - (int) the max time in seconds for each attempt.  \n  (optional, default: `3`)\n\n**Example:**\n```groovy\nwaitForEndpoint url: 'http://www.acme.com'\n```\n\n**Requirements:**\n* `curl`\n\n#### `withUsernamePassword`\nGet username and password from a stored jenkins credentials and use them.\n\n**Arguments:**\n* `credentialsId` - (String) the ID of the credentials to use\n\n**Example:**\n```groovy\nwithUsernamePassword(credentialsId: 'the-creds-id') { username, password -\u003e\n  // Do something with the username and password...\n}\n```\n\n#### `withSecretText`\nGet a secret text by credentials ID and use it.\n\n**Arguments:**\n* `credentialsId` - (String) the ID of the credentials to use\n\n**Example:**\n```groovy\nwithSecretText(credentialsId: 'the-secret-creds-id') { secretText -\u003e\n  // Do something with the secret\n}\n```\n\n#### `withSecretFile`\nGet a secret file path by credentials ID and use it.\n\n**Arguments:**\n* `credentialsId` - (String) the ID of the credentials to use\n\n**Example:**\n```groovy\nwithSecretFile(credentialsId: 'the-secret-creds-id') { secretFilepath -\u003e\n  // Do something with the secret file\n  def secret = readFile(file: secretFilepath)\n}\n```\n\n#### `failAsUnstable`\nDefines a scope in which in case of failure it is reported as `UNSTABLE`.\n\n**Example:**\n```groovy\nfailAsUnstable {\n  // Do something...\n}\n``` \n\n*Note-* This step can be used only in the end of the pipeline. \nFurther steps after the `failAsUnstable` scope is closed will be executed and hence might affect the result status.\n\n#### `shEx`\nExecutes a shell script and returns a map with both stdout and stderr, and also the result status.  \nReturns an `ArrayMap` with the following keys: 'out' (String), 'err' (String), 'status' (int).\n\n**Arguments:**\n* `script` - (String) the script to execute\n\n**Example:**\n```groovy\ndef result = shEx(script: 'java -version')\necho \"out: ${result.get('out')}, err: ${result.get('err')}, status: ${result.get('status')}\"\n```\n\n#### `withRetry`\nExecute a code block and retry in case of an error.  \nIf all attempts fail, the error of the last attempt is thrown.\n\n**Arguments:**  \n* `retries` - (int) the number of retry attempts  \n  (optional, default: `3`)\n\n**Example:**\n```groovy\nwithRetry(retries: 5) {\n  // Do something that might fail\n}\n```\n\n#### `interactiveShell`\nStarts an interactive shell loop where the build execution is paused and the user can interactively \nexecute shell command (implemented using the `sh` basic step). \nTo break the loop enter the `exit` command. The interactive shell has a total timeout of 10 minutes.  \n*Note-* This step shall not be part of a real pipeline. \nIts goal is to assist with pipeline development and debugging.\n\n**Example:**\n```groovy\ninteractiveShell()\n//Pauses the pipeline execution and waits for human interaction\n```\n\n#### `interactiveGroovyShell`\nStarts an interactive groovy shell loop where the build execution is paused and the user can interactively \nexecute groovy script (implemented using the `load` basic step). \nTo break the loop enter `exit` as the script. The interactive groovy shell has a total timeout of 10 minutes.  \n*Note-* This step shall not be part of a real pipeline. \nIts goal is to assist with pipeline development and debugging.  \n**LIMITATION:**  \nWhen using \"Replay\" after using this step, the scripts of the previous run are used.\nTheir content is available in the \"Replay\" page and can be modified from there. \nBut pay attention that the content in the \"Replay\" page overrides the input in the actual run.   \nThe easiest way to workaround it is to use \"Replay\" and add `return` in the beginning of the script. \nThis clears the cached loaded scripts for the next replay.     \n\n**Example:**\n```groovy\ninteractiveGroovyShell()\n//Pauses the pipeline execution and waits for human interaction\n```\n\n### Properties\n\nFollowing properties can be used in the `properties([...])` declaration.  \nFor example:\n```groovy\nproperties([\n  discardOldBuildsProperty()\n])\n```\n\n#### `discardOldBuildsProperty`\n\nConfigure the job to discard old builds according to the following parameters:\n* `numToKeep` - (integer) the maximum number of builds to keep for the job.  \n  (optional, default: `10`)\n* `daysToKeep` - (integer) the maximum number of days to keep a build.  \n  (optional, default: `-1`, i.e. infinite)\n\n**Example:**  \n```groovy\nproperties([\n  discardOldBuildsProperty(numToKeep: 20, daysToKeep: 30)\n])\n```   \n\n  \n----\n  \nLicense  \n\nCopyright 2018 eBay Inc.  \nDeveloper: [Yinon Avraham](https://github.com/yinonavraham)\n\nUse of this source code is governed by an MIT-style\nlicense that can be found in the LICENSE file or at\nhttps://opensource.org/licenses/MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febay%2Fjenkins-pipeline-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febay%2Fjenkins-pipeline-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febay%2Fjenkins-pipeline-utils/lists"}