gitlab-qa 6.21.4 → 7.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9760fa09e36771aae86f79908388d235ce9ec597e551d7458f8f2f9840f2456
-  data.tar.gz: e1c8574a9f3471e21017d32e9d92a0ff79ff057c71d0c9878fe04000ef5c781a
+  metadata.gz: 748a1ab7cef2f22dba11a3989e6ff8216eab6bc06eb017b1ba52ee9fbfff031c
+  data.tar.gz: 3e95822a025fb825039e3615548eab3f5ba6046b340fdecf7fc5d65c8e16b912
 SHA512:
-  metadata.gz: 361ad4bf805c10df590d8b7fb2bfce2a3d0af472c9d3dc92b648f44d44e779558171df44101ec952e6127848aa566f1d6ef4f50ce56e77a6d6cfdd0795f97313
-  data.tar.gz: b5ddd7de265e676f4078a10978d8931fb555a45fe9c559af9926debf620a9848ac6f503ee54689c7df04b4fa6d499765359a05c1909ef66445fe8794f39d3d66
+  metadata.gz: b80fc3ecf1eb1934126ed816b73c7f73d55a9364fec8afe035bb7d36c34d99e25003f036dba237dea3e6888102948aa303e3d18d931ae92b72ef306b1538bee6
+  data.tar.gz: 7997a9183233fa52f52e7cf71b6a8a43577ae0631297244a2b9ac20d65a17ad4e7a300ea9af3361a67681be668e7b252e95d27ed1a458b8294ec4af56cea1800

data/.gitlab-ci.yml

@@ -12,13 +12,14 @@ default:
   cache:
     key:
       files:
-        - Gemfile
+        - Gemfile.lock
         - gitlab-qa.gemspec
     paths:
       - vendor/ruby
   before_script:
     - bundle version
-    - bundle install --clean --jobs=$(nproc) --path=vendor --retry=3 --quiet && bundle check
+    - bundle config path vendor
+    - bundle install --jobs=$(nproc) --retry=3 --quiet && bundle check
     - if [ -n "$TRIGGERED_USER" ] && [ -n "$TRIGGER_SOURCE" ]; then
         echo "Pipeline triggered by $TRIGGERED_USER at $TRIGGER_SOURCE";
       fi
@@ -74,9 +75,9 @@ rspec:
     reports:
       junit: gitlab-qa-run-*/**/rspec-*.xml
   script:
