Add latest changes from gitlab-org/gitlab@master

2 files changed, 54 insertions, 0 deletions

diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md
index d701af20ec3..b6f6faa6052 100644
--- a/doc/development/testing_guide/end_to_end/index.md
+++ b/doc/development/testing_guide/end_to_end/index.md
@@ -166,6 +166,10 @@ environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/g
 Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab/tree/master/qa/README.md#how-can-i-use-it)
 and the section below.
 
+### Running tests that require special setup
+
+Learn how to perform [tests that require special setup or consideration to run on your local environment](running_tests_that_require_special_setup.md).
+
 ## How do I write tests?
 
 In order to write new tests, you first need to learn more about GitLab QA
diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
new file mode 100644
index 00000000000..f360226d922
--- /dev/null
+++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md
@@ -0,0 +1,50 @@
+# Running tests that require special setup
+
+## Jenkins spec
+
+The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a docker container based on an image stored in the [GitLab-QA container registry](https://gitlab.com/gitlab-org/gitlab-qa/container_registry).
+The docker image it uses is preconfigured with some base data and plugins.
+The test then configures the GitLab plugin in Jenkins with a URL of the GitLab instance that will be used
+to run the tests. Unfortunately, the GitLab Jenkins plugin does not accept ports so `http://localhost:3000` would
+not be accepted. Therefore, this requires us to run GitLab on port 80 or inside a docker container.
+
+To start a docker container for GitLab based on the nightly image:
+
+```shell
+docker run \
+  --publish 80:80 \
+  --name gitlab \
+  --hostname localhost \
+  gitlab/gitlab-ee:nightly
+```
+
+To run the tests from the `/qa` directory:
+
+```shell
+CHROME_HEADLESS=false bin/qa Test::Instance::All http://localhost -- qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb
+```
+
+The test will automatically spinup a docker container for Jenkins and tear down once the test completes.
+
+However, if you need to run Jenkins manually outside of the tests, use this command:
+
+```shell
+docker run \
+  --hostname localhost \
+  --name jenkins-server \
+  --env JENKINS_HOME=jenkins_home \
+  --publish 8080:8080 \
+  registry.gitlab.com/gitlab-org/gitlab-qa/jenkins-gitlab:version1
+```
+
+Jenkins will be available on `http://localhost:8080`.
+
+Admin username is `admin` and password is `password`.
+
+It is worth noting that this is not an orchestrated test. It is [tagged with the `:orchestrated` meta](https://gitlab.com/gitlab-org/gitlab/blob/163c8a8c814db26d11e104d1cb2dcf02eb567dbe/qa/qa/specs/features/ee/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb#L5)
+only to prevent it from running in the pipelines for live environments such as Staging.
+
+### Troubleshooting
+
+If Jenkins docker container exits without providing any information in the logs, try increasing the memory used by
+the Docker Engine.