MokoConsulting/MokoCassiopeia
1
1
Fork 0
Code Issues 2 Pull Requests Actions Packages Releases 1 Activity

Add client fork creation workflow and script

Browse Source 
Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-20 01:38:06 +00:00
parent 084bac383a
commit 64e8db75aa
3 changed files with 652 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
.github/workflows/create-client-fork.yml vendored Normal file
View File

@@ -0,0 +1,164 @@
# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# GitHub Actions Workflow: Create Client Fork Implementation
# This workflow prepares the repository for a client-specific fork by:
# - Copying custom color templates to the appropriate locations
# - Replacing the main README with the client fork README
# - Cleaning up template documentation files
name: Create Client Fork
on:
workflow_dispatch:
inputs:
client_name:
description: 'Client Name (e.g., "Acme Corporation")'
required: true
type: string
confirm:
description: 'Type "CONFIRM" to proceed with fork creation'
required: true
type: string
jobs:
create-fork:
name: Setup Client Fork
runs-on: ubuntu-latest
steps:
- name: Validate confirmation
if: ${{ inputs.confirm != 'CONFIRM' }}
run: |
echo "::error::You must type CONFIRM to proceed with fork creation"
exit 1
- name: Checkout repository
uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Git
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Create client fork branch
run: |
CLIENT_SLUG=$(echo "${{ inputs.client_name }}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
BRANCH_NAME="client-fork/${CLIENT_SLUG}"
git checkout -b "${BRANCH_NAME}"
echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_ENV
echo "CLIENT_SLUG=${CLIENT_SLUG}" >> $GITHUB_ENV
- name: Copy custom color templates
run: |
# Copy the colors_custom.css template to both light and dark mode directories
echo "Copying colors_custom.css to light and dark mode directories..."
cp templates/colors_custom.css src/media/css/colors/light/colors_custom.css
cp templates/colors_custom.css src/media/css/colors/dark/colors_custom.css
# Verify files were created
if [ -f "src/media/css/colors/light/colors_custom.css" ]; then
echo "✓ Created src/media/css/colors/light/colors_custom.css"
else
echo "::error::Failed to create light mode colors_custom.css"
exit 1
fi
if [ -f "src/media/css/colors/dark/colors_custom.css" ]; then
echo "✓ Created src/media/css/colors/dark/colors_custom.css"
else
echo "::error::Failed to create dark mode colors_custom.css"
exit 1
fi
- name: Replace README with client fork README
run: |
echo "Replacing README.md with CLIENT_FORK_README.md..."
# Customize the CLIENT_FORK_README.md with client name
sed "s/\[CLIENT NAME\]/${{ inputs.client_name }}/g" CLIENT_FORK_README.md > README.md
# Update fork information section
CURRENT_DATE=$(date +"%Y-%m-%d")
sed -i "s/\[DATE\]/${CURRENT_DATE}/g" README.md
sed -i "s/\[YOUR-FORK-URL\]/https:\/\/github.com\/${GITHUB_REPOSITORY}/g" README.md
echo "✓ README.md replaced with customized client fork README"
- name: Clean up template files
run: |
echo "Removing template documentation files..."
# Remove the original CLIENT_FORK_README.md
if [ -f "CLIENT_FORK_README.md" ]; then
rm CLIENT_FORK_README.md
echo "✓ Removed CLIENT_FORK_README.md"
fi
# Remove the template README from templates directory
if [ -f "templates/CLIENT_FORK_README_TEMPLATE.md" ]; then
rm templates/CLIENT_FORK_README_TEMPLATE.md
echo "✓ Removed templates/CLIENT_FORK_README_TEMPLATE.md"
fi
# Update templates/README.md to remove references to CLIENT_FORK_README_TEMPLATE.md
if [ -f "templates/README.md" ]; then
sed -i '/CLIENT_FORK_README_TEMPLATE.md/d' templates/README.md
sed -i '/Client Fork README Template/,/^---$/d' templates/README.md
echo "✓ Updated templates/README.md"
fi
# Keep templates/colors_custom.css as specified
echo "✓ Keeping templates/colors_custom.css as template"
- name: Commit changes
run: |
git add .
git status
if git diff --staged --quiet; then
echo "No changes to commit"
else
git commit -m "Setup client fork for ${{ inputs.client_name }}
- Copied colors_custom.css to src/media/css/colors/light/ and dark/
- Replaced README.md with customized CLIENT_FORK_README.md
- Removed CLIENT_FORK_README.md and templates/CLIENT_FORK_README_TEMPLATE.md
- Kept templates/colors_custom.css as template
This commit prepares the repository for ${{ inputs.client_name }}'s custom fork."
echo "✓ Changes committed successfully"
fi
- name: Push branch
run: |
git push origin "${BRANCH_NAME}"
echo "✓ Branch ${BRANCH_NAME} pushed successfully"
- name: Summary
run: |
echo "## Client Fork Setup Complete! 🎉" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Changes Applied" >> $GITHUB_STEP_SUMMARY
echo "- ✓ Copied \`colors_custom.css\` to \`src/media/css/colors/light/\`" >> $GITHUB_STEP_SUMMARY
echo "- ✓ Copied \`colors_custom.css\` to \`src/media/css/colors/dark/\`" >> $GITHUB_STEP_SUMMARY
echo "- ✓ Replaced \`README.md\` with customized client fork README" >> $GITHUB_STEP_SUMMARY
echo "- ✓ Removed \`CLIENT_FORK_README.md\`" >> $GITHUB_STEP_SUMMARY
echo "- ✓ Removed \`templates/CLIENT_FORK_README_TEMPLATE.md\`" >> $GITHUB_STEP_SUMMARY
echo "- ✓ Kept \`templates/colors_custom.css\` as template" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Next Steps" >> $GITHUB_STEP_SUMMARY
echo "1. Review the changes in branch: \`${BRANCH_NAME}\`" >> $GITHUB_STEP_SUMMARY
echo "2. Customize colors in \`src/media/css/colors/light/colors_custom.css\`" >> $GITHUB_STEP_SUMMARY
echo "3. Customize colors in \`src/media/css/colors/dark/colors_custom.css\`" >> $GITHUB_STEP_SUMMARY
echo "4. Update \`README.md\` with client-specific details" >> $GITHUB_STEP_SUMMARY
echo "5. Create a new repository for ${{ inputs.client_name }}" >> $GITHUB_STEP_SUMMARY
echo "6. Push this branch to the new repository" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Branch Information" >> $GITHUB_STEP_SUMMARY
echo "- **Branch Name**: \`${BRANCH_NAME}\`" >> $GITHUB_STEP_SUMMARY
echo "- **Client**: ${{ inputs.client_name }}" >> $GITHUB_STEP_SUMMARY

320
docs/CLIENT_FORK_WORKFLOW.md Normal file
View File

@@ -0,0 +1,320 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
BRIEF: Documentation for client fork creation workflow
-->
# Client Fork Creation Workflow
This document explains how to use the automated client fork creation tools to set up a new client-specific fork of MokoCassiopeia.
---
## Overview
The client fork creation workflow automates the process of preparing a repository for a client-specific fork. It performs the following actions:
1. ✅ Copies `templates/colors_custom.css` to `src/media/css/colors/light/colors_custom.css`
2. ✅ Copies `templates/colors_custom.css` to `src/media/css/colors/dark/colors_custom.css`
3. ✅ Replaces `README.md` with customized `CLIENT_FORK_README.md`
4. ✅ Removes `CLIENT_FORK_README.md` from root
5. ✅ Removes `templates/CLIENT_FORK_README_TEMPLATE.md`
6. ✅ Updates `templates/README.md` to remove fork template references
7. ✅ Keeps `templates/colors_custom.css` as a template for reference
---
## Method 1: GitHub Actions Workflow (Recommended)
### Prerequisites
- Repository admin or maintainer access
- GitHub Actions enabled for the repository
### Steps
1. **Navigate to Actions**
- Go to your repository on GitHub
- Click on the "Actions" tab
2. **Run the Workflow**
- Select "Create Client Fork" from the workflow list
- Click "Run workflow"
- Fill in the required inputs:
- **Client Name**: Full client name (e.g., "Acme Corporation")
- **Confirm**: Type "CONFIRM" to proceed
- Click "Run workflow" button
3. **Monitor Progress**
- The workflow will create a new branch named `client-fork/{client-slug}`
- You can monitor the progress in the Actions tab
- Once complete, you'll see a summary of changes
4. **Review the Branch**
- Navigate to the new branch: `client-fork/{client-slug}`
- Review the changes made
- The README will be customized with the client name
- Custom color files will be in place
5. **Create Client Repository**
- Create a new repository for the client
- Push the branch to the new repository:
```bash
git remote add client-repo <CLIENT_REPO_URL>
git push client-repo client-fork/{client-slug}:main
```
### Workflow Features
- ✅ **Safe Confirmation**: Requires typing "CONFIRM" to prevent accidental runs
- ✅ **Automated Branch Creation**: Creates a properly named branch automatically
- ✅ **Customized README**: Automatically fills in client name and date
- ✅ **Git Tracking**: Commits all changes with a descriptive message
- ✅ **Summary Report**: Provides a complete summary of actions taken
---
## Method 2: Local Bash Script
### Prerequisites
- Git installed on your local machine
- Bash shell (Linux, macOS, or Git Bash on Windows)
- Local clone of the MokoCassiopeia repository
### Steps
1. **Clone the Repository**
```bash
git clone https://github.com/mokoconsulting-tech/MokoCassiopeia.git
cd MokoCassiopeia
```
2. **Make Script Executable**
```bash
chmod +x scripts/create-client-fork.sh
```
3. **Run the Script**
```bash
./scripts/create-client-fork.sh "Client Name"
```
Example:
```bash
./scripts/create-client-fork.sh "Acme Corporation"
```
4. **Confirm Actions**
- The script will show you what it will do
- Type "yes" to proceed
- Review the changes shown
- Type "yes" to commit
5. **Push to New Repository**
```bash
# Add the client's repository as a remote
git remote add client-repo <CLIENT_REPO_URL>
# Push the branch
git push client-repo client-fork/{client-slug}:main
```
### Script Features
- 🎨 **Colored Output**: Easy-to-read colored terminal output
- ✅ **Interactive Confirmation**: Asks for confirmation before making changes
- ✅ **Safety Checks**: Verifies you're in the correct directory
- ✅ **Progress Indicators**: Shows each step as it completes
- ✅ **Git Status**: Shows what files changed before committing
- ✅ **Summary**: Provides a complete summary at the end
---
## What Gets Changed
### Files Created
```
src/media/css/colors/light/colors_custom.css [NEW]
src/media/css/colors/dark/colors_custom.css [NEW]
```
### Files Modified
```
README.md [REPLACED]
templates/README.md [UPDATED]
```
### Files Removed
```
CLIENT_FORK_README.md [DELETED]
templates/CLIENT_FORK_README_TEMPLATE.md [DELETED]
```
### Files Kept
```
templates/colors_custom.css [UNCHANGED]
```
---
## Post-Setup Steps
After running the workflow or script, you should:
1. **Customize Brand Colors**
- Edit `src/media/css/colors/light/colors_custom.css`
- Edit `src/media/css/colors/dark/colors_custom.css`
- Update CSS variables to match client branding
2. **Update README**
- Fill in client-specific contact information
- Add custom notes or configurations
- Update fork URL references
3. **Test Locally**
- Install the template in a local Joomla instance
- Test light and dark modes
- Verify custom colors appear correctly
4. **Create Client Repository**
- Create a new repository for the client
- Push the prepared branch to the new repo
- Set up appropriate access controls
5. **Enable Custom Palette in Joomla**
- Log into Joomla admin
- Navigate to System → Site Templates → MokoCassiopeia
- Under Theme tab, set palette to "Custom"
- Save and test
---
## Troubleshooting
### Workflow Fails with "CONFIRM" Error
**Problem**: Workflow stops immediately with confirmation error.
**Solution**: Make sure you type "CONFIRM" (in all caps) in the confirmation field.
### Script Says "CLIENT_FORK_README.md not found"
**Problem**: Script can't find required files.
**Solution**: Make sure you're running the script from the repository root directory:
```bash
cd /path/to/MokoCassiopeia
./scripts/create-client-fork.sh "Client Name"
```
### Colors Don't Appear After Setup
**Problem**: Custom colors don't show in Joomla.
**Solution**:
1. Enable custom palette in template settings
2. Clear Joomla cache (System → Clear Cache)
3. Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
### Branch Already Exists
**Problem**: Branch name conflicts with existing branch.
**Solution**: Either delete the old branch or choose a different client name:
```bash
# Delete old branch
git branch -D client-fork/{client-slug}
# Or use a more specific client name
./scripts/create-client-fork.sh "Client Name - Division"
```
---
## Examples
### Example 1: Simple Client Fork
```bash
# Using the script
./scripts/create-client-fork.sh "Acme Corporation"
```
This creates:
- Branch: `client-fork/acme-corporation`
- README title: "Acme Corporation - MokoCassiopeia Custom Fork"
### Example 2: Client with Multiple Words
```bash
# Using the script
./scripts/create-client-fork.sh "Global Tech Solutions Inc"
```
This creates:
- Branch: `client-fork/global-tech-solutions-inc`
- README title: "Global Tech Solutions Inc - MokoCassiopeia Custom Fork"
### Example 3: Using GitHub Actions
1. Go to Actions → Create Client Fork
2. Enter: "Mountain View Medical Center"
3. Enter: "CONFIRM"
4. Click "Run workflow"
Result:
- Branch: `client-fork/mountain-view-medical-center`
- README title: "Mountain View Medical Center - MokoCassiopeia Custom Fork"
---
## Best Practices
1. **Naming Convention**: Use the official client name as it should appear in documentation
2. **Branch Management**:
- Keep the branch until the client repository is set up
- Don't merge client fork branches back to main
3. **Custom Colors**:
- Document color choices in README
- Keep a backup of custom color files
- Test in both light and dark modes
4. **Version Tracking**:
- Note the upstream version in fork README
- Track when you last synced with upstream
5. **Security**:
- Don't commit client-specific credentials
- Review custom code before deployment
- Keep client forks private if they contain sensitive branding
---
## Related Documentation
- **[CLIENT_FORK_README.md](../CLIENT_FORK_README.md)** - Full client fork guide
- **[CSS Variables](../docs/CSS_VARIABLES.md)** - Complete CSS variable reference
- **[Main README](../README.md)** - MokoCassiopeia documentation
---
## Support
For issues with the workflow or script:
- Check this documentation first
- Review error messages carefully
- Contact: hello@mokoconsulting.tech
---
**Document Version**: 1.0
**Last Updated**: 2026-02-20
**Maintained by**: Moko Consulting

168
scripts/create-client-fork.sh Executable file
View File

@@ -0,0 +1,168 @@
#!/bin/bash
# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# Script: Create Client Fork Setup
# This script prepares the repository for a client-specific fork by:
# - Copying custom color templates to the appropriate locations
# - Replacing the main README with the client fork README
# - Cleaning up template documentation files
set -e
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Function to print colored output
print_success() { echo -e "${GREEN}✓${NC} $1"; }
print_error() { echo -e "${RED}✗${NC} $1"; }
print_info() { echo -e "${BLUE}ℹ${NC} $1"; }
print_warning() { echo -e "${YELLOW}⚠${NC} $1"; }
# Check if client name is provided
if [ -z "$1" ]; then
print_error "Usage: $0 <CLIENT_NAME>"
echo "Example: $0 \"Acme Corporation\""
exit 1
fi
CLIENT_NAME="$1"
CLIENT_SLUG=$(echo "${CLIENT_NAME}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
BRANCH_NAME="client-fork/${CLIENT_SLUG}"
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║ MokoCassiopeia - Client Fork Setup Script ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""
print_info "Client Name: ${CLIENT_NAME}"
print_info "Branch Name: ${BRANCH_NAME}"
echo ""
# Confirm before proceeding
read -p "Do you want to proceed? (yes/no): " -r
echo
if [[ ! $REPLY =~ ^[Yy]es$ ]]; then
print_warning "Operation cancelled by user"
exit 0
fi
# Check if we're in the right directory
if [ ! -f "CLIENT_FORK_README.md" ]; then
print_error "CLIENT_FORK_README.md not found. Are you in the repository root?"
exit 1
fi
# Create new branch
print_info "Creating branch: ${BRANCH_NAME}"
git checkout -b "${BRANCH_NAME}"
print_success "Branch created"
# Copy custom color templates
print_info "Copying colors_custom.css to light and dark mode directories..."
cp templates/colors_custom.css src/media/css/colors/light/colors_custom.css
cp templates/colors_custom.css src/media/css/colors/dark/colors_custom.css
if [ -f "src/media/css/colors/light/colors_custom.css" ] && [ -f "src/media/css/colors/dark/colors_custom.css" ]; then
print_success "Created src/media/css/colors/light/colors_custom.css"
print_success "Created src/media/css/colors/dark/colors_custom.css"
else
print_error "Failed to create colors_custom.css files"
exit 1
fi
# Replace README with client fork README
print_info "Replacing README.md with CLIENT_FORK_README.md..."
sed "s/\[CLIENT NAME\]/${CLIENT_NAME}/g" CLIENT_FORK_README.md > README.md.new
mv README.md.new README.md
# Update fork information section
CURRENT_DATE=$(date +"%Y-%m-%d")
sed -i.bak "s/\[DATE\]/${CURRENT_DATE}/g" README.md
sed -i.bak "s/\[YOUR-FORK-URL\]/[UPDATE-WITH-YOUR-FORK-URL]/g" README.md
rm -f README.md.bak
print_success "README.md replaced with customized client fork README"
# Clean up template files
print_info "Removing template documentation files..."
if [ -f "CLIENT_FORK_README.md" ]; then
rm CLIENT_FORK_README.md
print_success "Removed CLIENT_FORK_README.md"
fi
if [ -f "templates/CLIENT_FORK_README_TEMPLATE.md" ]; then
rm templates/CLIENT_FORK_README_TEMPLATE.md
print_success "Removed templates/CLIENT_FORK_README_TEMPLATE.md"
fi
# Update templates/README.md
if [ -f "templates/README.md" ]; then
# Create a backup
cp templates/README.md templates/README.md.bak
# Remove references to CLIENT_FORK_README_TEMPLATE.md
sed '/CLIENT_FORK_README_TEMPLATE.md/d' templates/README.md > templates/README.md.tmp
mv templates/README.md.tmp templates/README.md
rm -f templates/README.md.bak
print_success "Updated templates/README.md"
fi
print_success "Keeping templates/colors_custom.css as template"
# Show git status
echo ""
print_info "Git status:"
git status --short
# Commit changes
echo ""
read -p "Commit these changes? (yes/no): " -r
echo
if [[ $REPLY =~ ^[Yy]es$ ]]; then
git add .
git commit -m "Setup client fork for ${CLIENT_NAME}
- Copied colors_custom.css to src/media/css/colors/light/ and dark/
- Replaced README.md with customized CLIENT_FORK_README.md
- Removed CLIENT_FORK_README.md and templates/CLIENT_FORK_README_TEMPLATE.md
- Kept templates/colors_custom.css as template
This commit prepares the repository for ${CLIENT_NAME}'s custom fork."
print_success "Changes committed successfully"
echo ""
print_info "To push this branch, run:"
echo " git push origin ${BRANCH_NAME}"
fi
# Summary
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║ Setup Complete! 🎉 ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""
echo "Changes Applied:"
print_success "Copied colors_custom.css to src/media/css/colors/light/"
print_success "Copied colors_custom.css to src/media/css/colors/dark/"
print_success "Replaced README.md with customized client fork README"
print_success "Removed CLIENT_FORK_README.md"
print_success "Removed templates/CLIENT_FORK_README_TEMPLATE.md"
print_success "Kept templates/colors_custom.css as template"
echo ""
echo "Next Steps:"
echo "1. Review the changes in branch: ${BRANCH_NAME}"
echo "2. Customize colors in src/media/css/colors/light/colors_custom.css"
echo "3. Customize colors in src/media/css/colors/dark/colors_custom.css"
echo "4. Update README.md with client-specific details"
echo "5. Create a new repository for ${CLIENT_NAME}"
echo "6. Push this branch to the new repository"
echo ""