MokoCLI/docs/workflows/reserve-dolibarr-module-id.md

Reserve Dolibarr Module ID Workflow

Status: Active | Version: 04.00.04 | Effective: 2026-02-21

Overview

The reserve-dolibarr-module-id.yml workflow automates the reservation of Dolibarr module IDs from the Moko Consulting reserved range. Check the Module Registry for the current next available ID. It simplifies the module ID reservation process by automatically updating the module registry table and creating a pull request for approval.

Quick Links

• Module Registry - Official Dolibarr module number registry
• Run Workflow - Reserve a module ID now
• Development Guide - CRM development guide
• Development Standards - Coding standards

Key Features

• Automatic URL Construction: Repository URL automatically constructed from repo name with mokoconsulting-tech organization
• Simple Input: Only requires repository name - all other details are automatically handled
• Auto-Assignment or Manual ID Selection: Automatically assigns next available ID or accepts manual specification
• Conflict Detection: Validates that the requested ID is not already in use
• Registry Update: Updates the module registry in MokoStandards
• Pull Request Creation: Automatically creates PR with all changes
• Optional Remote Push: Optionally scans the target repository for module ID references ($this->numero, DOLIBARR_MODULE_ID=), updates them, and opens a PR in that repository

Workflow Location

File: .gitea/workflows/reserve-dolibarr-module-id.yml
Trigger: Manual (workflow_dispatch)
Permissions: contents: write, pull-requests: write
Repository: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards

Architecture

Workflow Flow

┌─────────────────────────────────────────────────────────────────┐
│                    WORKFLOW FLOW DIAGRAM                         │
└─────────────────────────────────────────────────────────────────┘

  TRIGGER: Manual Workflow Dispatch
       │
       ▼
  ┌──────────────────┐
  │ Extract Module   │
  │ Name from Repo   │───┐ github.repository → ModuleName
  └──────────────────┘   │
       │                 │
       ▼                 │
  ┌──────────────────┐   │
  │ Determine ID     │◀──┘ Manual or Auto-assign
  │ (see registry)   │
  └──────────────────┘
       │
       ▼
  ┌──────────────────┐
  │ Check for        │
  │ Conflicts        │───┐ Scan registry table
  └──────────────────┘   │
       │                 │
       ▼                 │
  ┌──────────────────┐   │
  │ Update Module    │◀──┘
  │ Registry Table   │
  └──────────────────┘
       │
       ▼
  ┌──────────────────┐
  │ Update Override  │───┐ Protect workflow file
  │ Configuration    │   │
  └──────────────────┘   │
       │                 │
       ▼                 │
  ┌──────────────────┐   │
  │ Create Branch    │◀──┘ reserve-module-id/<id>
  │ and Commit       │
  └──────────────────┘
       │
       ▼
  ┌──────────────────┐
  │ Create Pull      │───┐ Automated PR
  │ Request          │   │
  └──────────────────┘   │
       │                 │
       ├─────────────────┘
       │
       ▼
  ┌──────────────────┐
  │ Push to Remote   │ (Optional)
  │ Repository       │
  └──────────────────┘

Module ID Range

Reserved Range: 185051-185099 (Moko Consulting)
Assignment: Sequential; the workflow scans the module registry for all used IDs and auto-assigns the first free one.

Always check the Module Registry to see which IDs are currently available before making a reservation.

Usage

Basic Usage (Auto-Assign, No Remote Push)

When you want to reserve the next available module ID without pushing to remote:

# Trigger: Actions → Reserve Dolibarr Module ID → Run workflow

Inputs:
  repo_name: "MokoDoliExample"
  module_id: (leave empty for auto-assignment)
  push_to_remote: false

Result:

• Workflow will auto-assign the next available ID (check the registry to see which ID that will be) and create PR
• Repository URL automatically constructed as https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliExample
• Module ID file NOT pushed to remote (you can create it manually later)

With Remote Push

When you want the workflow to scan the remote repository for existing module ID references, update them, and open a PR:

