firecow · xoro · Aug 15, 2025
diff --git a/README.md b/README.md
@@ -26,6 +26,7 @@ Get rid of all those dev specific shell scripts and make files.
     * [docker-swarm-php](./examples/docker-swarm-php)
     * [docker-in-docker-build](./examples/docker-in-docker-build)
     * [docker-in-docker with a local registry](./examples/docker-in-docker-build-with-local-registry)
+    * [scheduled-pipeline-testing](./examples/scheduled-pipeline-testing)
 * [Installation](#installation)
 * [Convenience](#convenience)
     * [CLI options](#cli-options)
@@ -155,6 +156,77 @@ export GCL_MAX_JOB_NAME_PADDING=30 # or --maxJobNamePadding: limit padding aroun
 export GCL_QUIET=true # or --quiet: Suppress all job output
 ```
 
+
+### Pipeline Simulation Options
+
+#### --pipeline-source
+Simulate different pipeline sources for testing complex GitLab CI configurations locally.
+
+**Supported values:**
+- `push` (default) - Standard development pipeline
+- `schedule` - Scheduled pipeline
+- `merge_request_event` - Merge request pipeline  
+- `web` - Web-triggered pipeline
+- `api` - API-triggered pipeline
+- `external` - External pipeline
+- `chat` - Chat-triggered pipeline
+- `external_pull_request_event` - External pull request on GitHub
+- `ondemand_dast_scan` - DAST on-demand scan pipelines
+- `ondemand_dast_validation` - DAST on-demand validation pipelines
+- `parent_pipeline` - Parent/child pipeline triggers
+- `pipeline` - Multi-project pipelines
+- `security_orchestration_policy` - Scheduled scan execution policies
+- `trigger` - Downstream pipeline triggers
+- `webide` - Web IDE pipelines
+
+**Examples:**
+```bash
+# Test scheduled pipeline behavior
+gitlab-ci-local --pipeline-source schedule --list
+
+# Test merge request pipeline
+gitlab-ci-local --pipeline-source merge_request_event --list
+
+# Test downstream pipeline
+gitlab-ci-local --pipeline-source trigger --list
+
+# Test multi-project pipeline
+gitlab-ci-local --pipeline-source pipeline --list
+
+# Test external pull request
+gitlab-ci-local --pipeline-source external_pull_request_event --list
+
+# Test DAST scan
+gitlab-ci-local --pipeline-source ondemand_dast_scan --list
+
+# Test parent pipeline
+gitlab-ci-local --pipeline-source parent_pipeline --list
+
+# Test Web IDE
+gitlab-ci-local --pipeline-source webide --list
+```
+
+**Validation:**
+The tool validates pipeline source values and provides clear error messages for invalid options. All values are restricted to the official GitLab CI pipeline sources.
+
+#### --schedule-name
+Specify the exact schedule name for testing scheduled pipelines. This is particularly useful for testing complex conditional logic in scheduled pipelines.
+
+**Examples:**
+```bash
+# Test specific npm dependency update schedule
+gitlab-ci-local --pipeline-source schedule --schedule-name "npm Dependency Update" --list
+
+# Test OpenBSD snapshot schedule
+gitlab-ci-local --pipeline-source schedule --schedule-name "Daily OpenBSD Snapshot Check" --list
+```
+
+**Validation:**
+Schedule names are validated for:
+- Non-empty values
+- Maximum length of 255 characters
+- Invalid filesystem characters (`< > : " \ | ? *`)
+- Clear error messages for validation failures
 ### List Pipeline Jobs
 
 Sometimes there is the need of knowing which jobs will be added before actually executing the pipeline.
@@ -208,6 +280,56 @@ build-job;"";build;on_success;true;[test-job]
 deploy-job;"";deploy;never;false;[build-job]
 ```
 
+
+## Testing Complex Pipeline Scenarios
+
+### Enhanced Error Handling & Validation
+
+GitLab CI Local now includes comprehensive validation for pipeline simulation options:
+
+- **Pipeline Source Validation**: Restricts values to official GitLab CI pipeline sources (15 supported types)
+- **Schedule Name Validation**: Ensures schedule names meet filesystem and length requirements
+- **Clear Error Messages**: Provides actionable feedback for invalid inputs
+- **Environment Variable Support**: Automatically detects and validates `CI_PIPELINE_SOURCE` and `SCHEDULE_NAME` from environment
+- **Constants-Based Validation**: Uses centralized constants for maintainable validation logic
+
+**Error Handling Examples:**
+```bash
+# Invalid pipeline source
+gitlab-ci-local --pipeline-source invalid_source --list
+# Error: Invalid pipeline source: "invalid_source". Valid options are: push, schedule, merge_request_event, web, api, external, chat, external_pull_request_event, ondemand_dast_scan, ondemand_dast_validation, parent_pipeline, pipeline, security_orchestration_policy, trigger, webide
+
+# Invalid schedule name
+gitlab-ci-local --pipeline-source schedule --schedule-name "invalid<name" --list
+# Error: Schedule name contains invalid characters: <. Please use only valid characters.
+```
+
+GitLab CI Local now supports testing complex pipeline configurations including:
+
+- **Scheduled Pipelines**: Test pipelines triggered by GitLab schedules
+- **Conditional Includes**: Test complex `rules` and conditional logic
+- **Pipeline Source Simulation**: Test different pipeline trigger types
+- **Environment Variable Handling**: Test CI_* and SCHEDULE_NAME variables
+
+### Example: Testing Scheduled Pipeline with Conditional Logic
+
+```bash
+# Test a scheduled pipeline that has complex conditional includes
+gitlab-ci-local --pipeline-source schedule --schedule-name "Daily Check" --list
+
+# Compare with standard development pipeline
+gitlab-ci-local --pipeline-source push --list
+```
+
+### Example: Testing Complex Rules
+
+```bash
+# Test specific schedule names
+gitlab-ci-local --pipeline-source schedule --schedule-name "npm Dependency Update" --list
+gitlab-ci-local --pipeline-source schedule --schedule-name "Daily OpenBSD Snapshot Check" --list
+```
+
+See the [scheduled-pipeline-testing](./examples/scheduled-pipeline-testing) example for comprehensive usage patterns.
 ## Quirks
 
 ### Tracked Files

diff --git a/examples/scheduled-pipeline-testing/.gitlab-ci.yml b/examples/scheduled-pipeline-testing/.gitlab-ci.yml
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2025, Timo Pallach (timo@pallach.de).
+
+# Example GitLab CI configuration demonstrating scheduled pipeline testing
+# This file shows how to use conditional includes and complex rules
+
+stages:
+  - prepare
+  - build
+  - test
+  - deploy
+
+# Example jobs that demonstrate different pipeline behaviors
+standard-job:
+  stage: test
+  script:
+    - echo "This job runs in standard pipelines (push, merge_request_event)"
+  rules:
+    - if: $CI_PIPELINE_SOURCE != "schedule"
+      when: always
+    - when: never
+
+scheduled-job:
+  stage: test
+  script:
+    - echo "This job runs in scheduled pipelines"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      when: always
+    - when: never
+
+schedule-specific-job:
+  stage: test
+  script:
+    - echo "This job runs only for specific schedules"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULE_NAME == "Daily Check"
+      when: always
+    - when: never
+
+always-job:
+  stage: test
+  script:
+    - echo "This job always runs regardless of pipeline source"
+  rules:
+    - when: always
+
+# Example jobs for different pipeline sources
+web-triggered-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via web interface"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "web"
+      when: always
+    - when: never
+
+api-triggered-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via API"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "api"
+      when: always
+    - when: never
+
+external-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via external CI services"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "external"
+      when: always
+    - when: never
+
+merge-request-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via merge request"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: always
+    - when: never
+
+trigger-job:
+  stage: build
+  script:
+    - echo "This job runs when triggered via downstream pipeline"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "trigger"
+      when: always
+    - when: never
+
+pipeline-job:
+  stage: deploy
+  script:
+    - echo "This job runs when triggered via multi-project pipeline"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "pipeline"
+      when: always
+    - when: never
+
+# Additional pipeline source examples
+external-pull-request-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via external pull request on GitHub"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "external_pull_request_event"
+      when: always
+    - when: never
+
+ondemand-dast-scan-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via DAST on-demand scan"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "ondemand_dast_scan"
+      when: always
+    - when: never
+
+ondemand-dast-validation-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via DAST on-demand validation"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "ondemand_dast_validation"
+      when: always
+    - when: never
+
+parent-pipeline-job:
+  stage: build
+  script:
+    - echo "This job runs when triggered via parent pipeline"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "parent_pipeline"
+      when: always
+    - when: never
+
+security-orchestration-job:
+  stage: deploy
+  script:
+    - echo "This job runs when triggered via security orchestration policy"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "security_orchestration_policy"
+      when: always
+    - when: never
+
+webide-job:
+  stage: test
+  script:
+    - echo "This job runs when triggered via Web IDE"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "webide"
+      when: always
+    - when: never
diff --git a/examples/scheduled-pipeline-testing/.gitlab-ci/other-pipeline-sources.yml b/examples/scheduled-pipeline-testing/.gitlab-ci/other-pipeline-sources.yml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2025, Timo Pallach (timo@pallach.de).
+
+# Other pipeline source components
+# This file demonstrates different pipeline source types
+
+merge-request-job:
+  stage: test
+  script:
+    - echo "Running merge request specific tests"
+    - echo "Pipeline source: $CI_PIPELINE_SOURCE"
+    - echo "Merge request ID: $CI_MERGE_REQUEST_IID"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: always
+    - when: never
+
+trigger-job:
+  stage: build
+  script:
+    - echo "Running downstream pipeline job"
+    - echo "Pipeline source: $CI_PIPELINE_SOURCE"
+    - echo "Triggered by: $CI_PIPELINE_TRIGGER_ID"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "trigger"
+      when: always
+    - when: never
+
+multi-project-job:
+  stage: deploy
+  script:
+    - echo "Running multi-project pipeline job"
+    - echo "Pipeline source: $CI_PIPELINE_SOURCE"
+    - echo "Project path: $CI_PROJECT_PATH"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "pipeline"
+      when: always
+    - when: never
diff --git a/examples/scheduled-pipeline-testing/.gitlab-ci/scheduled-pipeline.yml b/examples/scheduled-pipeline-testing/.gitlab-ci/scheduled-pipeline.yml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2025, Timo Pallach (timo@pallach.de).
+
+# Scheduled pipeline components
+# This file is included when CI_PIPELINE_SOURCE == "schedule"
+
+scheduled-maintenance-job:
+  stage: prepare
+  script:
+    - echo "Running scheduled maintenance tasks"
+    - echo "Pipeline source: $CI_PIPELINE_SOURCE"
+    - echo "Schedule name: $SCHEDULE_NAME"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      when: always
+    - when: never
+
+daily-check-job:
+  stage: test
+  script:
+    - echo "Running daily health checks"
+    - echo "Pipeline source: $CI_PIPELINE_SOURCE"
+    - echo "Schedule name: $SCHEDULE_NAME"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULE_NAME == "Daily Check"
+      when: always
+    - when: never
+
+weekly-cleanup-job:
+  stage: deploy
+  script:
+    - echo "Running weekly cleanup tasks"
+    - echo "Pipeline source: $CI_PIPELINE_SOURCE"
+    - echo "Schedule name: $SCHEDULE_NAME"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULE_NAME == "Weekly Cleanup"
+      when: always
+    - when: never