You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
🚨 Please review the [guidelines for contributing](../blob/master/docs/CONTRIBUTING.md) to this repository.
2
-
3
1
<!--
4
2
Put an `x` into the [ ] to show you have filled the information
5
3
-->
6
4
7
-
### Related issues
5
+
### Related issue
8
6
9
7
<!-- Paste links to the issues that are related/resolved by this PR -->
10
8
<!-- If this PR is related to upstream libraries/API changes, include those links as well -->
@@ -17,14 +15,9 @@ Put an `x` into the [ ] to show you have filled the information
17
15
18
16
<!-- Describe how did you test your changes. If you don't have a Jira Cloud instance to test on, ask the maintainer to grant access to https://jenkins-jira-plugin.atlassian.net/ -->
19
17
18
+
-[ ] I have updated/added relevant documentation in the `docs/` directory
19
+
-[ ] I have verified that the Code Coverage is not lower than before / that all the changes are covered as needed
20
20
-[ ] I have tested my changes with a Jira Cloud / Jira Server
21
21
22
-
<!-- provide the flavor (Jira Cloud / Jira Server) and the version -->
23
-
24
-
-[ ] I have verified that the Code Coverage is not lower than before / that all the changes are covered as needed
25
-
26
-
### Checklist
27
-
28
-
-[ ] Make sure you are requesting the pull request from a _custom branch_ and **not your master/main branch**
29
-
-[ ] Ensure that the pull request title represents the desired changelog entry
30
-
-[ ] Apply relevant PR labels, at least one of `feature` or `bugfix` or `documentation`
22
+
<!-- provide here the flavor (Jira Cloud / Jira Server) and the version -->
This plugin integrates with Jenkins the [Atlassian Jira Software](http://www.atlassian.com/software/jira/) (both Cloud and Server versions). For bug reports, see [bugs](https://issues.jenkins-ci.org/issues/?filter=14761) or [all open issues](https://issues.jenkins-ci.org/issues/?filter=14956). For documentation, see [official plugin site](https://plugins.jenkins.io/jira).
9
+
See plugin documentation at [https://jenkinsci.github.io/jira-plugin/](https://jenkinsci.github.io/jira-plugin/)
12
10
13
11
## i18n
14
12
15
-
This plugin is using [CrowdIn platform](https://jenkins.crowdin.com/jira-plugin) as the frontend to manage translations. If you would like to contribute translation of this plugin in your language, you're most than welcome! For details, see [jenkins.io CrowdIn introduction](https://www.jenkins.io/doc/developer/crowdin/translating-plugins/).
For plugin compatibility with [Pipeline plugin](https://github.com/jenkinsci/pipeline-plugin), see [COMPATIBILITY](COMPATIBILITY.md).
29
-
30
-
## Configuring the plugin
31
-
32
-
### Configuration for Jira Cloud
33
-
34
-
With Atlassian Jira Cloud, it's not possible to create a user without an email, so you need to create API token that will be used as a _service user_ by Jenkins to execute API calls to Jira Cloud - follow [Atlassian API tokens documentation](https://confluence.atlassian.com/cloud/api-tokens-938839638.html)
35
-
36
-
Then create a global Jenkins credential:
37
-
38
-
- put _Atlassian ID email_ as username
39
-
-_API token_ as password.
40
-
41
-
You can check if your API token works correctly by getting a correct JSON issue response with this command (where TEST-1 is an example issue in your project):
42
-
43
-
```bash
44
-
curl -X GET -u <email>:<API token> -H "Content-Type: application/json" https://<YourCloudInstanceName>.atlassian.net/rest/api/latest/issue/TEST-1
45
-
```
46
-
47
-
Also make sure that CAPTCHA is not triggered for your user as this will
48
-
prevent the API token to work - see [CAPTCHA section in Atlassian REST API documentation.](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-basic-authentication/)
Use to disable resolving user email from Jira usernames. Currently there is no option for this in UI.
55
-
56
-
### Using Jira REST API
57
-
58
-
This plugin has an optional feature to update Jira issues with a back pointer to Jenkins build pages. This allows the submitter and watchers to quickly find out which build they need to pick up to get the fix.
If you also want to use this feature, you need to supply a valid user id/password. If you need the comment only to be visible to a certain Jira group, e.g. _Software Development_, enter the groupname.
73
-
74
-
Now you also need to configure jobs. I figured you might not always have write access to the Jira (say you have a Jenkins build for one of the Apache commons project that you depend on), so that's why this is optional.
75
-
76
-
The following screen shows how a Jira issue is updated:
77
-
78
-
79
-
80
-
By taking advantages of Jenkins' [fingerprint](https://wiki.jenkins.io/display/JENKINS/Fingerprint) feature, when your other projects that depend on this project pick up a build with a fix, those build numbers can also be recorded in Jira.
81
-
82
-
This is quite handy when a bug is fixed in one of the libraries, yet the submitter wants a fix in a different project. This happens often in my work, where a bug is reported against JAX-WS but the fix is in JAXB.
83
-
84
-
For curious mind, see [this thread for how this works behind the scene](http://jenkins.361315.n4.nabble.com/How-can-does-Hudson-Jira-integration-works-td374680.html).
85
-
86
-
### Referencing Jira Release version
87
-
88
-
To reference Jira Release versions in your build, you can pull these
89
-
releases directly from Jira by adding the Jira Release Version
90
-
Parameter.
23
+
This plugin uses [CrowdIn platform](https://jenkins.crowdin.com/jira-plugin) as the frontend to manage translations. If you would like to contribute translation of this plugin in your language, you're most welcome! For details, see [jenkins.io CrowdIn introduction](https://www.jenkins.io/doc/developer/crowdin/translating-plugins/).
91
24
92
-
This can be useful for generating release notes, trigerring
You can also generate release notes to be used during your build. These notes can be retrieved from an environment variable. See the [Maven Project Plugin](https://wiki.jenkins.io/display/JENKINS/Maven+Project+Plugin) for
99
-
the environment variables found within the POM.
100
-
101
-
102
-
After your build has run, you can also have the plugin mark a release as resolved. This typically will be a release you specified in your Build Parameters.
**Note:** As a rule of thumb, **you should be always using a service account** (instead of a personal account) to integrate Jenkins with Jira.
114
-
115
-
Make sure that the Jira user used by Jenkins has enough permissions to execute its actions. You can do that via Jira Permission Helper tool.
116
-
117
-
- For creating Jira issues, the user has to be able to Create Issues in the specified project
118
-
- If you additionally enter assignee or component field values, make sure that:
119
-
- both of the fields are assigned to the corresponding Jira Screen
120
-
- the Jira user is Assignable in the project
121
-
- the Jenkins Jira user can Assign issues
122
-
123
-
### Related Resources
124
-
125
-
- Check also the Marvelution [Jenkins Integration for Jira](https://www.marvelution.com/products/jenkins-integration-for-jira/) which provides a two-way solution (Jenkins-\>Jira and Jira-\>Jenkins)
126
-
- For Jira Workflow (Pipeline) plugin compatibility see [COMPATIBILITY.md](COMPATIBILITY.md)
127
-
128
-
#### Common issues
129
-
130
-
##### Jenkins<>Jira SSL connectivity problems
131
-
132
-
If you encounter stacktrace like this:
133
-
134
-
```stacktrace
135
-
Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
136
-
```
137
-
138
-
make sure the JRE/JDK that Jenkins master is running (or the Jenkins slaves are running) contain the valid CA chain certificates that Jira is running with.
139
-
You can test it using this [SSLPoke.java class](https://gist.github.com/warden/e4ef13ea60f24d458405613be4ddbc51):
We all love Open Source, but... Open Source Software relies on contributions of fellow developers. Please contribute by [opening Pull Requests](#contributing) or if you are not a developer, consider sponsoring one of the maintainers.
161
-
162
-
### Contributing
163
-
164
-
New feature proposals and bug fix proposals should be submitted as [Pull Requests](https://help.github.com/articles/creating-a-pull-request). When adding new features please make sure that they support Jenkins Pipeline Plugin - see [COMPATIBILITY.md](https://github.com/jenkinsci/pipeline-plugin/blob/master/COMPATIBILITY.md) for more information
165
-
166
-
### Tests
25
+
## Contributing
167
26
168
27
There have been many developers involved in the development of this plugin and there are many downstream users who depend on it. Tests help us assure that we're delivering a reliable plugin and that we've communicated our intent to other developers in a way that they can detect when they run tests.
169
28
170
-
- each change should be covered by appropriate unit tests.
171
-
- in case it is not testable via a unit test, it should be tested against a real Jira instance - possibly both Jira Server and Jira Cloud. There is a [Jira Cloud test instance](https://jenkins-jira-plugin.atlassian.net/) that we are using for testing the plugin releases - let us know in the Pull Request in case you need access for testing.
172
-
173
-
## Maintainers
174
-
175
-
See [MAINTAINERS](MAINTAINERS.md) for some useful info.
29
+
- each change should be covered by appropriate unit tests
30
+
- in case it is not testable via a unit test, it should be tested against a real Jira instance - possibly both Jira Server and Jira Cloud. There is a [Jira Cloud test instance](https://jenkins-jira-plugin.atlassian.net/) that we are using for testing the plugin releases - let us know in the Pull Request in case you need access for testing
This plugin integrates with Jenkins the [Atlassian Jira Software](http://www.atlassian.com/software/jira/) (both Cloud and Server versions).
4
+
5
+
## Configuration
6
+
7
+
!> **Jira Cloud** does not support Bearer Authentication
8
+
9
+
To integrate Jenkins with Atlassian Jira Cloud, you need to use an API token as a _service user_. Jira Cloud requires an email address for all users, so you cannot create a user without one.
10
+
11
+
### Steps
12
+
13
+
1.**Create an API Token**
14
+
15
+
Follow the [Atlassian API tokens documentation](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) to generate a new API token.
16
+
17
+
2.**Add a Global Jenkins Credential**
18
+
19
+
-**Username:** Your Atlassian ID email address
20
+
-**Password:** The API token you created
21
+
22
+
3.**Test Your API Token**
23
+
24
+
Verify your API token by running the following command (replace `<email>`, `<API token>`, `<YourCloudInstanceName>`, and `TEST-1` with your details):
25
+
26
+
```bash
27
+
curl -X GET -u <email>:<API token> -H "Content-Type: application/json" \
A successful response returns the issue details in JSON format.
32
+
33
+
4. **Check for CAPTCHA**
34
+
35
+
Ensure that CAPTCHA is **not** triggered foryour user, as this will prevent the API token from working. For more information, see the [CAPTCHA sectionin Atlassian REST API documentation](https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-basic-authentication/).
36
+
37
+
5. **Test Connection**
38
+
39
+
Finally, use the **Validate Settings** button on the plugin configuration page, to see if it can connect to the Jira instance.
First, check [Github Issues](https://github.com/jenkinsci/jira-plugin/issues) for already reported bugs.
47
+
48
+
Then, Contribute or Sponsor!
49
+
50
+
We all love Open Source, but... Open Source Software relies on contributions of fellow developers. Please contribute by [opening Pull Requests](#contributing) or if you are not a developer, consider sponsoring one of the maintainers - see ["Sponsor this project" section.](https://github.com/jenkinsci/jira-plugin)
This plugin has an optional feature to update Jira issues with a back pointer to Jenkins build pages. This allows the submitter and watchers to quickly find out which build they need to pick up to get the fix.
If you also want to use this feature, you need to supply a valid user id/password. If you need the comment only to be visible to a certain Jira group, e.g. _Software Development_, enter the groupname.
20
+
21
+
Now you also need to configure jobs. I figured you might not always have write access to the Jira (say you have a Jenkins build for one of the Apache commons project that you depend on), so that's why this is optional.
22
+
23
+
The following screen shows how a Jira issue is updated:
24
+
25
+
26
+
27
+
By taking advantages of Jenkins' [fingerprint](https://wiki.jenkins.io/display/JENKINS/Fingerprint) feature, when your other projects that depend on this project pick up a build with a fix, those build numbers can also be recorded in Jira.
28
+
29
+
This is quite handy when a bug is fixed in one of the libraries, yet the submitter wants a fix in a different project. This happens often in my work, where a bug is reported against JAX-WS but the fix is in JAXB.
30
+
31
+
For curious mind, see [this thread for how this works behind the scene](http://jenkins.361315.n4.nabble.com/How-can-does-Hudson-Jira-integration-works-td374680.html).
32
+
33
+
### Referencing Jira Release version
34
+
35
+
To reference Jira Release versions in your build, you can pull these
36
+
releases directly from Jira by adding the Jira Release Version
37
+
Parameter.
38
+
39
+
This can be useful for generating release notes, trigerring
You can also generate release notes to be used during your build. These notes can be retrieved from an environment variable. See the [Maven Project Plugin](https://wiki.jenkins.io/display/JENKINS/Maven+Project+Plugin) for
46
+
the environment variables found within the POM.
47
+
48
+
49
+
After your build has run, you can also have the plugin mark a release as resolved. This typically will be a release you specified in your Build Parameters.
0 commit comments