Inputs:
  repo_name: "MokoDoliSign"
  module_id: 185070
  push_to_remote: true

Result:

• Workflow will validate and reserve ID 185070 (if available)
• Repository URL automatically constructed as https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliSign
• Scans PHP files for $this->numero = <number> and updates them to $this->numero = 185070
• Scans other files for DOLIBARR_MODULE_ID=<number> and updates them
• Creates src/DOLIBARR_MODULE_ID.txt with the reserved ID
• Opens a PR in the remote repository with all changes

Workflow Inputs

Required Inputs

Input	Type	Description	Example
repo_name	string	Repository name (org automatically set to mokoconsulting-tech)	"MokoDoliExample"

Note: The repository URL is automatically constructed as https://git.mokoconsulting.tech/mokoconsulting-tech/{repo_name}.

Optional Inputs

Input	Type	Default	Description
module_id	number	(auto-assign)	Specific module ID to assign (185064-185099)
push_to_remote	boolean	false	Scan remote repository for module ID references, update them, and open a PR with the new ID

What the Workflow Does

1. Module Name and URL Construction

The workflow uses the provided repo_name input and automatically constructs the full repository URL:

# Example transformations:
repo_name: "MokoDoliExample" → https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliExample
repo_name: "MokoDoliSign"   → https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliSign
repo_name: "MyModule"       → https://git.mokoconsulting.tech/mokoconsulting-tech/MyModule

Note: The organization is always mokoconsulting-tech and cannot be changed.

2. Module ID Determination

Auto-Assignment Mode (default):

• Scans module registry for used IDs in range 185064-185099
• Assigns first available ID sequentially
• Fails if all IDs are reserved

Manual Assignment Mode:

• Validates ID is in range 185064-185099
• Checks for conflicts
• Fails if ID is already in use

3. Registry Table Update

Updates docs/development/crm/module-registry.md:

| Module Name | Module Number | Status | Description | Repository |
|-------------|---------------|--------|-------------|------------|
| MokoDoliExample | 185064 | Reserved | Example module | https://git.mokoconsulting.tech/mokoconsulting-tech/repo |

Insertion Point: Before the "Available for Assignment" line.

4. Override Configuration Update

Updates override.config.tf to protect the workflow file:

{
  path   = ".gitea/workflows/reserve-dolibarr-module-id.yml"
  reason = "Dolibarr module ID reservation workflow"
},

Purpose: Prevents the workflow file from being overwritten during bulk sync operations.

5. Pull Request Creation

Creates a PR with:

• Branch: reserve-module-id/<module_id>
• Title: "Reserve Dolibarr Module ID {id} for {module_name}"
• Labels: dolibarr, module-id-reservation, automated
• Description: Comprehensive details about the reservation

6. Optional Remote Push

If push_to_remote is enabled, the workflow:

1. Clones the remote repository using GH_TOKEN for authentication
2. Creates a new branch reserve-module-id/<ID> in the remote repo
3. Creates src/DOLIBARR_MODULE_ID.txt with the reserved ID
4. Scans all PHP files for the $this->numero = <number> pattern and updates every match to the new ID
5. Scans all other files for DOLIBARR_MODULE_ID=<number> and updates every match
6. Commits all changes to the new branch
7. Opens a PR in the remote repository via the GitHub CLI

The generated src/DOLIBARR_MODULE_ID.txt contains:

DOLIBARR_MODULE_ID=185064

This module ID has been officially reserved in MokoStandards.

Module Name: MokoDoliExample
Module ID: 185064
Reserved Range: 185051-185099 (Moko Consulting)
Description: Dolibarr module MokoDoliExample

Reserved: 2026-02-19 16:30:00 UTC

DO NOT CHANGE THIS ID!

This ID is registered in the MokoStandards module registry:
https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/development/crm/module-registry.md

If push_to_remote is disabled (default), you can manually create this file and update the module descriptor later.

Workflow Steps

Detailed Step Breakdown

