https://github.com/jenkinsci/pipeline-gitstatuswrapper-plugin
https://github.com/jenkinsci/pipeline-gitstatuswrapper-plugin
github jenkins-pipeline
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jenkinsci/pipeline-gitstatuswrapper-plugin
- Owner: jenkinsci
- License: mit
- Created: 2019-04-04T23:59:44.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-12T16:50:25.000Z (about 3 years ago)
- Last Synced: 2025-01-30T06:04:51.087Z (12 months ago)
- Topics: github, jenkins-pipeline
- Language: Java
- Homepage: https://plugins.jenkins.io/pipeline-gitstatuswrapper/
- Size: 106 KB
- Stars: 7
- Watchers: 2
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Pipeline Git Status Wrapper Plugin
[](https://ci.jenkins.io/job/Plugins/job/pipeline-gitstatuswrapper-plugin/job/master/)
This plugin lets you wrap a block of commands with `gitStatusWrapper`, which handles updating GitHub statuses automatically!
✅ gitStatusWrapper makes your life easier! ✅
```
stage('EZPZ Updates') {
steps {
gitStatusWrapper(credentialsId: 'github-token', gitHubContext: 'Status', description: 'Validating') {
sh "./do_stuff.sh"
}
}
}
```
💀🚫 Stop calling githubNotify 3+ times 🚫💀
```
stage('Annoying status updates') {
script {
try {
githubNotify(credentialsId: 'github-token', context: 'Status', description: 'Validating', status: 'PENDING')
sh "./do_stuff.sh"
githubNotify(credentialsId: 'github-token', context: 'Status', description: 'Validating', status: 'SUCCESS')
}
catch (Exception e) {
githubNotify(credentialsId: 'github-token', gitHubContext: 'Status', description: 'Validating', status: 'FAILURE')
}
}
}
```
The available parameters are:
| Parameter | Description |
| ------------- |:-------------|
| _credentialsId_ | The id of the github's credentials to use, must be of type UsernameAndPassword and contain the password or a personal access token. |
| _description_ | A short description for the status |
| _gitHubContext_ | The status context. GitHub uses the context to differentiate statuses |
| _sha_ | The sha that identifies the commit to set the status on |
| _repo_ | The repo that owns the commit we want to set the status on |
| _account_ | The account that owns the repository |
| _gitApiUrl_ | GitHub Enterprise instance API URL |
| _targetUrl_ | The targetUrl for the notification|
| _successDescription_ | A short description for the status if wrapped steps succeed _Can be Regex_ |
| _failureDescription_ | A short description for the status if wrapped steps fail. _Can be Regex_ |
# Inferring parameter values and defaults
## Inferring
Instead of specify all your parameters, this step will try to infer some of them if they
are not provided. The parameters that can be inferred are:
| Parameter |
| ------------- |
| _credentialsId_ |
| _sha_ |
| _repo_ |
| _account_ |
*Note that infer will only work if you have Git Build Data. If you find problems when inferring, specify the
required data explicitly. (You can access this data on your Jenkinsfile by using the appropriate env variables)*
## Defaults
The plugin will default some parameters as a convenience. The following are defaults:
| Parameter | Default |
| ------------- |:--------|
| _gitApiUrl_ | `https://api.github.com` |
| _gitHubContext_ | "gitStatusWrapper" |
| _targetUrl_ | The jenkins project build URL |
| _description_ | "" |
# Regex descriptions
_Since 1.1.0_
You can now specify a regex pattern for the *successDescription* and *failureDescription* parameters. This regex will be used to match against the entire build log.
It will use the first group match as the description for the respective status message.
To enable, wrap your regex with '`/`' to have it evaluted as regex.
Example:
```
gitStatusWrapper(credentialsId: 'github-token', description: 'Pending description', gitHubContext: 'jenkins/appTests',
successDescription='/^buildVersion=(.*)$/') {
sh '''
echo "buildVersion=$(./my_script.sh)"
'''
}
```
# Examples
## Explicit settings
Jenkinsfile:
```
pipeline {
agent any
stages {
stage('Run tests') {
steps {
gitStatusWrapper(credentialsId: 'github-token', description: 'Running Tests', gitHubContext: 'jenkins/appTests',
sha: 'ffg2ab', repo: 'my-repo', account: 'myaccount', gitApiUrl: 'https://[github.mycorp.com]/api/',
targetUrl: 'https://[myTestingSite].me') {
sh "./get_test_data.sh"
sh "./run_my_tests.sh"
}
}
}
}
}
```
Output:
```
...
[Pipeline] gitStatusWrapper
[GitStatusWrapper] - Setting PENDING status for jenkins/appTests on commit ffg2ab130985981ac0735f9789e19750f7200bd6
[Pipeline] {
[Pipeline] sh
+ ./get_test_data.sh
success
[Pipeline] sh
+ ./run_my_tests.sh
ok
ok
ok
[Pipeline] }
[GitStatusWrapper] - Setting SUCCESS status for jenkins/appTests on commit ffg2ab130985981ac0735f9789e19750f7200bd6
...
```
## Inferring properties and default values
Pipeline job with `Jenkinsfile from SCM`
```
pipeline {
agent any
stages {
stage('Run tests') {
steps {
gitStatusWrapper(credentialsId: 'github-token') {
sh "./get_test_data.sh"
sh "./run_my_tests.sh"
}
}
}
}
}
```
Output:
```
...
[Pipeline] gitStatusWrapper
[GitStatusWrapper] - Setting PENDING status for gitStatusWrapper on commit ffg2ab130985981ac0735f9789e19750f7200bd6
[Pipeline] {
[Pipeline] sh
+ ./get_test_data.sh
success
[Pipeline] sh
+ ./run_my_tests.sh
ok
ok
ok
[Pipeline] }
[GitStatusWrapper] - Setting SUCCESS status for gitStatusWrapper on commit ffg2ab130985981ac0735f9789e19750f7200bd6
...
```
## Example of failure
Pipeline job with `Jenkinsfile from SCM`
```
pipeline {
agent any
stages {
stage('Run tests') {
steps {
gitStatusWrapper(credentialsId: 'github-token') {
sh "./get_test_data.sh"
sh "./run_my_tests.sh"
}
}
}
}
}
```
Output:
```
...
[Pipeline] gitStatusWrapper
[GitStatusWrapper] - Setting PENDING status for gitStatusWrapper on commit ffg2ab130985981ac0735f9789e19750f7200bd6
[Pipeline] {
[Pipeline] sh
+ ./get_test_data.sh
success
[Pipeline] sh
+ ./run_my_tests.sh
ok
ok
! failure com.project.TestCalcs.java !
[Pipeline] }
[GitStatusWrapper] - Setting Failure status for gitStatusWrapper on commit ffg2ab130985981ac0735f9789e19750f7200bd6
...
```
# No pipeline? No Problem
This plugin also includes a builder plugin, so you can wrap your freestyle projects with the same goodness as the pipeline version.
## Users
Use the plugin? Let us know to get your logo here!
---------Created and Used by---------
---------------------------------------