gitlab-qa 6.23.0 → 7.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be38f6268c3a91ecdeee390c040f658e07194eb1e3d5f99694d50c68540a5461
-  data.tar.gz: bb9fd66f54e18792a9d5a8bb445fefe7cc63d824ef445b61b60f2c7ef378422f
+  metadata.gz: 94fd458767a2190eeba5094962dca4d1eb9d1ec2769c3ed6815e0750c4d95d3e
+  data.tar.gz: 38f5336f05c2bb558c7099d410ceea33cf1f0ea254b978e18c32c96f5e7fdc62
 SHA512:
-  metadata.gz: 54f0d06a51b27c5e4ea0c1352ca01f634d8e7bc00475345c87650beaf783e7f4dcc4cc53828d54e75b01ada167f002c1a51451147afac400a27ae9132008ee30
-  data.tar.gz: a651ecb24eb49d6e3997c5c6abfef1048900f760d81374e35b9104b05b25210f94c0ecf4de65e5e79c710ca7552153da7aab36e765b5e1acd9c829cf6feb36c1
+  metadata.gz: 8a146c677f1b78dde5755e9d0d0445c100f4264d2e862dc98c75c8bf7265b84df9167565702c88556877c48747eb18b677a6deb4ff4489bf5e05a54c0fb0bd5c
+  data.tar.gz: e386131381bdfc7e1f7c4f9644586279af44e8996c0f4fc23a70559d821f127856e56ec37391407346982058b9377f78979f269e2d0d49b49d074845fad7c37a

data/.gitlab-ci.yml

@@ -18,7 +18,8 @@ default:
       - vendor/ruby
   before_script:
     - bundle version
-    - bundle install --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
+```

data/docs/what_tests_can_be_run.md

@@ -534,6 +534,18 @@ $ gitlab-qa Test::Integration::Mattermost EE
 
 ### `Test::Integration::Packages CE|EE|<full image address>`
 
+**Note: This Scenario no longer exists.  See https://gitlab.com/gitlab-org/gitlab-qa/-/merge_requests/662**
+
+To run Packages tests, you may [configure Omnibus](configuring_omnibus.md) to use the [Packages](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/lib/gitlab/qa/runtime/omnibus_configurations/packages.rb) configurator.
+
+Example:
+
+```
+$ export EE_LICENSE=$(cat /path/to/Geo.gitlab_license)
+
+$ gitlab-qa Test::Instance::Image EE --omnibus-config packages
+```
+
 This tests the GitLab Package Registry feature by setting
 `gitlab_rails['packages_enabled'] = true` in the Omnibus configuration
 before starting the GitLab container.
@@ -547,14 +559,6 @@ which runs only the tests with `:packages` metadata.
 
 - `EE_LICENSE`: A valid EE license.
 
-Example:
-
-```
-$ export EE_LICENSE=$(cat /path/to/Geo.gitlab_license)
-
-$ gitlab-qa Test::Integration::Packages EE
-```
-
 ### `Test::Integration::Praefect CE|EE|<full image address>`
 
 This tests [Praefect](https://docs.gitlab.com/ee/administration/gitaly/praefect.html),