1. Checkout repository - Fetches MokoStandards repository
2. Configure Git - Sets up git credentials for commits
3. Extract module name - Uses provided repo_name and constructs full URL
4. Determine module ID - Auto-assigns or validates manual ID
5. Check for conflicts - Ensures ID is available
6. Update registry table - Adds new entry to registry with auto-generated description
7. Update override config - Protects workflow file
8. Create branch and commit - Commits changes to new branch
9. Create pull request - Automated PR creation
10. Add labels - Tags PR with relevant labels
11. Push to remote - (Optional) Scans remote repo for module ID patterns, updates them, and opens a PR if enabled
12. Output summary - Displays reservation summary

Output

GitHub Actions Summary

The workflow generates a summary with:

## 🎉 Module ID Reservation Summary

**Module Name:** MokoDoliExample
**Reserved ID:** 185064
**Repository:** https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliExample
**Pull Request:** https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/pull/123

### Next Steps
1. The GitHub Actions workflow has created the pull request above automatically
2. Review the pull request
3. Get approval from CRM Development Lead
4. Merge the PR to officially reserve the module ID
5. Verify DOLIBARR_MODULE_ID.txt was created in https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliExample

Files Modified

In MokoStandards Repository:

• docs/development/crm/module-registry.md - Registry table updated
• override.config.tf - Workflow protection added

In Remote Repository (when push_to_remote is enabled):

• src/DOLIBARR_MODULE_ID.txt — module ID file created
• PHP module descriptor(s) — $this->numero updated to the reserved ID
• Any other files containing DOLIBARR_MODULE_ID= — updated to the reserved ID
• A PR is opened in the remote repository on branch reserve-module-id/<ID>

Error Handling

Common Errors and Solutions

Error: "Module ID already in use"

Cause: The requested module ID is already reserved in the registry.

Solution:

• If auto-assigning: Workflow will try next available ID
• If manual: Choose a different ID or use auto-assignment

# Check available IDs
grep -E "185064|185065|185066" docs/policy/crm/development-standards.md

Error: "Module ID must be in range 185064-185099"

Cause: Manual module_id is outside the allowed range.

Solution: Use an ID between 185064 and 185099 (inclusive).

Error: "No available module IDs in range 185064-185099"

Cause: All 36 IDs in the range are already reserved.

Solution: Contact repository maintainers to discuss expanding the range or removing obsolete reservations.

Error: "push_to_remote is enabled but remote_repository is not provided"

This error no longer applies - The workflow now always pushes to the remote repository automatically constructed from the repo name.

Error: "Could not find 'Available for Assignment' line in registry"

Cause: Registry table structure has changed.

Solution: Verify docs/policy/crm/development-standards.md contains the "Available for Assignment" marker line.

Best Practices

Reservation Guidelines

1. Use Descriptive Names: Module name should clearly indicate purpose
2. Provide Accurate Descriptions: Help others understand the module
3. Reserve Before Development: Reserve ID before starting module development
4. One ID Per Module: Each module should have exactly one ID
5. Update Status: Change from "Reserved" to "Active" once deployed

Module Naming Conventions

• Prefix with "MokoDoli": Indicates Moko Consulting Dolibarr module
• CamelCase: Use PascalCase for module names
• Descriptive: Name should indicate functionality

Examples:

• ✅ MokoDoliSign - Clear, follows conventions
• ✅ MokoDoliForm - Concise, descriptive
• ❌ my-module - Not CamelCase, not descriptive
• ❌ Test123 - Not descriptive

Repository Structure

After reservation, structure your Dolibarr module repository:

MokoDoliExample/
├── src/
│   ├── DOLIBARR_MODULE_ID.txt       # Created by workflow
│   └── modMokoDoliExample.class.php # Module descriptor
├── class/                            # Business logic
├── langs/                            # Translations
│   ├── en_US/
│   └── fr_FR/
├── sql/                              # Database scripts
├── admin/                            # Admin pages
├── README.md
└── CHANGELOG.md

Integration with MokoStandards

Module Registry

The workflow updates the official module registry at: docs/policy/crm/development-standards.md

