From 4103ac83235cfe52d33d1c11c8d0b638095f3059 Mon Sep 17 00:00:00 2001 From: Krish Moodbidri Date: Fri, 9 Jan 2026 10:55:54 -0600 Subject: [PATCH 1/4] docs: consolidate and simplify GitLab CI docs Created a new top-level gitlab ci directory and moved the runner and debugging documentation into it. Added instructions for muting Slack notifications and enabling verbose debug tracing. --- docs/gitlab-ci/debugging/index.md | 49 ++++++++++++++++++ .../runner/personal}/image-1.png | Bin .../runner/personal}/image.png | Bin .../runner/personal/index.md} | 0 mkdocs.yml | 6 ++- 5 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 docs/gitlab-ci/debugging/index.md rename docs/{gitlab_runner => gitlab-ci/runner/personal}/image-1.png (100%) rename docs/{gitlab_runner => gitlab-ci/runner/personal}/image.png (100%) rename docs/{gitlab_runner/personal_gitlab_runner_setup.md => gitlab-ci/runner/personal/index.md} (100%) diff --git a/docs/gitlab-ci/debugging/index.md b/docs/gitlab-ci/debugging/index.md new file mode 100644 index 0000000..31421fd --- /dev/null +++ b/docs/gitlab-ci/debugging/index.md @@ -0,0 +1,49 @@ +# Mute Notifications While Debugging + +Frequent commits or scheduled pipeline runs during troubleshooting can result in notification spam within the team Slack channel. To address this, we utilize a branch-based filtering strategy. + +The UAB RC Slack integration is configured to send notifications **only for pipelines running on the default branch**. By running your pipeline on a non-default branch, you can execute as many test runs as needed without triggering Slack alerts. + +### How to Mute Notifications + +1. **Create and Push a Temporary Branch** Create a branch from your current development head using a descriptive name (e.g., `temp-debug-pipeline`). +2. **Run and Monitor the Pipeline** After pushing the branch, you may need to trigger the pipeline manually depending on the project's CI configuration. Since this is a non-default branch, Slack notifications will remain muted. +3. **Cleanup After Success** After you have confirmed your fix and the pipeline is successful, merge your changes into your primary development branch and remove the temporary branch to keep the repository clean. + + +# Enable CI_DEBUG_TRACE + +## Enabling debug mode for GitLab CI pipelines + + GitLab provides a predefined CI/CD variable, CI_DEBUG_TRACE, that enables verbose debug output for job execution. This is useful when you need to see the variable interpolation in the job + +When set to "true", the job log shows every command as it executes and prints the environment variables available to the job, which helps with troubleshooting variable expansion and script behavior. + +## Enabling debug for a single job in .gitlab-ci.yml +To turn on debug mode for a specific job, define CI_DEBUG_TRACE under that job’s variables section: + +``` +debug_example_job: + stage: test + variables: + CI_DEBUG_TRACE: "true" + script: + - echo "Debug trace is enabled for this job" + - ./run-tests.sh +``` +!!! note + * Debug trace applies only to `debug_example_job`; other jobs in the pipeline run with normal logging. + * To turn debug off for this job, either remove `CI_DEBUG_TRACE` or set it to `"false"` and re-run the pipeline. + +### Enable debug for the whole pipeline + +Enable debug mode for the entire pipeline by manually setting the `CI_DEBUG_TRACE` variable: + +1. In your project, navigate to **Build > Pipelines**. +2. Click the **Run pipeline** button. +3. In the **Variables** section of the form, add a new variable: + * **Key:** `CI_DEBUG_TRACE` + * **Value:** `true` +4. Click **Run pipeline**. + +All jobs within that specific pipeline run will detect `CI_DEBUG_TRACE` and emit verbose debug trace information in their respective logs. diff --git a/docs/gitlab_runner/image-1.png b/docs/gitlab-ci/runner/personal/image-1.png similarity index 100% rename from docs/gitlab_runner/image-1.png rename to docs/gitlab-ci/runner/personal/image-1.png diff --git a/docs/gitlab_runner/image.png b/docs/gitlab-ci/runner/personal/image.png similarity index 100% rename from docs/gitlab_runner/image.png rename to docs/gitlab-ci/runner/personal/image.png diff --git a/docs/gitlab_runner/personal_gitlab_runner_setup.md b/docs/gitlab-ci/runner/personal/index.md similarity index 100% rename from docs/gitlab_runner/personal_gitlab_runner_setup.md rename to docs/gitlab-ci/runner/personal/index.md diff --git a/mkdocs.yml b/mkdocs.yml index b423f10..8f84e25 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,8 +74,10 @@ nav: - Cheaha: - Archiving Modules: cheaha/archiving_modules.md - Shell Commands: cheaha/shell_commands.md - - GitLab Runner: - - Personal GitLab Runner Setup: gitlab_runner/personal_gitlab_runner_setup.md + - GitLab CI: + - GitLab Runner: + - Personal Runner: gitlab-ci/runner/personal/index.md + - Debugging CI Pipelines: gitlab-ci/debugging/index.md - Openstack: - VM Migration: openstack/vm_migration.md - VM Service Setup: service/service_setup.md From 7c8b2814259d409c8ae9ee5c99d9c2d6359ee204 Mon Sep 17 00:00:00 2001 From: Krish Moodbidri Date: Wed, 14 Jan 2026 12:54:03 -0600 Subject: [PATCH 2/4] docs: fix markdown linting errors in gitlab-ci debugging guide --- docs/gitlab-ci/debugging/index.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/gitlab-ci/debugging/index.md b/docs/gitlab-ci/debugging/index.md index 31421fd..09f6080 100644 --- a/docs/gitlab-ci/debugging/index.md +++ b/docs/gitlab-ci/debugging/index.md @@ -4,25 +4,27 @@ Frequent commits or scheduled pipeline runs during troubleshooting can result in The UAB RC Slack integration is configured to send notifications **only for pipelines running on the default branch**. By running your pipeline on a non-default branch, you can execute as many test runs as needed without triggering Slack alerts. -### How to Mute Notifications +## How to Mute Notifications -1. **Create and Push a Temporary Branch** Create a branch from your current development head using a descriptive name (e.g., `temp-debug-pipeline`). -2. **Run and Monitor the Pipeline** After pushing the branch, you may need to trigger the pipeline manually depending on the project's CI configuration. Since this is a non-default branch, Slack notifications will remain muted. -3. **Cleanup After Success** After you have confirmed your fix and the pipeline is successful, merge your changes into your primary development branch and remove the temporary branch to keep the repository clean. +1. **Create and Push a Temporary Branch** + Create a branch from your current development head using a descriptive name (e.g., `temp-debug-pipeline`). +2. **Run and Monitor the Pipeline** + After pushing the branch, you may need to trigger the pipeline manually depending on the project's CI configuration. Since this is a non-default branch, Slack notifications will remain muted. +3. **Cleanup After Success** + After you have confirmed your fix and the pipeline is successful, merge your changes into your primary development branch and remove the temporary branch to keep the repository clean. +## Enable CI_DEBUG_TRACE -# Enable CI_DEBUG_TRACE - -## Enabling debug mode for GitLab CI pipelines +### Enabling debug mode for GitLab CI pipelines GitLab provides a predefined CI/CD variable, CI_DEBUG_TRACE, that enables verbose debug output for job execution. This is useful when you need to see the variable interpolation in the job When set to "true", the job log shows every command as it executes and prints the environment variables available to the job, which helps with troubleshooting variable expansion and script behavior. -## Enabling debug for a single job in .gitlab-ci.yml +### Enabling debug for a single job in .gitlab-ci.yml To turn on debug mode for a specific job, define CI_DEBUG_TRACE under that job’s variables section: -``` +```yaml debug_example_job: stage: test variables: @@ -31,6 +33,7 @@ debug_example_job: - echo "Debug trace is enabled for this job" - ./run-tests.sh ``` + !!! note * Debug trace applies only to `debug_example_job`; other jobs in the pipeline run with normal logging. * To turn debug off for this job, either remove `CI_DEBUG_TRACE` or set it to `"false"` and re-run the pipeline. From 13e40ab7cf1073c1cafae747575c789c3fa82151 Mon Sep 17 00:00:00 2001 From: Krish Moodbidri Date: Wed, 14 Jan 2026 13:00:42 -0600 Subject: [PATCH 3/4] fix: resolve markdown linting issues in GitLab CI debugging docs --- docs/gitlab-ci/debugging/index.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/gitlab-ci/debugging/index.md b/docs/gitlab-ci/debugging/index.md index 09f6080..ec7ebc7 100644 --- a/docs/gitlab-ci/debugging/index.md +++ b/docs/gitlab-ci/debugging/index.md @@ -8,21 +8,22 @@ The UAB RC Slack integration is configured to send notifications **only for pipe 1. **Create and Push a Temporary Branch** Create a branch from your current development head using a descriptive name (e.g., `temp-debug-pipeline`). -2. **Run and Monitor the Pipeline** +1. **Run and Monitor the Pipeline** After pushing the branch, you may need to trigger the pipeline manually depending on the project's CI configuration. Since this is a non-default branch, Slack notifications will remain muted. -3. **Cleanup After Success** +1. **Cleanup After Success** After you have confirmed your fix and the pipeline is successful, merge your changes into your primary development branch and remove the temporary branch to keep the repository clean. ## Enable CI_DEBUG_TRACE ### Enabling debug mode for GitLab CI pipelines - GitLab provides a predefined CI/CD variable, CI_DEBUG_TRACE, that enables verbose debug output for job execution. This is useful when you need to see the variable interpolation in the job +GitLab provides a predefined CI/CD variable, CI_DEBUG_TRACE, that enables verbose debug output for job execution. This is useful when you need to see the variable interpolation in the job -When set to "true", the job log shows every command as it executes and prints the environment variables available to the job, which helps with troubleshooting variable expansion and script behavior. +When set to "true", the job log shows every command as it executes and prints the environment variables available to the job, which helps with troubleshooting variable expansion and script behavior. ### Enabling debug for a single job in .gitlab-ci.yml -To turn on debug mode for a specific job, define CI_DEBUG_TRACE under that job’s variables section: + +To turn on debug mode for a specific job, define CI_DEBUG_TRACE under that job's variables section: ```yaml debug_example_job: @@ -35,18 +36,19 @@ debug_example_job: ``` !!! note - * Debug trace applies only to `debug_example_job`; other jobs in the pipeline run with normal logging. - * To turn debug off for this job, either remove `CI_DEBUG_TRACE` or set it to `"false"` and re-run the pipeline. -### Enable debug for the whole pipeline + - Debug trace applies only to `debug_example_job`; other jobs in the pipeline run with normal logging. + - To turn debug off for this job, either remove `CI_DEBUG_TRACE` or set it to `"false"` and re-run the pipeline. + +### Enable debug for the whole pipeline Enable debug mode for the entire pipeline by manually setting the `CI_DEBUG_TRACE` variable: 1. In your project, navigate to **Build > Pipelines**. -2. Click the **Run pipeline** button. -3. In the **Variables** section of the form, add a new variable: - * **Key:** `CI_DEBUG_TRACE` - * **Value:** `true` -4. Click **Run pipeline**. +1. Click the **Run pipeline** button. +1. In the **Variables** section of the form, add a new variable: + - **Key:** `CI_DEBUG_TRACE` + - **Value:** `true` +1. Click **Run pipeline**. All jobs within that specific pipeline run will detect `CI_DEBUG_TRACE` and emit verbose debug trace information in their respective logs. From 6c84654f0db974c8b2e9bf9566e7f64875af4b65 Mon Sep 17 00:00:00 2001 From: Krish Moodbidri Date: Wed, 14 Jan 2026 13:06:04 -0600 Subject: [PATCH 4/4] fix: remove indentation from note block to resolve MD046 linting error --- docs/gitlab-ci/debugging/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/gitlab-ci/debugging/index.md b/docs/gitlab-ci/debugging/index.md index ec7ebc7..9374ae4 100644 --- a/docs/gitlab-ci/debugging/index.md +++ b/docs/gitlab-ci/debugging/index.md @@ -37,8 +37,8 @@ debug_example_job: !!! note - - Debug trace applies only to `debug_example_job`; other jobs in the pipeline run with normal logging. - - To turn debug off for this job, either remove `CI_DEBUG_TRACE` or set it to `"false"` and re-run the pipeline. +- Debug trace applies only to `debug_example_job`; other jobs in the pipeline run with normal logging. +- To turn debug off for this job, either remove `CI_DEBUG_TRACE` or set it to `"false"` and re-run the pipeline. ### Enable debug for the whole pipeline