-    - 'echo "Running: exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS"'
-    - exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS || test_run_exit_code=$?
-    - exe/gitlab-qa-report --update-screenshot-path "gitlab-qa-run-*/**/rspec-*.xml"
+    - 'echo "Running: bundle exec exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS"'
+    - bundle exec exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS || test_run_exit_code=$?
+    - bundle exec exe/gitlab-qa-report --update-screenshot-path "gitlab-qa-run-*/**/rspec-*.xml"
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
     - if [ "$TOP_UPSTREAM_SOURCE_REF" == $TOP_UPSTREAM_DEFAULT_BRANCH ] || [[ "$TOP_UPSTREAM_SOURCE_JOB" == https://ops.gitlab.net* ]]; then exe/gitlab-qa-report --report-in-issues "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASES_REPORTING_PROJECT" || true; fi
     - exit $test_run_exit_code
@@ -152,7 +153,7 @@ rspec:
 
 ce:sanity-framework:
   script:
-    - ./bin/expect_exit_code_and_text "exe/gitlab-qa Test::Instance::Image ${RELEASE:=CE} -- --tag framework" 1 "2 examples, 1 failure"
+    - ./bin/expect_exit_code_and_text "bundle exec exe/gitlab-qa Test::Instance::Image ${RELEASE:=CE} -- --tag framework" 1 "2 examples, 1 failure"
   extends:
     - .test
     - .high-capacity
@@ -160,7 +161,7 @@ ce:sanity-framework:
 
 ee:sanity-framework:
   script:
-    - ./bin/expect_exit_code_and_text "exe/gitlab-qa Test::Instance::Image ${RELEASE:=EE} -- --tag framework" 1 "2 examples, 1 failure"
+    - ./bin/expect_exit_code_and_text "bundle exec exe/gitlab-qa Test::Instance::Image ${RELEASE:=EE} -- --tag framework" 1 "2 examples, 1 failure"
   extends:
     - .test
     - .high-capacity
@@ -169,8 +170,8 @@ ee:sanity-framework:
 # The custom jobs are for manually running specific/alternative tests in MRs, so we don't report them in issues
 ce:custom-parallel:
   script:
-    - 'echo "Running: exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS"'
-    - exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS
+    - 'echo "Running: bundle exec exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS"'
+    - bundle exec exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS
   extends:
     - .test
     - .high-capacity
@@ -181,8 +182,8 @@ ce:custom-parallel:
 
 ee:custom-parallel:
   script:
-    - 'echo "Running: exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS"'
-    - exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS
+    - 'echo "Running: bundle exec exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS"'
+    - bundle exec exe/gitlab-qa ${QA_SCENARIO:=Test::Instance::Image} ${RELEASE:=$DEFAULT_RELEASE} $GITLAB_QA_OPTS -- $QA_TESTS $QA_RSPEC_TAGS $RSPEC_REPORT_OPTS
   extends:
     - .test
     - .high-capacity
@@ -314,14 +315,14 @@ ee:repository_storage-quarantine:
 # The Test::Omnibus::Image scenarios don't run the E2E tests so they don't need to report test results
 ce:image:
   script:
-    - exe/gitlab-qa Test::Omnibus::Image ${RELEASE:=CE}
+    - bundle exec exe/gitlab-qa Test::Omnibus::Image ${RELEASE:=CE}
   extends:
     - .test
     - .ce-qa
 
 ee:image:
   script:
-    - exe/gitlab-qa Test::Omnibus::Image ${RELEASE:=EE}
+    - bundle exec exe/gitlab-qa Test::Omnibus::Image ${RELEASE:=EE}
   extends:
     - .test
     - .ee-qa
@@ -330,7 +331,7 @@ ee:image:
 # So instead we include the script here again, with two release variables
 ce:update:
   script:
-    - exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=CE} ${RELEASE:=CE} -- $RSPEC_REPORT_OPTS || test_run_exit_code=$?
+    - bundle exec exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=CE} ${RELEASE:=CE} -- $RSPEC_REPORT_OPTS || test_run_exit_code=$?
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
     - if [ "$TOP_UPSTREAM_SOURCE_REF" == $TOP_UPSTREAM_DEFAULT_BRANCH ] || [[ "$TOP_UPSTREAM_SOURCE_JOB" == https://ops.gitlab.net* ]]; then exe/gitlab-qa-report --report-in-issues "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASES_REPORTING_PROJECT" || true; fi
     - exit $test_run_exit_code
@@ -344,7 +345,7 @@ ce:update:
 
 ce:update-quarantine:
   script:
-    - exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=CE} ${RELEASE:=CE} -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS || test_run_exit_code=$?
+    - bundle exec exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=CE} ${RELEASE:=CE} -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS || test_run_exit_code=$?
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
     - if [ "$TOP_UPSTREAM_SOURCE_REF" == $TOP_UPSTREAM_DEFAULT_BRANCH ] || [[ "$TOP_UPSTREAM_SOURCE_JOB" == https://ops.gitlab.net* ]]; then exe/gitlab-qa-report --report-in-issues "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASES_REPORTING_PROJECT" || true; fi
     - exit $test_run_exit_code
@@ -357,7 +358,7 @@ ce:update-quarantine:
 
 ee:update:
   script:
-    - exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=EE} ${RELEASE:=EE} -- $RSPEC_REPORT_OPTS || test_run_exit_code=$?
+    - bundle exec exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=EE} ${RELEASE:=EE} -- $RSPEC_REPORT_OPTS || test_run_exit_code=$?
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
     - if [ "$TOP_UPSTREAM_SOURCE_REF" == $TOP_UPSTREAM_DEFAULT_BRANCH ] || [[ "$TOP_UPSTREAM_SOURCE_JOB" == https://ops.gitlab.net* ]]; then exe/gitlab-qa-report --report-in-issues "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASES_REPORTING_PROJECT" || true; fi
     - exit $test_run_exit_code
@@ -371,7 +372,7 @@ ee:update:
 
 ee:update-quarantine:
   script:
-    - exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=EE} ${RELEASE:=EE} -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS || test_run_exit_code=$?
+    - bundle exec exe/gitlab-qa Test::Omnibus::Update ${RELEASE:=EE} ${RELEASE:=EE} -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS || test_run_exit_code=$?
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
     - if [ "$TOP_UPSTREAM_SOURCE_REF" == $TOP_UPSTREAM_DEFAULT_BRANCH ] || [[ "$TOP_UPSTREAM_SOURCE_JOB" == https://ops.gitlab.net* ]]; then exe/gitlab-qa-report --report-in-issues "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASES_REPORTING_PROJECT" || true; fi
     - exit $test_run_exit_code
@@ -385,7 +386,7 @@ ee:update-quarantine:
 # The Test::Omnibus::Upgrade scenario isn't run on master (because it always uses the latest CE/EE image) so we don't report the test results in issues
 ce:upgrade:
   script:
-    - exe/gitlab-qa Test::Omnibus::Upgrade CE -- $RSPEC_REPORT_OPTS
+    - bundle exec exe/gitlab-qa Test::Omnibus::Upgrade CE -- $RSPEC_REPORT_OPTS
   extends:
     - .test
     - .high-capacity
@@ -396,7 +397,7 @@ ce:upgrade:
 
 ce:upgrade-quarantine:
   script:
-    - exe/gitlab-qa Test::Omnibus::Upgrade CE -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS
+    - bundle exec exe/gitlab-qa Test::Omnibus::Upgrade CE -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS
   extends:
     - .test
     - .high-capacity
@@ -406,7 +407,7 @@ ce:upgrade-quarantine:
 
 ee-previous-to-ce:update:
   script:
-    - exe/gitlab-qa Test::Omnibus::Update EE CE -- $RSPEC_REPORT_OPTS
+    - bundle exec exe/gitlab-qa Test::Omnibus::Update EE CE -- $RSPEC_REPORT_OPTS
   extends:
     - .test
     - .high-capacity
@@ -415,7 +416,7 @@ ee-previous-to-ce:update:
 
 ee-previous-to-ce:update-quarantine:
   script:
-    - exe/gitlab-qa Test::Omnibus::Update EE CE -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS
+    - bundle exec exe/gitlab-qa Test::Omnibus::Update EE CE -- --tag quarantine --tag ~orchestrated $RSPEC_REPORT_OPTS
   extends:
     - .test
     - .high-capacity
@@ -718,7 +719,7 @@ ce:object_storage:
     - .ce-qa
     - .rspec-report-opts
   variables:
-    QA_SCENARIO: "Test::Integration::ObjectStorage"
+    GITLAB_QA_OPTS: "--omnibus-config object_storage"
 
 ce:object_storage-quarantine:
   extends:
@@ -728,7 +729,7 @@ ce:object_storage-quarantine:
     - .quarantine
     - .rspec-report-opts
   variables:
-    QA_SCENARIO: "Test::Integration::ObjectStorage"
+    GITLAB_QA_OPTS: "--omnibus-config object_storage"
 
 ee:object_storage:
   extends:
@@ -737,7 +738,7 @@ ee:object_storage:
     - .ee-qa
     - .rspec-report-opts
   variables:
-    QA_SCENARIO: "Test::Integration::ObjectStorage"
+    GITLAB_QA_OPTS: "--omnibus-config object_storage"
 
 ee:object_storage-quarantine:
   extends:
@@ -747,7 +748,7 @@ ee:object_storage-quarantine:
     - .quarantine
     - .rspec-report-opts
   variables:
-    QA_SCENARIO: "Test::Integration::ObjectStorage"
+    GITLAB_QA_OPTS: "--omnibus-config object_storage"
 
 ee:packages:
   extends:
@@ -756,7 +757,7 @@ ee:packages:
     - .ee-qa
     - .rspec-report-opts
   variables:
-    QA_SCENARIO: "Test::Integration::Packages"
+    GITLAB_QA_OPTS: "--omnibus-config packages"
 
 ee:packages-quarantine:
   extends:
@@ -766,7 +767,7 @@ ee:packages-quarantine:
     - .quarantine
     - .rspec-report-opts
   variables:
-    QA_SCENARIO: "Test::Integration::Packages"
+    GITLAB_QA_OPTS: "--omnibus-config packages"
 
 ce:actioncable:
   extends:
@@ -988,8 +989,8 @@ ee:jira-quarantine:
 staging:
   script:
     - unset EE_LICENSE
-    - 'echo "Running: exe/gitlab-qa Test::Instance::Staging ${RELEASE:=$DEFAULT_RELEASE} -- $QA_TESTS $QA_RSPEC_TAGS"'
-    - exe/gitlab-qa Test::Instance::Staging ${RELEASE:=$DEFAULT_RELEASE} -- $QA_TESTS $QA_RSPEC_TAGS
+    - 'echo "Running: bundle exec exe/gitlab-qa Test::Instance::Staging ${RELEASE:=$DEFAULT_RELEASE} -- $QA_TESTS $QA_RSPEC_TAGS"'
+    - bundle exec exe/gitlab-qa Test::Instance::Staging ${RELEASE:=$DEFAULT_RELEASE} -- $QA_TESTS $QA_RSPEC_TAGS
   extends:
     - .test
     - .high-capacity
@@ -1010,7 +1011,7 @@ generate_test_session:
       - REPORT_ISSUE_URL
   script:
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
-    - exe/gitlab-qa-report --generate-test-session "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASE_SESSIONS_PROJECT"
+    - bundle exec exe/gitlab-qa-report --generate-test-session "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_TESTCASE_SESSIONS_PROJECT"
 
 relate_test_failures:
   stage: report
@@ -1028,7 +1029,7 @@ relate_test_failures:
     QA_FAILURES_REPORTER_OPTIONS: ""
   script:
     - export GITLAB_QA_ACCESS_TOKEN="$GITLAB_QA_PRODUCTION_ACCESS_TOKEN"
-    - exe/gitlab-qa-report --relate-failure-issue "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_FAILURES_REPORTING_PROJECT" --max-diff-ratio "$QA_FAILURES_MAX_DIFF_RATIO" $QA_FAILURES_REPORTER_OPTIONS
+    - bundle exec exe/gitlab-qa-report --relate-failure-issue "gitlab-qa-run-*/**/rspec-*.json" --project "$QA_FAILURES_REPORTING_PROJECT" --max-diff-ratio "$QA_FAILURES_MAX_DIFF_RATIO" $QA_FAILURES_REPORTER_OPTIONS
 
 .notify_upstream_commit:
   stage: notify

data/docs/configuring_omnibus.md

@@ -0,0 +1,208 @@
+# Configuring Omnibus
+
+Omnibus will, by default, contain the configuration specified in `Gitlab::QA::Runtime::OmnibusConfigurations::Default`.
+
+Omnibus can be configured from two places:
+
+1. Within a custom `Scenario::Template`.
+1. Represented as a `Gitlab::QA::Runtime::OmnibusConfiguration` class.
+
+## Adding an Omnibus Configurator
+
+All configurators are held within `Gitlab::QA::Runtime::OmnibusConfigurations` and represented as separate classes.
+
+Notes:
+
+- If it is required that more than one GitLab instance is configured, 
+  you may skip adding an Omnibus Configurator.  In this case, it should be handled by a separate `Scenario::Template`.
+  An example of this would be a Geo Primary and Secondary.
+- All classes should be a type of `Runtime::OmnibusConfiguration`.
+
+### Add the Configurator Class
+
+Create a new file in `lib/gitlab/qa/runtime/omnibus_configurations` called `registry.rb`.
+
+```ruby
+# frozen_string_literal: true
+
+module Gitlab
+  module QA
+    module Runtime
+      module OmnibusConfigurations
+        class Registry < Default
+          def configuration
+            <<~OMNIBUS
+              gitlab_rails['registry_enabled'] = true
+            OMNIBUS
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Notes:
+
+- Refrain from adding unnecessary statement terminations (`;`).
+
+### Prepare Sidecar Container
+
+If the tests require an additional container to be spun up adjacent to GitLab, you may override the `prepare` method.
+
+```ruby
+#=> lib/gitlab/qa/runtime/omnibus_configurations/registry.rb
+
+# frozen_string_literal: true
+
+module Gitlab
+  module QA
+    module Runtime
+      module OmnibusConfigurations
+        class Registry < Default
+          def configuration
+            <<~OMNIBUS
+              gitlab_rails['registry_enabled'] = true
+            OMNIBUS
+          end
+
+          def prepare
+            Component::Sidecar.new
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Notes:
+
+- `prepare` **must** return an instance of `Component::Base`.
+- The sidecar container will be prepared before the test runs, and will run the tests after it is running.
+- Extending the class from `Default` is only a nicety that adds a singleton method called `Registry.configuration` and returns the configuration.
+  It is recommended to extend from `Default`, but you may also extend from any other Omnibus Configuration class, including `Runtime::OmnibusConfiguration`.
+
+## Running tests with Omnibus Configured
+
+All Omnibus Configurators can be called by passing arguments into the `gitlab-qa` executable.
+
+```shell
+exe/gitlab-qa Test::Instance::Image EE --omnibus-config registry
+```
+
+Notes:
+
+- `--omnibus-config registry` must match the name of the Omnibus Configurator Class name (`Runtime::OmnibusConfigurations::Registry`), but lowercase.
+- If the Configurator Class name contains several words, the argument will be named the same, but snake cased. E.g. `--omnibus-config some_class` matches `SomeClass`, `--omnibus-config some_other_class` matches `SomeOtherClass`.
+- The Omnibus GitLab Instance will have the configuration from `Default` and `Registry` (in that order) put into `/etc/gitlab/gitlab.rb` and GitLab QA will proceed to run the tests.
+- If a specified Omnibus Configuration does not exist, GitLab QA will raise an error and fail immediately.
+
+## Further reading
+
+### Multiple Configurators
+
+Multiple Configurators may be specified and the order will be preserved in which the arguments were passed.
+
+E.g., given the arguments:
+
+```
+exe/gitlab-qa Test::Instance::Image EE --omnibus-config packages,registry
+# or
+exe/gitlab-qa Test::Instance::Image EE --omnibus-config packages --omnibus-config registry
+```
+
+Omnibus will be configured in the order they appear.
+
+```ruby
+# /etc/gitlab/gitlab.rb
+#=> Runtime::OmnibusConfiguration::Default#configuration
+#=> Runtime::OmnibusConfiguration::Packages#configuration
+#=> Runtime::OmnibusConfiguration::Registry#configuration
+```
+
+The order is also preserved for Sidecar containers.  If the `Packages` and `Registry` Configurators each prepare a sidecar container, they will be spun up in order from first to last.
+
+### Adding one-off configurations
+
+#### From a new Scenario::Template
+
+If it is required to create a new `Scenario::Template`, you may add new Configurations to the respective GitLab Instances by invoking `omnibus_configuration#<<`
+
+```ruby
+# Geo example
+
+Component::Gitlab.perform do |primary|
+  primary.omnibus_configuration << <<~OMNIBUS
+    geo_primary_role['enable'] = true
+  OMNIBUS
+  
+  primary.instance do
+    Component::Gitlab.perform do |secondary|
+      secondary.omnibus_configuration << <<~OMNIBUS
+        geo_secondary_role['enable'] = true
+      OMNIBUS
+    end
+  end
+end
+```
+
+Notes:
+
+- The `primary` instance will be configured using the `Runtime::OmnibusConfigurations::Default` configuration, *then* `geo_primary_role['enable'] = true` will be affixed afterwards.
+- The `secondary` instance will be configured using the `Runtime::OmnibusConfigurations::Default` configuration, *then* `geo_secondary_role['enable'] = true` will be affixed afterwards.
+
+#### From Component::Gitlab
+
+Any additional one-off configurations needing to be added may be directly appended to `@omnibus_configuration` as such:
+
+```ruby
+disable_animations = true
+
+@omnibus_configuration << "gitlab_rails['gitlab_disable_animations'] = true" if disable_animations
+```
+
+This will add the specified configuration **after** what has already been specified beforehand (Configurators or Default configurations).
+
+Note:
+
+- If there is no issue appending this configuration to the **rest** of the GitLab Instances that might be spun up, you can add this
+  to the global Omnibus Configuration. E.g., use `Runtime::Scenario.omnibus_configuration << ...` instead of `@omnibus_configuration << ...`
+
+#### Difference between Runtime::Scenario.omnibus_configuration and Gitlab#omnibus_configuration
+
+Generally, while running GitLab QA, only one GitLab instance is necessary. `Runtime::Scenario.omnibus_configuration` contains all of the global
+Omnibus configurations required for this one environment.  This also contains the configuration for any other GitLab instance.
+
+When multiple GitLab Instances are required, `@omnibus_configuration#<<` is preferred over `Runtime::Scenario.omnibus_configuration#<<` since the First Instance might require
+one Omnibus configuration that might be unneccesary or Invalid for the Second Instance.
+
+#### Load order and precedence
+
+1. `Runtime::OmnibusConfigurations::Default`
+1. `Runtime::OmnibusConfigurations::[A,B,...]` where `A` and `B` are Configurators specified through the positional arguments `--a --b`
+1. Custom written `Scenario::Template` (such as `Test::Integation::Geo`)
+1. `lib/gitlab/qa/component/gitlab.rb`
+
+From top to bottom, configurations will be loaded and any configurations that are superceded, will take precedence over the one before it, and so on.
+
+### Executing arbitrary shell commands within the GitLab Instance
+
+Sometimes it's necessary to execute arbitrary commands within the GitLab instance before the tests start.
+
+You may specify these commands by overriding the `exec_commands` method within the Configurator.
+
+```ruby
+class Registry < Default
+  def configuration
+    # configuration
+  end
+  
+  def exec_commands
+    [
+      'cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.bak.rb',
+      'rm /etc/gitlab/gitlab.bak.rb'
+    ]
+  end
+end
+```