This registry is the single source of truth for all Moko Consulting Dolibarr module IDs.

Override Protection

The workflow protects itself from being overwritten during bulk repository sync operations by adding an entry to override.config.tf.

Policy Compliance

This workflow follows the module ID reservation process defined in: CRM Development Standards

Advanced Usage

Batch Reservations

For reserving multiple module IDs, run the workflow multiple times. Each run will auto-assign the next available ID.

# First run: Reserves 185064
# Second run: Reserves 185065
# Third run: Reserves 185066

Checking Available IDs

To see which IDs are still available:

cd /home/runner/work/MokoStandards/MokoStandards
grep -oP '(?<=\| )1850(6[4-9]|[7-8][0-9]|9[0-9])(?= \|)' \
  docs/policy/crm/development-standards.md | sort -n

Updating Reserved Status

Once a module is deployed, update its status from "Reserved" to "Active":

1. Edit docs/policy/crm/development-standards.md
2. Change status column from "Reserved" to "Active"
3. Update repository URL if needed
4. Create PR with changes

Troubleshooting

Workflow Run Failed

Check the Actions tab: Review the failed step for error messages.

Common issues:

• YAML syntax errors (validate with yamllint)
• Git configuration issues
• Permission errors
• Network connectivity to remote repository

PR Creation Failed

Possible causes:

• Insufficient permissions
• Base branch doesn't exist
• Branch already exists

Solution: Check workflow permissions in repository settings.

Remote Push Failed

Causes:

• GH_TOKEN secret not set or lacks write access to the remote repository
• Invalid repository name (remote repo does not exist)
• Branch reserve-module-id/<ID> already exists in the remote repo

Solution:

• Verify repository URL is correct
• Ensure GitHub token has push permissions
• Check default branch name (main vs master)

ID Conflict After Merge

If two PRs reserve the same ID simultaneously:

1. The first merged PR wins
2. The second PR will show conflicts
3. Close the second PR and re-run the workflow
4. The workflow will auto-assign the next available ID

Maintenance

Updating the Workflow

When updating the workflow:

1. Update the VERSION field in the file header
2. Update this documentation
3. Test with dry-run if possible
4. Update the workflow inventory

Monitoring

Monitor the module registry regularly:

# Count reserved IDs
grep -c "| Reserved |" docs/policy/crm/development-standards.md

# Count active IDs
grep -c "| Active |" docs/policy/crm/development-standards.md

# Show available slots
echo $((36 - $(grep -cE "185064|185065|..." docs/policy/crm/development-standards.md)))

Examples

Example 1: Simple Reservation (No Remote Push)

# Input
repo_name: "MokoDoliPasskey"
push_to_remote: false

# Result
Module ID: 185064 (auto-assigned)
Module Name: MokoDoliPasskey
Repository URL: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliPasskey
PR Created: #123
Remote File: NOT created (manual creation required)

Example 2: Specific ID with Remote Push

# Input
repo_name: "MokoDoliMulti"
module_id: 185070
push_to_remote: true

# Result
Module ID: 185070 (manual)
Module Name: MokoDoliMulti
Repository URL: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoDoliMulti
PR Created: #124
Remote PR: opened in MokoDoliMulti with $this->numero and DOLIBARR_MODULE_ID.txt updated to 185070

Example 3: Conflict Handling

# First run - Success
module_id: 185065
Result: Reserved successfully

# Second run - Conflict
module_id: 185065
Error: "Module ID 185065 is already in use!"

Security Considerations

Token Permissions

The workflow requires:

• contents: write - To create branches and commits
• pull-requests: write - To create PRs

Remote Repository Access

The workflow interacts with remote repositories using GH_TOKEN, which is an organization-level Actions secret (set under GitHub organization Settings → Secrets and variables → Actions):

• Repository URL is constructed as https://git.mokoconsulting.tech/mokoconsulting-tech/{repo_name}
• GH_TOKEN must have repo (contents write) and pull-requests: write on the target repository
• The workflow creates a branch reserve-module-id/<ID> and opens a PR — it never pushes directly to the default branch
• Because GH_TOKEN is an organization secret it is automatically available to all repositories in the mokoconsulting-tech organization without any per-repo configuration

