🚀 CredFlow CLI - Ultimate DevOps Automation Tool

A powerful, enterprise-ready command-line tool for automating GitLab workflows, ERPNext integration, and deployment processes.

Built by: Gaurav, Manthan, Sharat

✨ What is CredFlow?

CredFlow is your one-stop solution for automating complex DevOps workflows. Whether you're a beginner or an experienced developer, CredFlow makes it easy to:

• 🔀 Create and manage GitLab merge requests with automatic conflict resolution
• 📦 Deploy patches with smart version management (including addon patches)
• 🔐 Integrate with ERPNext for software release management
• 🏢 Automate enterprise workflows with TOTP authentication
• 📱 Interactive CLI that guides you through every step

🎯 Perfect For

• DevOps Engineers automating deployment pipelines
• Software Developers managing merge requests and releases
• Project Managers tracking software releases in ERPNext
• Enterprise Teams requiring secure, automated workflows
• Beginners who want guided, interactive assistance

🚀 Quick Start (5 Minutes!)

Step 1: Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g credflowcli

# Verify installation
credflow --version

Option 2: Install from source

# Clone the repository
git clone https://gitlab.credenceanalytics.com/sharatyaragatti/CredflowCLI.git
cd CredflowCLI

# Install dependencies
npm install

# Make CLI globally available
npm link

Prerequisites

Required:

• 📦 Node.js >= 18.0.0
• 🔑 GitLab Personal Access Token
• 🏢 ERPNext Credentials (if using ERPNext features)

Optional (for AI-Enhanced Features):

• 🤖 Gemini CLI - For AI-powered tag naming and branch generation
  • Install globally: npm install -g @google/generative-ai-cli or use Gemini CLI
  • Alternative: Set GEMINI_API_KEY environment variable to use API instead
  • Benefits: Intelligent pattern learning from existing tags, smart branch name generation

Step 2: Initialize CredFlow

Run the initialization wizard - it will guide you through everything:

credflow init

The wizard will ask for:

