{"id":25257311,"url":"https://github.com/zowe/jenkins-library","last_synced_at":"2025-10-27T02:31:52.590Z","repository":{"id":33348458,"uuid":"152270012","full_name":"zowe/jenkins-library","owner":"zowe","description":"Jenkins Pipeline Library","archived":false,"fork":false,"pushed_at":"2022-01-07T19:07:21.000Z","size":3056,"stargazers_count":47,"open_issues_count":13,"forks_count":37,"subscribers_count":5,"default_branch":"master","last_synced_at":"2023-03-02T07:25:43.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zowe.github.io/jenkins-library","language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zowe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-09T14:52:51.000Z","updated_at":"2023-01-19T02:11:38.000Z","dependencies_parsed_at":"2022-08-07T20:30:44.399Z","dependency_job_id":null,"html_url":"https://github.com/zowe/jenkins-library","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fjenkins-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fjenkins-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fjenkins-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fjenkins-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zowe","download_url":"https://codeload.github.com/zowe/jenkins-library/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238424196,"owners_count":19470011,"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":[],"created_at":"2025-02-12T06:38:51.644Z","updated_at":"2025-10-27T02:31:51.971Z","avatar_url":"https://github.com/zowe.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jenkins Pipeline Shared Library\n\nThis repository holds shared library for Jenkins Pipeline\n\n## Import Library\n\nThe Jenkins library requires sophisticated operation on Jenkins objects, which requires to be setup as `Global Pipeline Libraries` to avoid extra `In-process Script Approval`.\n\n### Configure Jenkins Pipeline Job\n\n- In The `Manage Jenkins` - `Configure System` section, find `Global Pipeline Libraries` and click `ADD`.\n  - Give the library a name, for example, `jenkins-library`. Set `Default version` to `master`.\n  - For `Retrieval method`, choose `Modern SCM`.\n    - For `Source Code Management` section, choose `GitHub`.\n    - Configure github connection to this repository\n\n### Import Library in Jenkinsfile\n\nIf you didn't check `Load implicitly` when configuring the job, you need to use `@Library` to import it.\n\nIn your Jenkinsfile, you can add `def lib = library(\"jenkins-library\").org.zowe.jenkins_shared_library\n` on top of the file to import library.\n\nThen you can use any classes/methods defined in the library. For example:\n\n```\ngithub = lib.scm.GitHub.new(this)\ngithub.init([...])\ngithub.commit('my test')\n```\n\n## Run Tests\n\nTo start test, run gradle command `gradle test`.\n\n## Generate Documentation\n\nRun gradle command `gradle groovydoc` to generate documentation.\n\n## Relase Process Design\n\nAll below scenarios are based on `master` version `v2.3.4` as example, timestamp string example is `20190101000000`.\n\n### Things We Want to Do\n\n- Allow every branches to publish artifacts for debugging purpose.\n- Release is only performed when we want to, so it's always started manually.\n\n### Special Notes\n\n- The release stage doesn't have option to choose MINOR/MAJOR/SPECIFIC version bump. Those works should be handled in GitHub with Pull Requests.\n- The relase stage doesn't have manual approval option. We assume everything pushed into `master` branch is for release purpose and have been reviewed by Pull Request reviewers.\n\n### Release Options\n\n- For each pipeline, we have 2 build parameters are only available to branches which can do a `release`:\n  - `Perform Release`: boolean, default is _false_.\n  - `Pre-Release String`: string, default is _empty_. This parameter will only be used if `Perform Release` is _true_. This parameter is required if the release is not happened on `master` or `v?.x/master` branch.\n- By default, only `master`, `v?.x/master`, `staging` and `v?.x/staging` branches can do a release. This can be changed by `pipeline.addReleaseBranches(...branches)` or `pipeline.setReleaseBranches(...branches)`.\n- For NPM packages, each branch can have a npm publish tag name when performaing release build. By default, `master`'s tag is `latest`, `staging`'s tag is `dev`. For branches do not have publish tag defined, or branches is not in release build, npm publish will use default `snapshot` tag name, and the version will have normalized branch name included. For example, `staging` branch **non-release** build will generate a version `v2.3.4-staging-snapshot.20190101000000` release on `snapshot` npm tag. `staging` branch **release** build will generate a version `v2.3.4-dev.20190101000000` release on `dev` tag. And a branch `feature/lts` build will generate a version `v2.3.4-feature-lts-snapshot.20190101000000` release on `snapshot` tag.\n- For pax/zip packages, each branch can also have a release tag name. By default, `master`'s tag is 'snapshot'. If it's not defined, artifactory publish will use branch name as tag name. For example, `master` **non-release** build will publish artifact to `libs-snapshot-local/org/zowe/\u003ccomponent\u003e/2.3.4-snapshot/` and **release** build will publish to `libs-release-local/org/zowe/\u003ccomponent\u003e/2.3.4/`. `staging` **non-release** build will publish artifact to `libs-snapshot-local/org/zowe/\u003ccomponent\u003e/2.3.4-staging/` and **release** build will publish to `libs-release-local/org/zowe/\u003ccomponent\u003e/2.3.4-rc1/`, the `rc1` is the pre-release string which is required.\n\n### Pipeline Build Scenarios\n\n- **Scenario #1**\n  - Build on `master` with default parameter values (`Perform Release` = _false_, `Pre-Release String` = _empty_)\n    - for npm package, it will be published to `npm-local-release` as `v2.3.4-snapshot-master.20190101000000` with npm tag `snapshot`.\n    - for pax/zip(gradle) package, it will be published to `libs-snapshot-local/org/zowe/\u003ccomponent\u003e/2.3.4-snapshot/` as `\u003ccomponent\u003e-2.3.4-snapshot.20190101000000.(pax|zip)`.\n  - No github tag will be created.\n  - No version bump will be performed on GitHub.\n- **Scenario #2**\n  - Build on `master` with (`Perform Release` = _true_, `Pre-Release String` = _beta.1_)\n    - for npm package, it will be published to `npm-local-release` as `v2.3.4-beta.1` with npm tag `snapshot`.\n    - for pax/zip(gradle) package, it will be published to `libs-release-local/org/zowe/\u003ccomponent\u003e/2.3.4/` as `\u003ccomponent\u003e-2.3.4-beta.1.(pax|zip)`.\n  - Github tag `v2.3.4-beta.1` will be created.\n  - No version bump will be performed on GitHub after release.\n- **Scenario #3**\n  - Build on `master` with (`Perform Release` = _true_, `Pre-Release String` = _empty_)\n    - for npm package, it will be published to `npm-local-release` as `v2.3.4` with npm default tag `latest`.\n    - for pax/zip(gradle) package, it will be published to `libs-release-local/org/zowe/\u003ccomponent\u003e/2.3.4/` as `\u003ccomponent\u003e-2.3.4.(pax|zip)`.\n  - Github tag `v2.3.4` will be created.\n  - A **PATCH** level version bump will be performed on GitHub. This is to avoid release the same version again. So after version bump, `master` has version of `2.4.0`, and a commit can be seen from github commit history. This commit should be merged/cherry-picked back to `staging`.\n- **Scenario #dev-1**\n  - Build on `staging` which **IS** a release branch with default parameter values (`Perform Release` = _false_, `Pre-Release String` = _empty_)\n    - for npm package, it will be published to `npm-local-release` as `v2.3.4-staging-snapshot.20190101000000` with npm tag `snapshot`.\n    - for pax/zip(gradle) package, it will be published to `libs-snapshot-local/org/zowe/\u003ccomponent\u003e/2.3.4-staging/` as `\u003ccomponent\u003e-2.3.4-staging.20190101000000.(pax|zip)`.\n  - No github tag will be created.\n  - No version bump will be performed on GitHub.\n- **Scenario #dev-2**\n  - Build on `staging` which **IS** a release branch with default parameter values (`Perform Release` = _true_, `Pre-Release String` = _rc.1_)\n    - for npm package, it will be published to `npm-local-release` as `v2.3.4-rc.1` with npm tag `dev`.\n    - for pax/zip(gradle) package, it will be published to `libs-snapshot-local/org/zowe/\u003ccomponent\u003e/2.3.4-staging/` as `\u003ccomponent\u003e-2.3.4-staging.20190101000000.(pax|zip)`.\n  - No github tag will be created.\n  - No version bump will be performed on GitHub after release.\n- **Scenario #dev-3**\n  - Build on `staging` which **IS** a release branch with default parameter values (`Perform Release` = _true_, `Pre-Release String` = _empty_)\n  - Build will be rejected because pre-release string is empty.\n- **Typical Scenario**\n  - A NPM project has `latest`, `dev`, `v1-latest` and `v1-dev` tags. `v1` is a LTS version, current `master` is on `v2.3.4`.\n  - There are 4 branches can do a release, the branch-tag mappings are:\n    - `master` - `latest`\n    - `staging` - `dev`\n    - `v1.x/master` - `v1-latest`\n    - `v1.x/staging` - `v1-dev`\n\n### Release Scenarios\n\n- **Release v2.3.4-rc.1**\n  - Build `staging` with (`Perform Release` = _true_, `Pre-Release String` = _rc.1_).\n  - Or build `master` with (`Perform Release` = _true_, `Pre-Release String` = _rc.1_), **not suggested**.\n- **Release v2.3.4**\n  - Build `master` with (`Perform Release` = _true_, `Pre-Release String` = _empty_).\n- **Release v2.4.0**\n  - Make a commit on `staging` to upgrade version to `2.4.0`.\n  - Build `staging` with (`Perform Release` = _true_, `Pre-Release String` = _rc.1_), we should have `v2.4.0-rc.1`.\n  - Create a Pull Request to merge `staging` into `master`. After merged, `master` should have a version definition of `2.4.0` instead of `2.3.4`.\n  - build master with (`Perform Release` = _true_, `Pre-Release String` = _empty_), we should have `v2.4.0`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzowe%2Fjenkins-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzowe%2Fjenkins-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzowe%2Fjenkins-library/lists"}