Merge branch 'docs-jenkins-troubleshooting' into 'master'

Add troubleshooting steps to Jenkins documentation

See merge request gitlab-org/gitlab-ee!9082

doc/integration/jenkins.md

@@ -60,15 +60,19 @@ Go to Manage Jenkins -> Configure System and scroll down to the 'GitLab' section
 Enter the GitLab server URL in the 'GitLab host URL' field and paste the API token
 copied earlier in the 'API Token' field.
 
+For more information, see GitLab Plugin documentation about 
+[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication)
+
 ![Jenkins GitLab plugin configuration](jenkins_gitlab_plugin_config.png)
 
 ## Configure a Jenkins project
 
-Follow the GitLab Plugin documentation under the
-[Using it With a Job](https://github.com/jenkinsci/gitlab-plugin#using-it-with-a-job)
-heading. You *do not* need to complete instructions under the 'GitLab
-Configuration (>= 8.0)'. Be sure to check the 'Use GitLab CI features' checkbox
-as described under the 'GitLab Configuration (>= 8.1)'.
+Follow the GitLab Plugin documentation about [Jenkins Job Configuration](https://github.com/jenkinsci/gitlab-plugin#jenkins-job-configuration).
+
+NOTE: **Note:**
+Be sure to include the steps about [Build status configuration](https://github.com/jenkinsci/gitlab-plugin#build-status-configuration).
+The 'Publish build status to GitLab' post-build step is required to view 
+Jenkins build status in GitLab Merge Requests. 
 
 ## Configure a GitLab project
 
@@ -108,3 +112,18 @@ All steps are implemented using AJAX requests on the merge request page.
 2. Your project service will do a (JSON) query to a URL of the CI tool with the SHA1 of the commit.
 3. The project service builds this URL and payload based on project service settings and knowledge of the CI tool.
 4. The response is parsed to give a response in GitLab (success/failed/pending).
+
+## Troubleshooting
+
+### Error in merge requests - "Could not connect to the CI server"
+
+This integration relies on Jenkins reporting the build status back to GitLab via
+the [Commit Status API](../api/commits.md#commit-status). 
+
+The error 'Could not connect to the CI server' usually means that GitLab did not
+receive a build status update via the API. Either Jenkins was not properly
+configured or there was an error reporting the status via the API. 
+
+1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access
+2. [Configure a Jenkins project](#configure-a-jenkins-project), including the 
+   'Publish build status to GitLab' post-build action.