• 🌐 GitLab URL (e.g., https://gitlab.credenceanalytics.com)
• 🔑 GitLab Personal Access Token (we'll show you how to get one)
• 🏢 ERPNext URL (e.g., https://erp.credenceanalytics.com)
• 👤 ERPNext Credentials (username and password)
• 🔐 TOTP Setup (optional, for two-factor authentication)

Step 3: Start Using CredFlow!

# Launch interactive menu
credflow

# Or use specific commands
credflow mr --from-mr "https://gitlab.../merge_requests/123" --target preprod

That's it! You're ready to automate your workflows! 🎉

📋 Complete Feature Guide

🎮 Interactive Mode (Recommended for Beginners)

Simply run credflow to access the interactive menu:

credflow

You'll see options like:

• 📦 Deploy from MR - Automated patch deployment (with Thomas Cook project support!)
• 🔀 Create Merge Request - Smart MR creation
• 📋 Create Patch - Generate deployment patches
• 🔐 Setup TOTP - Two-factor authentication setup
• 🚀 Create Software Release - ERPNext integration
• 🏷️ Create GitLab Tag (from MR) - Generate release tags from merge requests
• 🏢 Test ERP Login - Verify your credentials

🔧 Command Line Mode (For Power Users)

1. 📦 Deploy from Merge Request (Patch Automation)

Deploy a new development patch:

credflow mr --from-mr "https://gitlab.../merge_requests/123" --target preprod

Deploy an addon patch (additional changes to existing deployment):

credflow mr \
  --from-mr "https://gitlab.../merge_requests/124" \
  --target preprod \
  --patch-type addon \
  --original-branch "PREPROD-v6.5.0.286_Update_BBPS_SMS_templates"

What happens behind the scenes:

1. 🔍 Extracts project info from MR URL
2. 🌿 Creates deployment branch with proper naming
3. 🔄 Applies changes from source MR
4. 📤 Pushes to GitLab
5. 🎯 Creates new MR for deployment

2. 🔀 Create Merge Request

Basic MR creation:

credflow mr --source feature/my-feature --target main --title "Add new feature"

Advanced MR with file attachments:

credflow mr \
  --source feature/user-auth \
  --target main \
  --title "Feature: User Authentication" \
  --description "Implements JWT-based authentication" \
  --files ./documentation \
  --report ./test-results.docx \
  --push \
  --merge

3. 🚀 Create Software Release in ERPNext

credflow software-release --mr-url "https://gitlab.../merge_requests/123"

This will:

• 📋 Extract release information from MR
• 🏢 Login to ERPNext with TOTP
• 📝 Create software release record
• 📎 Attach relevant files

4. 🏷️ Create GitLab Tag from Merge Request

Create release tags automatically based on merged MRs:

credflow  # Then select "🏷️ Create GitLab Tag (from MR)"

What happens:

1. 📋 Enter MR URL - Provide the merged MR URL
2. 🏷️ Auto-generate Tag Name - Format: TARGET-vX.X.X.X_SOURCE_BRANCH_NAME
3. 📝 Create Release - Optionally create GitLab release with MR description
4. 🔗 Link Everything - Release includes MR metadata and links

Example Tag Names:

• Source: release/lrs-rbi_2025_07_16 → Tag: PREPROD-v6.5.0.286_lrs-rbi_2025_07_16
• Source: feature/new-api → Tag: PROD-v6.5.0.287_new-api

Features:

• ✅ Follows your naming convention (TARGET-vVERSION_DESCRIPTION)
• ✅ Removes "release/" prefix automatically
• ✅ Uses target branch for tagging (preprod/prod)
• ✅ Creates clean tags (no comments/annotations)
• ✅ Auto-populates release description with MR details
• ✅ Warns if MR is not merged yet

🏗️ Advanced Features

🏢 Thomas Cook Patch Automation (NEW!)

CredFlow automatically detects Thomas Cook projects (mercuryfx/tcil) and uses their specific patch structure and naming conventions.

How It Works

When you use "Deploy from MR" with a Thomas Cook project, CredFlow automatically:

1. 🔍 Detects the Project Type - Recognizes Thomas Cook projects automatically
2. 🏷️ Uses Proper Tag Format - Follows MFXSTD_RETAIL_LIVE_X_X_X_XXX naming convention
3. 🌿 Creates Patch Branch - Branches from UAT/target with cherry-picked commits
4. 📁 Generates Correct Structure:

   MFXSTD_RETAIL_LIVE_5_0_0_439/
   ├── ReleaseNote.txt (with proper metadata format)
   ├── MR_Description.md (template for GitLab)
   ├── code/
   │   ├── new/ (modified files)
   │   └── old/ (original files)
   └── script/
       ├── applyscript.sql
       └── revertscript.sql

Example Usage

# Just use the normal Deploy from MR workflow
credflow

# Select: 📦 Deploy from MR
# Enter Thomas Cook project MR URL
# Select target branch (e.g., uat)
# CredFlow will detect it's Thomas Cook and handle the rest!

What You Get

• ✅ Proper ReleaseNote.txt with all required fields
• ✅ MR description template following Thomas Cook format
• ✅ Automatic tag versioning (analyzes existing tags)
• ✅ Cherry-pick support for merge commits
• ✅ Issue tracking integration
• ✅ Database change management
• ✅ Structured patch directory

Thomas Cook ReleaseNote.txt Format

patch_no:MFXSTD_RETAIL_LIVE_5_0_0_439
codebase:1
prev_patch_no:MFXSTD_RETAIL_LIVE_5_0_0_438
release_date:13-10-2025
released_by:Your Name
isaddon:no
parentaddon:MFXSTD_RETAIL_LIVE_5_0_0_439
codechanges:yes
object1:file#filename.jds#Framewrk#0.0.0.1#modify#comment.
total_no_objects:2
dbchanges:no
comments:
authorised_by:Approver Name
qa_certified:yes

🤖 AI-Enhanced Tag Naming

CredFlow now supports intelligent tag naming and branch generation powered by Google Gemini AI. The AI learns from your existing project tags to automatically generate branch names that follow your project's conventions.

Features

• 🎯 Pattern Learning - Analyzes recent tags to detect naming conventions
• 🏷️ Smart Branch Generation - Creates branch names matching your project style
• 📝 Intelligent Descriptions - Converts MR titles to tag descriptions following detected patterns
• 🔄 Automatic Version Increment - Correctly increments version numbers based on target branch
• 🎨 Style Detection - Recognizes casing (lowercase, Title_Case), separators, and abbreviations
• ⚡ Hybrid Approach - Falls back to regex-based analysis if AI is unavailable

Setup Options

Option 1: Use Local Gemini CLI (No API Key Required)

# Install Gemini CLI globally
npm install -g @google/generative-ai-cli

# CredFlow will automatically detect and use it
credflow mr --from-mr "https://gitlab.../123" --target prod

Option 2: Use Gemini API

# Set API key in environment
export GEMINI_API_KEY="your-api-key-here"

# Or add to ~/.credflow.env
echo "GEMINI_API_KEY=your-api-key-here" >> ~/.credflow.env

How It Works

1. Fetches Recent Tags - Retrieves 30 most recent tags from your project
2. Filters by Target - Analyzes only tags relevant to target branch (PROD/PREPROD/UAT)
3. Pattern Analysis - AI identifies:
   • Version format (4-part, 5-part, semver)
   • Prefix patterns (PROD-, PREPROD-, UAT-)
   • Description style (lowercase_with_underscores, Title_Case, etc.)
   • Separator usage (underscore, hyphen)
4. Smart Generation - Creates new branch name with:
   • Correct version increment (e.g., PROD-v6.5.0.222 → PROD-v6.5.0.223)
   • Matching description style from MR title
   • Project-specific conventions

Example

Input:

• Target: master (maps to PROD)
• MR Title: "Update BBPS SMS templates"
• Latest Tag: PROD-v6.5.0.222_Cross_Currency_Split

AI Output:

release/PROD-v6.5.0.223_update_bbps_sms_templates

✅ Correct prefix (PROD) ✅ Incremented version (223) ✅ Lowercase style (matching existing tags) ✅ Underscore separators

Confidence Score: AI provides confidence (0-1) for generated names. CredFlow uses AI suggestions only if confidence ≥ 0.7

🔐 TOTP (Two-Factor Authentication) Setup

CredFlow supports secure TOTP authentication for ERPNext. Follow these steps to set up TOTP:

Step 1: Reset OTP Secret in ERPNext

1. 🔐 Login to ERPNext with your regular credentials
2. 👤 Go to My Settings (usually in the user dropdown menu)
3. 🔑 Click on Password button - you'll see a dropdown menu
4. 🔄 Select "Reset OTP Secret" from the dropdown
5. 🚪 Logout of the application completely

Step 2: Get QR Code from Email

1. 🔐 Login again to ERPNext (use regular login, NOT Google login)
2. 📧 Check your email - ERPNext will send you a verification URL
3. 🔗 Click the verification URL from your email
4. 📱 Save the QR code as an SVG file to your local computer

Step 3: Configure CredFlow

Run the interactive setup:

credflow totp

When prompted for QR code:

• 📁 Provide the path to the SVG file you saved
• 📷 Supports multiple formats - PNG, JPG, SVG (SVG recommended)

Options available:

• 📱 Upload QR code image - Use the QR code from ERPNext email
• 🔗 Enter otpauth:// URL - Manual URL entry (if you can extract it)

Example:

# When prompted, provide the SVG file path
Enter QR code image path: /path/to/your/qr-code.svg

📦 Addon Patch System

CredFlow intelligently handles sequential deployments:

Scenario 1: Base Branch → First Addon

• Input: PREPROD-v6.5.0.286_Update_BBPS_SMS_templates
• Output: PREPROD-v6.5.0.286_1_Update_BBPS_SMS_templates

Scenario 2: Addon → Next Addon

• Input: PREPROD-v6.5.0.286_1_Update_BBPS_SMS_templates
• Output: PREPROD-v6.5.0.286_2_Update_BBPS_SMS_templates

Unlimited sequential patches supported! 🔄

⚡ Automatic Conflict Resolution

CredFlow can automatically resolve merge conflicts:

# Prefer source branch changes (for features)
credflow mr --source feature/new-feature --auto-resolve prefer-source

# Prefer target branch changes (for hotfixes)
credflow mr --source hotfix/urgent-fix --auto-resolve prefer-target

# Manual resolution (default)
credflow mr --source my-branch --auto-resolve manual

🛠️ Configuration Guide

🔑 Getting GitLab Personal Access Token

1. 🌐 Log in to your GitLab instance
2. 👤 Go to User Settings → Access Tokens
3. 🆕 Create new token with these scopes:
   • ✅ api - Full API access
   • ✅ read_repository - Read repository access
   • ✅ write_repository - Write repository access
   • ✅ read_user - Read user information
4. 📋 Copy the token (you won't see it again!)

🏢 ERPNext Setup

1. 🌐 Get your ERPNext URL (e.g., https://erp.credenceanalytics.com)
2. 👤 Use your regular ERPNext username/email
3. 🔒 Use your ERPNext password
4. 📱 Set up TOTP for enhanced security (see detailed TOTP setup instructions above)

📁 Global Configuration File

After running credflow init, your global configuration file (~/.credflow.env) will contain:

# GitLab Configuration
GITLAB_URL=https://gitlab.credenceanalytics.com
GITLAB_TOKEN=your_gitlab_token_here

# ERPNext Configuration
ERP_URL=https://erp.credenceanalytics.com
[email protected]
ERP_PASSWORD=your_erp_password
ERP_RELEASED_BY_NAME=Your Full Name

# Optional: TOTP for ERPNext (if enabled)
ERP_TOTP_SECRET=your_base32_secret_here

🌟 Benefits of Global Configuration:

• ✅ Shared across all projects - No need to set up credentials in each project
• ✅ One-time setup - Configure once, use everywhere
• ✅ Secure location - Stored in your home directory
• ✅ Project-specific overrides - Local .env files can still override global settings if needed

📖 Command Reference

Core Commands

| Command | Description | Example | |---------|-------------|---------| | credflow | 🎮 Launch interactive menu | credflow | | credflow init | 🔧 Initialize CLI with credentials | credflow init | | credflow mr | 🔀 Create/manage merge requests | credflow mr --help | | credflow totp | 🔐 Setup TOTP authentication | credflow totp | | credflow --help | ❓ Show help information | credflow --help |

MR Command Options

| Option | Description | Example | |--------|-------------|---------| | --from-mr <url> | 📦 Deploy from existing MR | --from-mr "https://gitlab.../123" | | --target <branch> | 🎯 Target deployment branch | --target preprod | | --patch-type <type> | 📋 Patch type (new/addon) | --patch-type addon | | --original-branch <name> | 🌿 Original branch for addon | --original-branch "PREPROD-v6.5.0.286_Feature" | | --source <branch> | 🌱 Source branch | --source feature/my-feature | | --push | 📤 Push branch before MR | --push | | --merge | 🔄 Auto-merge after creation | --merge |

🔄 Common Workflows

🚀 Production Deployment Workflow

# 1. Deploy to preprod first
credflow mr \
  --from-mr "https://gitlab.../merge_requests/123" \
  --target preprod

# 2. Test in preprod environment
# ... run your tests ...

# 3. Deploy to production
credflow mr \
  --from-mr "https://gitlab.../merge_requests/124" \
  --target prod

🔧 Hotfix Workflow

# Deploy urgent hotfix
credflow mr \
  --from-mr "https://gitlab.../merge_requests/urgent-fix" \
  --target prod \
  --auto-resolve prefer-target

📦 Addon Patch Workflow

# Additional changes to existing deployment
credflow mr \
  --from-mr "https://gitlab.../merge_requests/addon-changes" \
  --target preprod \
  --patch-type addon \
  --original-branch "PREPROD-v6.5.0.286_Original_Feature"

🏢 ERPNext Release Workflow

# Create software release in ERPNext
credflow software-release \
  --mr-url "https://gitlab.../merge_requests/123"

🏷️ Tag Creation Workflow

# Create a release tag from merged MR
credflow  # Select "🏷️ Create GitLab Tag (from MR)"
# Enter MR URL: https://gitlab.../merge_requests/123
# Result: Creates tag like PREPROD-v6.5.0.286_feature_name
#         with full GitLab release and MR metadata

Complete Release Workflow:

# 1. Deploy to preprod
credflow mr --from-mr "https://gitlab.../MR/123" --target preprod

# 2. Test and validate

# 3. Create release tag (optional)
credflow  # → Create GitLab Tag (from MR) → Enter same MR URL

# 4. Deploy to production
credflow mr --from-mr "https://gitlab.../MR/123" --target prod

# 5. Create production tag
credflow  # → Create GitLab Tag (from MR) → Enter prod MR URL

🚨 Troubleshooting

❌ Common Issues & Solutions

Problem: "CredFlow CLI is not initialized"

# Solution: Run initialization
credflow init

Problem: "Failed to resolve project from MR URL"

# Solution: Check MR URL format
# Correct: https://gitlab.../namespace/project/-/merge_requests/123
# Wrong: https://gitlab.../merge_requests/123

Problem: "ERPNext login failed"

# Solution: Check credentials and run
credflow # Then select "Test ERP Login"

Problem: "TOTP authentication failed"

# Solution: Re-setup TOTP
credflow totp

Problem: "Merge conflicts detected"

# Solution: Use auto-resolution or resolve manually
credflow mr --source my-branch --auto-resolve prefer-source

🐛 Debug Mode

Enable detailed logging:

# Set in .env file
LOG_LEVEL=debug

# Or run with debug
DEBUG=* credflow mr --source my-branch

📞 Getting Help

1. 📖 Check command help: credflow --help or credflow mr --help
2. 🎮 Use interactive mode: credflow (guides you through everything)
3. 📝 Check logs: Look at credflow.log for detailed information
4. 🔍 Debug mode: Set LOG_LEVEL=debug in .env

🏗️ For Developers

📁 Project Structure

CredflowCLI/
├── 📁 bin/
│   └── credflow.js              # 🎯 Main CLI entry point
├── 📁 src/
│   ├── 📁 config/
│   │   └── index.js             # ⚙️ Configuration management
│   ├── 📁 modules/
│   │   ├── gitlab.js            # 🦊 GitLab API integration
│   │   ├── git-operations.js    # 🌿 Git operations
│   │   ├── erp.js               # 🏢 ERPNext integration
│   │   └── prompt-flows.js      # 🎮 Interactive flows
│   ├── 📁 utils/
│   │   ├── logger.js            # 📝 Logging utility
│   │   ├── project-resolver.js  # 🔍 Project resolution
│   │   └── version-manager.js   # 🏷️ Version management
│   └── 📁 commands/
│       └── patch-create.js      # 📦 Patch creation
├── 📄 .env.example              # 📋 Environment template
├── 📄 package.json              # 📦 Project metadata
└── 📖 README.md                 # 📚 This documentation

🧪 Running Tests

# Run test suite
npm test

# Run with coverage
npm run test:coverage

# Lint code
npm run lint

🔄 Development Workflow

1. 🌿 Create feature branch: git checkout -b feature/my-feature
2. 🛠️ Make changes and test
3. ✅ Run tests: npm test
4. 🔍 Lint code: npm run lint
5. 📝 Commit changes: Use conventional commits
6. 🚀 Create MR: Use CredFlow itself! credflow mr --source feature/my-feature

🔮 Future Features

• [x] 🤖 AI-powered tag naming and branch generation ✨ NEW!
• [ ] 🐳 Docker integration for containerized deployments
• [ ] 🔔 Slack/Teams notifications for deployment status
• [ ] 📊 Dashboard integration for release tracking
• [ ] 🤖 AI-powered conflict resolution suggestions
• [ ] 🌐 Multi-platform support (Jenkins, Azure DevOps)
• [ ] 📱 Mobile app for deployment approvals
• [ ] 🔍 Advanced analytics and reporting

📜 License

MIT License - feel free to use in your projects!

👥 Contributing

We welcome contributions! Here's how:

1. 🍴 Fork the repository
2. 🌿 Create feature branch: git checkout -b feature/amazing-feature
3. 💻 Make your changes
4. ✅ Test thoroughly
5. 📝 Follow commit conventions
6. 🚀 Create merge request (use CredFlow!)

🙏 Credits

Core Team:

• 👨‍💻 Gaurav - Architecture & GitLab Integration
• 👨‍💻 Manthan - Git Operations & Conflict Resolution
• 👨‍💻 Sharat - CLI Interface & ERPNext Integration

Special Thanks:

• 🏢 Credence Analytics for supporting this project
• 🌟 Open Source Community for inspiration and tools

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitLab Issues
• 📖 Documentation: This README + credflow --help

Made with ❤️ by the CredFlow Team

Automate your workflows, focus on what matters! 🚀