🚀 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!)

$3

Option 1: Install from npm (Recommended)
``bash

Install globally

npm install -g credflowcli

Verify installation

credflow --version
`

Option 2: Install from source
`bash

Clone the repository

git clone https://gitlab.credenceanalytics.com/sharatyaragatti/CredflowCLI.git
cd CredflowCLI

Install dependencies

npm install

Make CLI globally available

npm link
`

$3

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

$3

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

`bash
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)

$3

`bash

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

$3

Simply run credflow to access the interactive menu:

`bash
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

$3

#### 1. 📦 Deploy from Merge Request (Patch Automation)

Deploy a new development patch:
`bash
credflow mr --from-mr "https://gitlab.../merge_requests/123" --target preprod
`

Deploy an addon patch (additional changes to existing deployment):
`bash
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:
`bash
credflow mr --source feature/my-feature --target main --title "Add new feature"
`

Advanced MR with file attachments:
`bash
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

`bash
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:

`bash
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

$3

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

`bash

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
`

---

$3

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)
`bash

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
`bash

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

$3

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:
`bash
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:
`bash

When prompted, provide the SVG file path

Enter QR code image path: /path/to/your/qr-code.svg
`

$3

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! 🔄

$3

CredFlow can automatically resolve merge conflicts:

`bash

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

$3

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!)

$3

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)

$3

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

`env

GitLab Configuration

GITLAB_URL=https://gitlab.credenceanalytics.com
GITLAB_TOKEN=your_gitlab_token_here

ERPNext Configuration

ERP_URL=https://erp.credenceanalytics.com
ERP_USER=your.email@company.com
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

$3

| 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 |

$3

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

---

🔄 Common Workflows

$3

`bash

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
`

$3

`bash

Deploy urgent hotfix

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

$3

`bash

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"
`

$3

`bash

Create software release in ERPNext

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

$3

`bash

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:
`bash

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

$3

Problem: "CredFlow CLI is not initialized"
`bash

Solution: Run initialization

credflow init
`

Problem: "Failed to resolve project from MR URL"
`bash

Solution: Check MR URL format

Correct: https://gitlab.../namespace/project/-/merge_requests/123

Wrong: https://gitlab.../merge_requests/123

`

Problem: "ERPNext login failed"
`bash

Solution: Check credentials and run

credflow # Then select "Test ERP Login"
`

Problem: "TOTP authentication failed"
`bash

Solution: Re-setup TOTP

credflow totp
`

Problem: "Merge conflicts detected"
`bash

Solution: Use auto-resolution or resolve manually

credflow mr --source my-branch --auto-resolve prefer-source
`

$3

Enable detailed logging:

`bash

Set in .env file

LOG_LEVEL=debug

Or run with debug

DEBUG=* credflow mr --source my-branch
`

$3

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

$3

`
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
`

$3

`bash

Run test suite

npm test

Run with coverage

npm run test:coverage

Lint code

npm run lint
`

$3

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: support@credenceanalytics.com
- 🐛 Issues: GitLab Issues
- 📖 Documentation: This README + credflow --help`

---

Made with ❤️ by the CredFlow Team

Automate your workflows, focus on what matters! 🚀