diff --git a/OT-Documentation/Run-Pipeline/README.md b/OT-Documentation/Run-Pipeline/README.md new file mode 100644 index 0000000..a990f53 --- /dev/null +++ b/OT-Documentation/Run-Pipeline/README.md @@ -0,0 +1,222 @@ +image + +# Buildpiper Pipeline Execution Guide + +## Overview + +This document explains how to **create, configure, and execute** a pipeline in Buildpiper for automated CI/CD workflows. + +--- + +## Prerequisites + +* Access to Buildpiper application portal +* Permissions to create and execute pipelines +* Configured environments, services, and job templates +* Access to Git repository + +--- + +## Pipeline Workflow (End-to-End) + +``` +1. Add Pipeline +2. Configure Basic Info +3. Add Stages / Upload YAML +4. Save Workflow +5. Run with Parameters +6. Monitor Execution +7. Approve Stages (if required) +8. Review Results +``` + +--- + +## Step 1: Add New Pipeline + +1. Navigate: **Application → Select Project → Pipeline Overview** +2. Click **+ ADD PIPELINE** → Opens “Setup Pipeline” page. +--- +Screenshot from 2025-10-13 17-05-08 + + +## Step 2: Configure Basic Information + +| **Field** | **Meaning** | **Description** | **Recommended** | +|------------|--------------|-----------------|-----------------| +| **Pipeline Name** | The unique identifier of your pipeline. | Used to distinguish between multiple pipelines (e.g., `demo-deploy`, `prod-pipeline`). Naming should reflect the environment or purpose. | Use clear, descriptive names (e.g., `app1-prod-deploy`). | +| **Version** | Defines the version of the pipeline configuration format or syntax. | Versioning ensures backward compatibility and helps maintain consistency with CI/CD platform updates. | Choose **Version 2** (latest stable format). | +| **Retention Count** | Determines how many past pipeline runs are stored in history. | Old runs are automatically deleted beyond this number, freeing up space and reducing clutter. | Keep **10–50 runs** based on frequency and audit needs. | +| **Pipeline Execution Via** | Specifies how the pipeline can be triggered. | Options include: `Run with Parameters`, `Run with Release Package`, or both. This defines whether manual input or predefined package triggers are allowed. | Select **Both** to support flexibility for both manual and automated runs. | +| **Trigger Type** | Defines what initiates the pipeline execution. | Common triggers include: **Manual** (human-triggered), **Schedule** (cron job), **SCM Poll** (source code change), or **Webhook** (external event). | Use **Manual** for controlled deployments (especially production). | +| **Production Hotfix** | Indicates whether this pipeline is used for urgent fixes in production. | Helps track and categorize high-priority emergency releases or patches. | Set to **No**, unless this is a designated hotfix pipeline. | +| **JIRA Reference Required** | Determines if the pipeline must be linked to a JIRA ticket. | Useful for organizations with strict change management and audit trails. | Set to **No** for non-audit or internal pipelines; **Yes** if under compliance control. | +| **Multi-Service Pipeline** | Enables deployment for multiple microservices in a single execution. | Allows bundling multiple related services or components together to deploy in one go. | Enable **Yes** if your application consists of multiple microservices. | +| **Select Tag During Execution** | Allows users to select an artifact or image tag at runtime. | Useful for controlled rollouts or choosing between versions without code changes. | Mark as **Optional** — use when manual tag control is required. | +| **Tags** | Metadata or keywords used for filtering and searching pipelines. | Helps organize and categorize pipelines in large environments (e.g., `production`, `testing`, `frontend`). | Add tags if needed for better discoverability. | +| **Pipeline Variables** | Dynamic key-value pairs used across pipeline steps. | Useful for managing environment details like namespaces, regions, image names, and configurations. | Define clearly: e.g., `ENV=dev`, `NAMESPACE=demo`, `REGION=us-east1`. | + +image +image + +### - Once filled, it auto-saves and moves to Workflow Editor. +### - Click on the Pipeline name you created, It will open Workflow Editor + + +Screenshot from 2025-10-13 17-11-28 + +--- + +## Step 3: Add Stages + +In the **Workflow Editor**: + +1. Click **ADD NEW STAGE** +2. Set: + + ### **Stage Name:** e.g., Build, Deploy, Test + + image + + ### **Approval Required:** Yes/No + + image + +4. Stage Approval Configurations + + +| **Field** | **Meaning** | **Purpose / Description** | **Recommended Action** | +| ---------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **Any questions before approval?** | Optional prompt for additional clarification from approvers. | Allows you to set a question or note that approvers must review before granting approval. Example: “Has QA testing been validated?” or “Is rollback plan documented?” | Keep **No** if unnecessary, or enable **Yes** with clear, short questions to avoid confusion. | +| **Do you want to push approver name to JIRA?** | Sync approval data with JIRA ticketing system. | When enabled, the name of the person who approved the stage is automatically updated in the linked JIRA ticket, ensuring traceability for change management and audit. | Enable **Yes** for production or audit-heavy environments where approvals must be logged in JIRA. | +| **Do you want to push approver name to ServiceNow?** | Sync approval data with ServiceNow change records. | Similar to JIRA integration — when turned on, the approver’s name is pushed to ServiceNow change request, ensuring compliance and visibility for CAB (Change Advisory Board). | Enable **Yes** for enterprises using **ServiceNow** for ITSM/change management; otherwise **No**. | + + +--- + +## Step 4: YAML Configuration (Optional) + +You can define the pipeline using YAML instead of the visual editor. + +**Example:** + +```yaml +stages: + - stage1: + name: "Build Stage" + jobs: + - job_1: { type: Build, environment: dev, template: build-template } + - job_2: { type: Deploy, environment: dev, template: deploy-template } + - stage2: + name: "Promote Stage" + jobs: + - job_1: { type: Promote, from_env: dev, to_env: qa } +``` + +Upload via **YAML tab → Upload YAML → Save Workflow.** + +--- + +## Step 5: Save Workflow + +Click **Save Workflow** (top-right). +Confirmation: “ Pipeline created successfully.” +Pipeline now visible under **Pipeline Overview**. + +--- + +## Step 6: Run Pipeline with Parameters + +1. Go to **Pipeline Overview → RUN WITH PARAMETERS** +2. Fill required details: + +| Field | Purpose | +| ------------------ | ----------------------------------------------------- | +| **Services** | Select one/multiple services | +| **Branch** | e.g., `main`, `develop`, `feature/...` | +| **Artifact Tag** | Unique build identifier (`v1.0.0`, `release-2025-10`) | +| **Deploy Version** | Deployment label (optional) | + +**Optional Toggles:** + +* **UAT Required:** Pause for approval +* **Link JIRA Issues:** Attach tickets +* **Advanced Config:** Override variables or parameters + +Click **Run Pipeline** to execute. +Screenshot from 2025-10-13 16-31-50 + +--- +## Step 7 : Pending for Approval + +* It will show the Pending for Approval , When we click on the pipeline we created ( e.g Demo 1 , k-demo etc ) there will be one window that will open. Then you have to click on Thumbs up icon for Approval. Then add Comment for same +--- +### 1. Screenshot from 2025-10-13 16-33-31 +--- +### 2. Screenshot from 2025-10-13 16-33-52 +--- +### 3. Screenshot from 2025-10-13 16-34-07 + + +## Step 8: Monitor Execution + +* View live status: **Running, Success, Failed, Pending** +* Each stage shows job count, duration, and logs. +* Click **VIEW LOGS** to inspect build or deploy details. + +--- +Screenshot from 2025-10-13 16-34-32 +--- + +**Indicators:** + +| Color/Icon | Status | +| ---------- | ------- | +| 🟢 Green | Success | +| 🔴 Red | Failed | +| 🟡 Yellow | Running | +| ⚪ Gray | Pending | + +--- + +## Best Practices + +### Configuration + +* Use clear names and tags +* Define key variables early +* Keep retention balanced (10–50) +* Use approvals only for production + +### Execution + +* Always use unique artifact tags +* Monitor logs actively +* Test in non-prod first +* Add meaningful approval comments + +### YAML + +* Validate syntax before upload +* Keep YAML files in Git +* Reuse job templates + +--- + +## Troubleshooting (Quick Fixes) + +| Issue | Solution | +| ------------------- | ---------------------------- | +| YAML errors | Fix indentation / syntax | +| Tag already used | Choose a new unique tag | +| Stage not running | Approvals pending | +| Service not visible | Check Service configuration | +| Pipeline missing | Re-save and refresh overview | + +--- + +**Document Version:** 1.0 +**Last Updated:** 13 October 2025 +**Platform:** Buildpiper + +