Protected Files

The workflow file itself is protected via override.config.tf to prevent accidental deletion or modification during bulk sync operations.

Related Documentation

• CRM Development Standards - Module ID reservation policy
• Dolibarr Module Development Guide - Complete development guide
• Dolibarr Workflow Templates - CI/CD templates for modules
• Bulk Repository Sync - Understanding override protection
• Workflow Architecture - Overall workflow design patterns

Changelog

Version 04.00.04 (2026-03-04)

Changed:

• push_to_remote now scans remote repository PHP files for $this->numero = <number> and updates them to the reserved ID
• push_to_remote now scans other files for DOLIBARR_MODULE_ID=<number> and updates them
• push_to_remote now creates a branch reserve-module-id/<ID> and opens a PR in the remote repository instead of pushing directly to the default branch
• Remote push uses GH_TOKEN for authenticated clone and PR creation
• Output summary now shows the remote PR URL when push_to_remote is enabled

Version 04.00.04 (2026-02-21)

Changed:

• Remote push is now optional with push_to_remote input parameter (default: false)
• PR description now shows whether remote push was enabled
• Output summary shows remote push status (Enabled/Skipped)
• Next steps conditional based on push status

Added:

• push_to_remote boolean input parameter (optional, default: false)
• Conditional execution of push step based on push_to_remote value
• Status indicator in workflow outputs

Fixed:

• Push step now skips if push_to_remote is false
• Documentation updated to reflect optional push behavior
• Workflow diagram correctly shows push as "(Optional)"

Version 04.00.04 (2026-02-20)

Changed:

• Simplified workflow inputs to only require repo_name
• Repository URL now automatically constructed as https://git.mokoconsulting.tech/mokoconsulting-tech/{repo_name}
• Organization is always assumed to be mokoconsulting-tech
• Description is automatically generated from module name
• Remote push is now always enabled (no longer optional)

Fixed:

• Removed outdated "(Optional)" label from workflow diagram
• Updated documentation to reflect that remote push is mandatory
• Clarified that DOLIBARR_MODULE_ID.txt is always created in remote repository

Removed:

• description input (auto-generated)
• repository input (auto-constructed)
• push_to_remote input (always true)
• remote_repository input (auto-constructed)
• developer input (removed in v04.00.04)

Added:

• repo_name required input - single field for repository name

Version 04.00.04 (2026-02-19)

Changed:

• Simplified from 866 to 450 lines (48% reduction)
• Removed module documentation generation
• Module name now auto-detected from repository name
• Added optional manual module ID assignment
• Focused on core functionality: ID assignment and registry update only

Added:

• module_id optional input for manual ID assignment
• Automatic module name extraction from repository

Removed:

• Module documentation creation (docs/modules/)
• Module README creation
• Module ID reference file creation
• Override protection for module docs (now only protects workflow)
• Module descriptor template creation in remote repos
• README creation in remote repos

Version 03.00.00 (2026-02-16)

Initial release:

• Full documentation generation
• Registry table updates
• PR automation
• Remote push support

Support

For issues or questions about this workflow:

1. Check this documentation
2. Review the CRM Development Standards
3. Open an issue in the MokoStandards repository
4. Contact the MokoStandards maintainers

---

Last Updated: 2026-02-19
Maintained By: MokoStandards Team
Category: Workflow Documentation

Metadata

Field	Value
Document Type	Workflow Documentation
Domain	Documentation
Applies To	MokoStandards Repository
Jurisdiction	Tennessee, USA
Owner	Moko Consulting
Repo	https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
Path	/docs/workflows/reserve-dolibarr-module-id.md
Version	04.00.04
Status	Active
Last Reviewed	2026-02-19
Reviewed By	Documentation Team

Revision History

Date	Author	Change	Notes
2026-02-19	GitHub Copilot	Initial documentation creation	Comprehensive workflow documentation for v04.00.04