gitlab-pipeline-automator 1.0.0

package/ENV_SETUP.md

@@ -0,0 +1,235 @@
+# Environment Variables Setup Guide
+
+This guide shows you how to set up the `SCRIPTS_PATH` environment variable for the GitLab Pipeline Automator.
+
+## Quick Setup
+
+### macOS / Linux
+
+**Permanent setup (recommended):**
+```bash
+# Add to ~/.zshrc (macOS) or ~/.bashrc (Linux)
+echo 'export SCRIPTS_PATH="/path/to/your/scripts"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Temporary (current session only):**
+```bash
+export SCRIPTS_PATH="/path/to/scripts"
+```
+
+### Windows (PowerShell)
+
+**Permanent setup (recommended):**
+```powershell
+[System.Environment]::SetEnvironmentVariable("SCRIPTS_PATH", "C:\path\to\your\scripts", "User")
+```
+Restart PowerShell after running this command.
+
+**Temporary (current session only):**
+```powershell
+$env:SCRIPTS_PATH="C:\path\to\scripts"
+```
+
+## Step-by-Step Instructions
+
+### macOS
+
+1. **Open Terminal**
+
+2. **Edit your Zsh configuration:**
+   ```bash
+   nano ~/.zshrc
+   ```
+
+3. **Add your environment variables:**
+   ```bash
+   export SCRIPTS_PATH="/Users/yourusername/path/to/scripts"
+   export GITLAB_BASE_URL="https://devops.nhc.sa"
+   export GITLAB_PROJECT_PATH="/ejar3/devs/ejar3-run-script-tool"
+   ```
+
+4. **Save and exit:**
+   - Press `Ctrl + X`
+   - Press `Y` to confirm
+   - Press `Enter` to save
+
+5. **Reload your configuration:**
+   ```bash
+   source ~/.zshrc
+   ```
+
+6. **Verify it's set:**
+   ```bash
+   echo $SCRIPTS_PATH
+   ```
+
+### Linux
+
+1. **Open Terminal**
+
+2. **Edit your Bash configuration:**
+   ```bash
+   nano ~/.bashrc
+   # or
+   nano ~/.bash_profile
+   ```
+
+3. **Add your SCRIPTS_PATH:**
+   ```bash
+   export SCRIPTS_PATH="/home/yourusername/path/to/scripts"
+   ```
+
+4. **Save and reload:**
+   ```bash
+   source ~/.bashrc
+   ```
+
+5. **Verify:**
+   ```bash
+   echo $SCRIPTS_PATH
+   ```
+
+### Windows (PowerShell)
+
+#### Method 1: PowerShell Profile (Recommended)
+
+1. **Open PowerShell**
+
+2. **Check if profile exists:**
+   ```powershell
+   Test-Path $PROFILE
+   ```
+
+3. **Create/edit profile:**
+   ```powershell
+   if (!(Test-Path $PROFILE)) {
+     New-Item -Path $PROFILE -Type File -Force
+   }
+   notepad $PROFILE
+   ```
+
+4. **Add your SCRIPTS_PATH:**
+   ```powershell
+   $env:SCRIPTS_PATH = "C:\Users\YourUsername\path\to\scripts"
+   ```
+
+5. **Save and restart PowerShell**
+
+#### Method 2: System Environment Variables (GUI)
+
+1. **Open System Properties:**
+   - Press `Win + R`
+   - Type `sysdm.cpl` and press Enter
+   - Click "Advanced" tab
+   - Click "Environment Variables"
+
+2. **Add User Variable:**
+   - Under "User variables", click "New"
+   - Variable name: `SCRIPTS_PATH`
+   - Variable value: `C:\Users\YourUsername\path\to\scripts`
+   - Click "OK"
+
+3. **Repeat for other variables**
+
+4. **Restart your terminal/command prompt**
+
+#### Method 3: Command Line (Permanent)
+
+1. **Open PowerShell as Administrator**
+
+2. **Set SCRIPTS_PATH:**
+   ```powershell
+   [System.Environment]::SetEnvironmentVariable("SCRIPTS_PATH", "C:\path\to\scripts", "User")
+   ```
+
+3. **Restart PowerShell**
+
+## Required Environment Variable
+
+| Variable | Description | Example | Required |
+|----------|-------------|---------|----------|
+| `SCRIPTS_PATH` | Path to directory containing Ruby scripts | `/Users/username/scripts` | ✅ **Yes** |
+
+## Optional Environment Variables
+
+These have defaults and are optional:
+
+| Variable | Description | Default Value |
+|----------|-------------|---------------|
+| `GITLAB_BASE_URL` | GitLab instance base URL | `https://devops.nhc.sa` |
+| `GITLAB_PROJECT_PATH` | GitLab project path | `/ejar3/devs/ejar3-run-script-tool` |
+| `CDP_PORT` | Chrome DevTools Protocol port | `9222` |
+| `CHROME_USER_DATA_DIR` | Chrome user data directory | Auto-created in `~/.config/gitlab-pipeline-automator/chrome-profile` |
+| `CHROME_PROFILE_DIR` | Chrome profile directory name | `Default` |
+
+## Verification
+
+After setting up, verify your environment variables:
+
+**macOS / Linux:**
+```bash
+echo $SCRIPTS_PATH
+echo $GITLAB_BASE_URL
+```
+
+**Windows (PowerShell):**
+```powershell
+echo $env:SCRIPTS_PATH
+echo $env:GITLAB_BASE_URL
+```
+
+**Windows (Command Prompt):**
+```cmd
+echo %SCRIPTS_PATH%
+echo %GITLAB_BASE_URL%
+```
+
+## Usage After Setup
+
+Once environment variables are set, you can use the tool without specifying paths:
+
+```bash
+# Before (without env vars):
+gitlab-pipeline-automator \
+  --scripts-path "/path/to/scripts" \
+  -t "ticket" -s "script" -e "service"
+
+# After (with env vars):
+gitlab-pipeline-automator -t "ticket" -s "script" -e "service"
+```
+
+## Troubleshooting
+
+### Variable Not Found
+
+**Problem:** `echo $SCRIPTS_PATH` returns empty
+
+**Solution:**
+1. Make sure you saved the configuration file
+2. Reload your shell: `source ~/.zshrc` (or `~/.bashrc`)
+3. Restart your terminal
+4. Check for typos in variable names
+
+### Changes Not Persisting
+
+**Problem:** Variables work in current session but disappear after closing terminal
+
+**Solution:**
+- Make sure you added them to the correct configuration file:
+  - macOS: `~/.zshrc`
+  - Linux: `~/.bashrc` or `~/.bash_profile`
+  - Windows: PowerShell profile or System Environment Variables
+
+### Path Issues on Windows
+
+**Problem:** Path not working on Windows
+
+**Solution:**
+- Use forward slashes or escaped backslashes:
+  ```powershell
+  # Good
+  $env:SCRIPTS_PATH = "C:/Users/username/scripts"
+  # or
+  $env:SCRIPTS_PATH = "C:\Users\username\scripts"
+  ```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mahad Asif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,432 @@
+# GitLab Pipeline Automator
+
+Automation script for GitLab pipeline management. This tool automatically creates, approves, and monitors GitLab pipelines using browser automation.
+
+## Features
+
+- 🚀 **Automatic Chrome Launch**: Automatically launches Chrome with remote debugging when needed
+- 🔄 **Cross-platform**: Works on macOS, Windows, and Linux
+- ⚙️ **Configurable**: Supports environment variables and CLI options
+- 📦 **NPM Package**: Can be installed globally or used as a module
+- 🎯 **Smart Retry Logic**: Built-in retry mechanisms for reliability
+
+## Installation
+
+### As a Global NPM Package
+
+```bash
+npm install -g gitlab-pipeline-automator
+```
+
+After installation, you can use the `gitlab-pipeline-automator` command from anywhere.
+
+> ⚠️ **Important:** After installation, you'll see setup instructions. Make sure to:
+> 1. Set the `SCRIPTS_PATH` environment variable (see [Environment Variables](#environment-variables) below)
+> 2. Install Playwright browsers: `npx playwright install chromium firefox`
+
+### As a Local Package
+
+```bash
+npm install
+```
+
+Then run with:
+
+```bash
+npm start -- -t <ticket> -s <script> -e <service>
+```
+
+### Install Playwright Browsers
+
+After installation, you need to install Playwright browsers:
+
+```bash
+npx playwright install chromium firefox
+```
+
+## Usage
+
+### Command Line Interface
+
+```bash
+gitlab-pipeline-automator \
+  -t "ticket-description" \
+  -s "script-name" \
+  -e "ejar-service-name" \
+  -b "production"
+```
+
+#### Required Arguments
+
+- `-t, --ticket <ticket>`: Ticket description
+- `-s, --script <script>`: Ruby script filename (without .rb extension)
+- `-e, --ejar-service <service>`: Ejar3 service name
+
+#### Optional Arguments
+
+- `-b, --branch <branch>`: Git branch to use (default: "production")
+- `--scripts-path <path>`: Path to scripts directory (overrides `SCRIPTS_PATH` env var)
+- `--gitlab-url <url>`: GitLab base URL (overrides `GITLAB_BASE_URL` env var)
+- `--project-path <path>`: GitLab project path (overrides `GITLAB_PROJECT_PATH` env var)
+- `--cdp-port <port>`: Chrome DevTools Protocol port (default: 9222)
+- `--chrome-user-data-dir <path>`: Chrome user data directory for saved credentials/login (overrides `CHROME_USER_DATA_DIR` env var)
+- `--chrome-profile-dir <name>`: Chrome profile directory name (default: "Default") (overrides `CHROME_PROFILE_DIR` env var)
+
+### Environment Variables
+
+> 📖 **First-time setup?** See [ENV_SETUP.md](./ENV_SETUP.md) for detailed step-by-step instructions.
+
+The main environment variable you need to set is `SCRIPTS_PATH` - the path to your Ruby scripts directory. This allows you to run the tool without specifying `--scripts-path` every time.
+
+#### Setting Up SCRIPTS_PATH
+
+**macOS / Linux:**
+
+Add to your `~/.zshrc` (or `~/.bashrc` on Linux):
+```bash
+export SCRIPTS_PATH="/path/to/your/scripts"
+```
+
+Then reload:
+```bash
+source ~/.zshrc  # or source ~/.bashrc
+```
+
+**Windows (PowerShell):**
+
+Open PowerShell and run:
+```powershell
+[System.Environment]::SetEnvironmentVariable("SCRIPTS_PATH", "C:\path\to\your\scripts", "User")
+```
+
+Restart PowerShell for changes to take effect.
+
+**Windows (GUI Method):**
+
+1. Press `Win + R`, type `sysdm.cpl`, press Enter
+2. Click "Environment Variables"
+3. Under "User variables", click "New"
+4. Variable name: `SCRIPTS_PATH`
+5. Variable value: `C:\path\to\your\scripts`
+6. Click OK and restart your terminal
+
+> 📖 **For detailed setup instructions, see [ENV_SETUP.md](./ENV_SETUP.md)**
+
+#### Other Optional Environment Variables
+
+You can also set these if needed (they have defaults):
+
+```bash
+export GITLAB_BASE_URL="https://your-gitlab-instance.com"      # Default: https://devops.nhc.sa
+export GITLAB_PROJECT_PATH="/group/project"                     # Default: /ejar3/devs/ejar3-run-script-tool
+export CDP_PORT=9222                                           # Default: 9222
+export CHROME_USER_DATA_DIR="/path/to/chrome/profile"          # Optional
+export CHROME_PROFILE_DIR="Profile 1"                          # Default: Default
+```
+
+#### Setting Up Environment Variables Permanently
+
+To make environment variables persist across terminal sessions, add them to your shell configuration file:
+
+##### macOS / Linux (Bash)
+
+1. Open your shell configuration file:
+   ```bash
+   # For Bash
+   nano ~/.bash_profile
+   # or
+   nano ~/.bashrc
+   
+   # For Zsh (default on macOS)
+   nano ~/.zshrc
+   ```
+
+2. Add the environment variables:
+   ```bash
+   export SCRIPTS_PATH="/path/to/your/scripts"
+   export GITLAB_BASE_URL="https://devops.nhc.sa"
+   export GITLAB_PROJECT_PATH="/ejar3/devs/ejar3-run-script-tool"
+   export CDP_PORT=9222
+   ```
+
+3. Save and reload:
+   ```bash
+   # Reload the configuration
+   source ~/.zshrc  # or ~/.bashrc
+   ```
+
+##### macOS / Linux (Zsh)
+
+1. Edit `~/.zshrc`:
+   ```bash
+   nano ~/.zshrc
+   ```
+
+2. Add the variables:
+   ```bash
+   export SCRIPTS_PATH="/path/to/your/scripts"
+   export GITLAB_BASE_URL="https://devops.nhc.sa"
+   export GITLAB_PROJECT_PATH="/ejar3/devs/ejar3-run-script-tool"
+   ```
+
+3. Reload:
+   ```bash
+   source ~/.zshrc
+   ```
+
+##### Windows (PowerShell)
+
+1. Open PowerShell as Administrator
+
+2. Set user-level environment variable:
+   ```powershell
+   [System.Environment]::SetEnvironmentVariable("SCRIPTS_PATH", "C:\path\to\scripts", "User")
+   [System.Environment]::SetEnvironmentVariable("GITLAB_BASE_URL", "https://devops.nhc.sa", "User")
+   [System.Environment]::SetEnvironmentVariable("GITLAB_PROJECT_PATH", "/ejar3/devs/ejar3-run-script-tool", "User")
+   ```
+
+3. Restart PowerShell for changes to take effect
+
+**Alternative (PowerShell Profile):**
+
+1. Check if profile exists:
+   ```powershell
+   Test-Path $PROFILE
+   ```
+
+2. Create/edit profile:
+   ```powershell
+   notepad $PROFILE
+   ```
+
+3. Add variables:
+   ```powershell
+   $env:SCRIPTS_PATH = "C:\path\to\scripts"
+   $env:GITLAB_BASE_URL = "https://devops.nhc.sa"
+   $env:GITLAB_PROJECT_PATH = "/ejar3/devs/ejar3-run-script-tool"
+   ```
+
+##### Windows (GUI Method)
+
+1. Open System Properties:
+   - Press `Win + R`, type `sysdm.cpl`, press Enter
+   - Or: Right-click "This PC" → Properties → Advanced system settings
+
+2. Click "Environment Variables"
+
+3. Under "User variables", click "New"
+
+4. Add each variable:
+   - Variable name: `SCRIPTS_PATH`
+   - Variable value: `C:\path\to\scripts`
+   - Click OK
+
+5. Repeat for other variables
+
+6. Restart your terminal/command prompt
+
+#### Verifying Environment Variables
+
+Check if your environment variables are set correctly:
+
+**macOS / Linux:**
+```bash
+echo $SCRIPTS_PATH
+echo $GITLAB_BASE_URL
+```
+
+**Windows (PowerShell):**
+```powershell
+echo $env:SCRIPTS_PATH
+echo $env:GITLAB_BASE_URL
+```
+
+**Windows (Command Prompt):**
+```cmd
+echo %SCRIPTS_PATH%
+echo %GITLAB_BASE_URL%
+```
+
+#### Example: Setting Up SCRIPTS_PATH
+
+If your Ruby scripts are located at `/Users/username/scripts`:
+
+**macOS:**
+```bash
+# Add to ~/.zshrc
+export SCRIPTS_PATH="/Users/username/scripts"
+```
+
+**Windows:**
+```powershell
+# PowerShell
+[System.Environment]::SetEnvironmentVariable("SCRIPTS_PATH", "C:\Users\username\scripts", "User")
+```
+
+After setting up, you can run the tool without specifying `--scripts-path`:
+```bash
+gitlab-pipeline-automator -t "ticket" -s "script" -e "service"
+```
+
+### Using as a Module
+
+```javascript
+import GitLabPipelineAutomator from 'gitlab-pipeline-automator';
+
+const automator = new GitLabPipelineAutomator({
+  scriptsPath: '/path/to/scripts',
+  gitlabBaseUrl: 'https://devops.nhc.sa',
+  gitlabProjectPath: '/ejar3/devs/ejar3-run-script-tool',
+  cdpPort: 9222,
+  chromeUserDataDir: '/path/to/chrome/profile', // Optional: for saved credentials
+  chromeProfileDir: 'Default' // Optional: profile name
+});
+
+// Connect to Chrome (will auto-launch if needed)
+await automator.connectToExistingChrome();
+
+// Navigate and create pipeline
+await automator.navigateToGitlabPipeline();
+await automator.selectBranch('production');
+const script = await automator.readScript('my-script');
+await automator.processCiVariables('ticket-desc', script, 'service-name');
+await automator.waitForPipelinePage();
+
+// Approve and run
+await automator.approvePipelineStage();
+await automator.runPipelineStage();
+
+// Cleanup
+await automator.close();
+```
+
+## How It Works
+
+1. **Browser Connection**: The tool first attempts to connect to an existing Chrome instance with remote debugging enabled. If not found, it automatically launches Chrome with the required flags.
+
+2. **Pipeline Creation**: Navigates to the GitLab pipeline creation page, selects the specified branch, and fills in CI variables (ticket description, service, and script content).
+
+3. **Pipeline Approval**: Waits for the approval stage and automatically clicks the approve button when available.
+
+4. **Pipeline Execution**: Monitors the pipeline execution until completion, reporting success or failure.
+
+## Configuration
+
+### Default Configuration
+
+- **Scripts Path**: `/Users/mahadasif/Desktop/wareef-scripts` (macOS default)
+- **GitLab URL**: `https://devops.nhc.sa`
+- **Project Path**: `/ejar3/devs/ejar3-run-script-tool`
+- **CDP Port**: `9222`
+
+### Chrome Path Detection
+
+The tool automatically detects Chrome installation paths:
+
+- **macOS**: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
+- **Windows**: Checks common installation paths
+- **Linux**: Checks `/usr/bin/google-chrome`, `/usr/bin/chromium`, etc.
+
+### Automatic Login with Chrome Profiles
+
+The tool supports using Chrome user profiles to automatically log in to GitLab using saved credentials. **By default, the tool automatically creates a persistent Chrome profile** to save your login credentials.
+
+#### Automatic Profile Creation (Default Behavior)
+
+When you run the tool for the first time **without** specifying `--chrome-user-data-dir`, it automatically creates a dedicated Chrome profile directory:
+
+**Default Chrome Profile Locations:**
+
+- **macOS**: `~/.config/gitlab-pipeline-automator/chrome-profile`
+  - Full path example: `/Users/username/.config/gitlab-pipeline-automator/chrome-profile`
+  
+- **Windows**: `%APPDATA%\gitlab-pipeline-automator\chrome-profile`
+  - Full path example: `C:\Users\username\AppData\Roaming\gitlab-pipeline-automator\chrome-profile`
+  - Or: `%LOCALAPPDATA%\gitlab-pipeline-automator\chrome-profile` if APPDATA is not available
+  
+- **Linux**: `~/.config/gitlab-pipeline-automator/chrome-profile`
+  - Full path example: `/home/username/.config/gitlab-pipeline-automator/chrome-profile`
+
+**Note:** The exact location is displayed in the console output when the tool runs. The profile persists across runs, so once you log in to GitLab the first time, you'll stay logged in for future runs.
+
+#### Option 1: Use Default Chrome Profile
+
+If you're already logged into GitLab in your regular Chrome browser, the tool will automatically use those credentials when connecting to an existing Chrome instance.
+
+#### Option 2: Use Custom Chrome Profile
+
+You can specify a custom Chrome user data directory to use saved credentials:
+
+```bash
+# Using CLI
+gitlab-pipeline-automator \
+  --chrome-user-data-dir "/Users/username/Library/Application Support/Google/Chrome" \
+  --chrome-profile-dir "Profile 1" \
+  -t "ticket" -s "script" -e "service"
+
+# Using environment variables
+export CHROME_USER_DATA_DIR="/Users/username/Library/Application Support/Google/Chrome"
+export CHROME_PROFILE_DIR="Profile 1"
+gitlab-pipeline-automator -t "ticket" -s "script" -e "service"
+```
+
+#### Finding Your Chrome Profile Path
+
+**macOS:**
+
+```bash
+~/Library/Application Support/Google/Chrome
+```
+
+**Windows:**
+
+```bash
+%LOCALAPPDATA%\Google\Chrome\User Data
+```
+
+**Linux:**
+
+```bash
+~/.config/google-chrome
+```
+
+#### Profile Directory Names
+
+- `Default` - The default profile (most common)
+- `Profile 1`, `Profile 2`, etc. - Additional profiles if you have multiple Chrome profiles
+
+**Note:** 
+- When using a custom profile, Chrome will use saved cookies and session data, so you'll be automatically logged in to GitLab if you've logged in before in that profile.
+- **If you don't specify `--chrome-user-data-dir`, the tool automatically creates a persistent profile** in `~/.config/gitlab-pipeline-automator/chrome-profile` (or equivalent on Windows/Linux) on first run. This profile will persist your login credentials for future runs, so you only need to log in once.
+
+## Requirements
+
+- Node.js >= 14.0.0
+- Google Chrome or Chromium installed
+- Playwright browsers installed (`npx playwright install`)
+
+## Troubleshooting
+
+### Chrome Not Found
+
+If Chrome is not automatically detected, ensure it's installed in a standard location, or set the path manually in the code.
+
+### Connection Issues
+
+If you encounter connection issues:
+
+1. Ensure no other process is using port 9222
+2. Check that Chrome is not already running with remote debugging on a different port
+3. Try closing all Chrome instances and let the tool launch it automatically
+
+### Pipeline Not Found
+
+Ensure your GitLab project path and base URL are correctly configured. The tool expects specific GitLab UI elements - if your GitLab instance uses a different UI, you may need to adjust the selectors in the code.
+
+## License
+
+ISC
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.