Add automated client fork creation workflow #79
136
.github/workflows/create-client-fork.yml
vendored
136
.github/workflows/create-client-fork.yml
vendored
@@ -1,16 +1,13 @@
|
||||
---
|
||||
|
|
||||
# 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:
|
||||
"on":
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
client_name:
|
||||
@@ -18,7 +15,7 @@ on:
|
||||
required: true
|
||||
type: string
|
||||
confirm:
|
||||
description: 'Type "CONFIRM" to proceed with fork creation'
|
||||
description: 'Type "CONFIRM" to proceed'
|
||||
required: true
|
||||
type: string
|
||||
|
||||
@@ -26,139 +23,128 @@ 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"
|
||||
echo "::error::Type CONFIRM to proceed"
|
||||
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 ' ' '-')
|
||||
CLIENT_NAME="${{ inputs.client_name }}"
|
||||
CLIENT_SLUG=$(echo "${CLIENT_NAME}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
|
||||
BRANCH_NAME="client-fork/${CLIENT_SLUG}"
|
||||
git checkout -b "${BRANCH_NAME}"
|
||||
`CLIENT_SLUG` is derived only by lowercasing and replacing spaces. Client names containing characters like `/`, `&`, `.`, or multiple whitespace can produce invalid git branch names (and could also lead to awkward paths in automation output). Consider sanitizing to `[a-z0-9-]`, collapsing runs of `-`, and trimming leading/trailing dashes before forming `BRANCH_NAME`.
```suggestion
CLIENT_SLUG=$(
printf '%s' "${CLIENT_NAME}" \
| tr '[:upper:]' '[:lower:]' \
| sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
)
```
|
||||
echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_ENV
|
||||
|
`git checkout -b "${BRANCH_NAME}"` will fail if the branch already exists (e.g., reruns for the same client). Consider adding an explicit existence check and emitting a clear `::error::` message (or switching to `git checkout -B` if overwriting is acceptable) so the failure mode is predictable.
```suggestion
BRANCH_NAME="client-fork/${CLIENT_SLUG}"
if git rev-parse --verify "${BRANCH_NAME}" >/dev/null 2>&1; then
echo "::error::Branch ${BRANCH_NAME} already exists. Aborting to avoid overwriting existing client fork."
exit 1
fi
```
|
||||
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..."
|
||||
echo "Copying colors_custom.css..."
|
||||
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"
|
||||
echo "✓ Created light mode 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"
|
||||
echo "✓ Created dark mode 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
|
||||
echo "Replacing README.md..."
|
||||
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"
|
||||
|
||||
|
||||
echo "✓ README.md replaced"
|
||||
|
||||
|
The sed replacement uses the raw The sed replacement uses the raw `inputs.client_name` as the replacement string. If the client name contains characters meaningful to sed replacements (e.g., `&`, `/`, or backslashes), README generation can break or produce incorrect output. Escape the replacement string before substituting, or use a tool/approach that safely handles arbitrary text.
|
||||
- name: Clean up template files
|
||||
run: |
|
||||
echo "Removing template documentation files..."
|
||||
|
||||
# Remove the original CLIENT_FORK_README.md
|
||||
echo "Removing template files..."
|
||||
|
||||
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
|
||||
|
The workflow removes The workflow removes `CLIENT_FORK_README.md` but the `templates/README.md` edits only remove the client fork template section. `templates/README.md` still contains links/instructions pointing to `../CLIENT_FORK_README.md`, which will be broken after deletion. Update the cleanup step to remove or rewrite all references to files that are deleted in the fork branch.
```suggestion
sed -i '/Client Fork README Template/,/^---$/d' templates/README.md
sed -i '/CLIENT_FORK_README.md/d' templates/README.md
```
|
||||
|
||||
# Keep templates/colors_custom.css as specified
|
||||
echo "✓ Keeping templates/colors_custom.css as template"
|
||||
|
||||
|
||||
echo "✓ Keeping templates/colors_custom.css"
|
||||
|
||||
- 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"
|
||||
git commit -m "Setup client fork for ${{ inputs.client_name }}" \
|
||||
-m "Copied colors_custom.css to src/media/css/colors/" \
|
||||
-m "Replaced README.md with CLIENT_FORK_README.md" \
|
||||
-m "Removed CLIENT_FORK_README.md" \
|
||||
-m "Removed templates/CLIENT_FORK_README_TEMPLATE.md" \
|
||||
-m "Kept templates/colors_custom.css as template"
|
||||
echo "✓ Changes committed"
|
||||
fi
|
||||
|
||||
|
||||
|
The custom color files you copy into src/media/css/colors/*/colors_custom.css are ignored by .gitignore, so The custom color files you copy into src/media/css/colors/*/colors_custom.css are ignored by .gitignore, so `git add .` will not stage them and the fork branch won’t actually contain the generated color files. Force-add just those files (e.g., explicit `git add -f <paths>`), or adjust the workflow to temporarily override the ignore rules before committing.
|
||||
- name: Push branch
|
||||
run: |
|
||||
git push origin "${BRANCH_NAME}"
|
||||
echo "✓ Branch ${BRANCH_NAME} pushed successfully"
|
||||
|
||||
echo "✓ Branch ${BRANCH_NAME} pushed"
|
||||
|
||||
- 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
|
||||
cat >> $GITHUB_STEP_SUMMARY << EOF
|
||||
## Client Fork Setup Complete! 🎉
|
||||
|
||||
### Changes Applied
|
||||
- ✓ Copied colors_custom.css to src/media/css/colors/
|
||||
- ✓ Replaced README.md
|
||||
- ✓ Removed CLIENT_FORK_README.md
|
||||
- ✓ Removed templates/CLIENT_FORK_README_TEMPLATE.md
|
||||
- ✓ Kept templates/colors_custom.css
|
||||
|
||||
### Next Steps
|
||||
1. Review branch: \`${BRANCH_NAME}\`
|
||||
2. Customize colors in src/media/css/colors/
|
||||
3. Update README.md with client details
|
||||
4. Create new repository for ${{ inputs.client_name }}
|
||||
5. Push branch to new repository
|
||||
|
||||
### Branch Information
|
||||
- **Branch**: \`${BRANCH_NAME}\`
|
||||
- **Client**: ${{ inputs.client_name }}
|
||||
EOF
|
||||
|
||||
@@ -19,6 +19,8 @@
|
||||
|
||||
This is a customized fork of the [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) Joomla template, tailored specifically for [CLIENT NAME]'s website.
|
||||
|
||||
> **💡 Tip**: This fork was likely created using the automated [Client Fork Workflow](./docs/CLIENT_FORK_WORKFLOW.md). If you're creating a new client fork, use the workflow for instant setup!
|
||||
|
||||
---
|
||||
|
||||
## 📋 About This Fork
|
||||
|
||||
@@ -404,7 +404,12 @@ See [Workflow Guide](./docs/WORKFLOW_GUIDE.md) for detailed Git workflow.
|
||||
|
||||
### Client Custom Forks
|
||||
|
||||
Creating a custom fork for client-specific branding and code? See our comprehensive [Client Fork Guide](./CLIENT_FORK_README.md) for:
|
||||
Creating a custom fork for client-specific branding and code?
|
||||
|
||||
**Quick Setup**: Use our automated workflow to create a client fork in minutes:
|
||||
- **[Client Fork Workflow Guide](./docs/CLIENT_FORK_WORKFLOW.md)** - Automated GitHub Actions workflow or local bash script
|
||||
|
||||
**Comprehensive Guide**: See our [Client Fork Guide](./CLIENT_FORK_README.md) for:
|
||||
- Setting up custom color schemes
|
||||
- Maintaining fork-specific customizations
|
||||
- Syncing with upstream updates
|
||||
|
||||
@@ -72,6 +72,12 @@ For end-user documentation, installation instructions, and feature guides, see t
|
||||
|
||||
### Client Fork Documentation
|
||||
|
||||
* **[Client Fork Workflow](CLIENT_FORK_WORKFLOW.md)** - Automated client fork creation
|
||||
* GitHub Actions workflow for instant fork setup
|
||||
* Local bash script alternative
|
||||
* Complete setup automation in minutes
|
||||
* Post-setup customization guide
|
||||
|
||||
* **[Client Fork Guide](../CLIENT_FORK_README.md)** - Comprehensive guide for client custom code forks
|
||||
* Setting up custom branding and colors
|
||||
* Maintaining fork-specific customizations
|
||||
|
||||
Reference in New Issue
Block a user
Workflow does not contain permissions
Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}}
Show more details
Workflow does not contain permissions
Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}}
Show more details