diff options
Diffstat (limited to 'doc/integration/jira/troubleshooting.md')
| -rw-r--r-- | doc/integration/jira/troubleshooting.md | 99 |
1 files changed, 69 insertions, 30 deletions
diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index cf637484b5f..6c8b49b4159 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -1,18 +1,14 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Troubleshooting Jira **(FREE ALL)** +# Troubleshooting Jira issue integration **(FREE ALL)** -This page contains a list of common issues you might encounter when working with Jira integrations. +This page contains a list of common issues you might encounter when working with the [Jira issue integration](configure.md). -## Jira issue integration - -When working with the [Jira issue integration](configure.md), you might encounter the following issues. - -### GitLab cannot link to a Jira issue +## GitLab cannot link to a Jira issue When you mention a Jira issue ID in GitLab, the issue link might be missing. [`sidekiq.log`](../../administration/logs/index.md#sidekiq-logs) might contain the following exception: @@ -23,7 +19,7 @@ No Link Issue Permission for issue 'JIRA-1234' To resolve this issue, ensure the Jira user you created for the [Jira issue integration](configure.md) has permission to link issues. -### GitLab cannot comment on a Jira issue +## GitLab cannot comment on a Jira issue If GitLab cannot comment on a Jira issue, ensure the Jira user you created for the [Jira issue integration](configure.md) has permission to: @@ -35,10 +31,13 @@ If you [restrict IP addresses for Jira access](https://support.atlassian.com/sec For the root cause, check the [`integrations_json.log`](../../administration/logs/index.md#integrations_jsonlog) file. When GitLab tries to comment on a Jira issue, an `Error sending message` log entry might appear. -In GitLab 16.1 and later, when an error occurs, the [`integrations_json.log`](../../administration/logs/index.md#integrations_jsonlog) file contains `client_*` keys in the outgoing API request to Jira. +In GitLab 16.1 and later, when an error occurs, the `integrations_json.log` file contains `client_*` keys in the outgoing API request to Jira. You can use the `client_*` keys to check the [Atlassian API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-group-issues) for why the error has occurred. -In the following example, Jira responds with a `404` because the Jira issue `ALPHA-1` does not exist: +In the following example, Jira responds with a `404 Not Found`. This error might happen if: + +- The Jira user you created for the Jira issue integration does not have permission to view the issue. +- The Jira issue ID you specified does not exist. ```json { @@ -53,7 +52,19 @@ In the following example, Jira responds with a `404` because the Jira issue `ALP } ``` -### GitLab cannot close a Jira issue +For more information about returned status codes, see the [Jira Cloud platform REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-get-response). + +### Using `curl` to verify access to a Jira issue + +To verify that a Jira user can access a specific Jira issue, run the following script: + +```shell +curl --verbose --user "$USER:$API_TOKEN" "https://$ATLASSIAN_SUBDOMAIN.atlassian.net/rest/api/2/issue/$JIRA_ISSUE" +``` + +If the user can access the issue, Jira responds with a `200 OK` and the returned JSON includes the Jira issue details. + +## GitLab cannot close a Jira issue If GitLab cannot close a Jira issue: @@ -64,28 +75,54 @@ If GitLab cannot close a Jira issue: - Check the Jira issue resolution field is not set. - Check the issue is not struck through in Jira lists. -### CAPTCHA after failed sign-in attempts +## CAPTCHA after failed sign-in attempts + +CAPTCHA might be triggered after consecutive failed sign-in attempts. +These failed attempts might lead to a `401 Unauthorized` when testing the Jira issue integration settings. +If CAPTCHA has been triggered, you cannot use the Jira REST API +to authenticate with the Jira site. + +To resolve this issue, sign in to your Jira instance and complete the CAPTCHA. + +## Integration does not work for an imported project -CAPTCHA might be triggered after several consecutive failed sign-in attempts, -which might lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you can't use the Jira REST API to -authenticate with the Jira site. +The Jira issue integration might not work for a project that has been imported. +For more information, see [issue 341571](https://gitlab.com/gitlab-org/gitlab/-/issues/341571). -To fix this error, sign in to your Jira instance -and complete the CAPTCHA. +To resolve this issue, disable and then re-enable the integration. -### Integration does not work for an imported project +## `certificate verify failed` when testing the integration settings -There is a [known bug](https://gitlab.com/gitlab-org/gitlab/-/issues/341571) -where the Jira integration sometimes does not work for a project that has been imported. -As a workaround, disable the integration and then re-enable it. +When testing the Jira issue integration settings, you might get the following error: -### Change all Jira projects to instance-level or group-level values +```plaintext +Connection failed. Check your integration settings. SSL_connect returned=1 errno=0 peeraddr=<jira.example.com> state=error: certificate verify failed (unable to get local issuer certificate) +``` + +This error might also appear in the [`integrations_json.log`](../../administration/logs/index.md#integrations_jsonlog) file: + +```json +{ + "severity":"ERROR", + "integration_class":"Integrations::Jira", + "message":"Error sending message", + "exception.class":"OpenSSL::SSL::SSLError", + "exception.message":"SSL_connect returned=1 errno=0 peeraddr=x.x.x.x:443 state=error: certificate verify failed (unable to get local issuer certificate)", +} +``` + +The error occurs because the Jira certificate is not publicly trusted or the certificate chain is incomplete. +Until this issue is resolved, GitLab does not connect to Jira. + +To resolve this issue, see +[Common SSL errors](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html#common-ssl-errors). + +## Change all Jira projects to instance-level or group-level values WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. -#### Change all projects instance wide +### Change all projects on the instance To change all Jira projects to use instance-level integration settings: @@ -116,7 +153,7 @@ To change all Jira projects to use instance-level integration settings: 1. Modify and save the instance-level integration from the UI to propagate the changes to all group-level and project-level integrations. -#### Change all projects in a group +### Change all projects in a group To change all Jira projects in a group (and its subgroups) to use group-level integration settings: @@ -126,7 +163,7 @@ To change all Jira projects in a group (and its subgroups) to use group-level in def reset_integration(target) integration = target.integrations.find_by(type: Integrations::Jira) - return if integration.nil? # Skip if the project has no Jira integration + return if integration.nil? # Skip if the project has no Jira issue integration return unless integration.inherit_from_id.nil? # Skip integrations that are already inheriting default_integration = Integration.default_integration(integration.type, target) @@ -152,7 +189,7 @@ To change all Jira projects in a group (and its subgroups) to use group-level in end ``` -### Update the Jira integration password for all projects +## Update the Jira issue integration password for all projects WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. @@ -185,7 +222,7 @@ If that's the case, ensure the [**Due date** field is visible for issues](https: ### `An error occurred while requesting data from Jira` -When you try to view the Jira issue list in GitLab, you might see this message: +When you try to view the Jira issue list in GitLab, you might get this message: ```plaintext An error occurred while requesting data from Jira @@ -202,7 +239,7 @@ Your Jira project key must not have [restricted words and characters](https://co ### Jira credentials not allowed to access the data -When you try to view the Jira issue list in GitLab, you might see this message: +When you try to view the Jira issue list in GitLab, you might get this message: ```plaintext The credentials for accessing Jira are not allowed to access the data. Check your Jira integration credentials and try again. @@ -233,3 +270,5 @@ Both methods should return a JSON response: - `total` gives a count of the issues that match the Jira project key. - `issues` contains an array of the issues that match the Jira project key. + +For more information about returned status codes, see the [Jira Cloud platform REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-get-response). |