| name | template-to-production |
| description | Convert the migration framework from a template repository to a production-ready operational repository. Use this skill after completing initial setup to finalize documentation, replace placeholder organization references, and transition from setup mode to daily usage mode. |
Template to Production Conversion
Overview
This skill guides you through converting the migration framework from a template repository with setup instructions to a production-ready operational repository focused on daily usage. After completing initial setup (GitHub App creation, secrets configuration, organization updates), this skill helps you:
- Refactor README from setup-focused to usage-focused
- Move detailed setup instructions to SETUP.md for administrators
- Replace all placeholder organization references with actual values
- Confirm all setup steps are complete
- Archive original template documentation
When to Use This Skill
Use this skill when:
- You've completed all initial setup steps (GitHub App, secrets, org configuration)
- You've run at least one successful test migration
- You're ready to transition from "setting up" to "using" the framework
- You want to simplify documentation for end users
- You need to finalize organization-specific customizations
Prerequisites Checklist
Before using this skill, confirm these setup steps are complete:
If any items are incomplete, finish setup before proceeding with this conversion.
Conversion Steps
Step 1: Get Repository Information
First, identify your repository's organization and name:
# Run the script to get repository info
./.github/skills/template-to-production/scripts/Get-RepositoryInfo.ps1
Save these values for reference:
- Organization:
______________________
- Repository:
______________________
- Full name:
______________________
Step 2: Create SETUP.md for Administrators
Move all setup documentation from README.md to a new SETUP.md file for administrators.
Create SETUP.md with this structure:
# Migration Framework Setup and Administration
This document contains setup and administrative information for the migration framework. **End users do not need this documentation** - they should use the issue template to request migrations.
---
## Architecture Overview
[Move the "Architecture Overview" section from README here]
## Initial Setup
[Move all "Setup Instructions" (Steps 1-5) from README here]
### Step 1: Create Your Repository from This Template
[Content from README]
### Step 2: Create a GitHub App
[Content from README]
### Step 3: Get Your App User ID
[Content from README]
### Step 4: Update Configuration with GitHub Copilot
[Content from README]
### Step 5: Configure Secrets
[Content from README]
## Prerequisites
[Move "Prerequisites" section from README here]
## Additional Configuration
[Move "Additional Configuration" section from README here]
## Available Skills
- **[add-custom-properties](.github/skills/add-custom-properties/SKILL.md)** - Add repository metadata
- **[add-import-source](.github/skills/add-import-source/SKILL.md)** - Support new source systems
- **[template-to-production](.github/skills/template-to-production/SKILL.md)** - Convert template to production
## Maintenance
### Regular Tasks
**Monthly:**
- Review migration success rates
- Check for failed migrations
- Update documentation based on common questions
- Review and update dependencies
**Quarterly:**
- Rotate GitHub App credentials
- Review and update source system credentials
- Audit team permissions
Review security best practices
Add support for new source systems
Update workflows based on GitHub Actions changes
Respond to feature requests
Troubleshoot issues
Set up monitoring for:
Migration success rate
Workflow execution time
Common error patterns
Usage statistics (migrations per week)
[Move security content from README here]
[Move "Troubleshooting" section from README here]
Step 3: Create Production-Focused README
Replace the setup-heavy README with usage-focused content.
Update README.md to this structure:
# Repository Migration Framework
[](https://github.com/{YOUR-ORG}/{YOUR-REPO}/actions/workflows/migrate.yml)
[](https://opensource.org/licenses/MIT)
[](https://github.com/PowerShell/PowerShell)
[](https://cli.github.com/)
Automated repository migration framework for {YOUR-ORG}. Migrate repositories from Azure DevOps, BitBucket, SVN, or GitHub with complete automation.
---
## Quick Start
### Request a Repository Migration
1. Go to **[Issues](../../issues)** → **[New Issue](../../issues/new/choose)**
2. Select **"🏃♂️ Repository Creation/Migration"**
3. Fill in the form:
- **Organization:** Select from dropdown
- **Team Name:** Your team identifier (e.g., `platform-team`)
- **Repository Name:** New repository name
- **Source URL:** (Optional) Repository to migrate from
- **Criticality:** `critical` (private) or `non-critical` (internal)
4. Submit and track progress
The migration runs automatically and completes in minutes.
---
## Supported Source Systems
| Source | URL Format | Authentication |
|--------|------------|----------------|
| | | PAT configured |
| | | Username/PAT configured |
| | | Credentials configured |
| | | PAT configured |
| | | No extra auth needed |
---
Every migration automatically:
✅ Creates new GitHub repository with standardized naming
✅ Migrates complete git history (when source provided)
✅ Creates team hierarchy with proper permissions
✅ Configures repository visibility based on criticality
✅ Sets up branch protection rules
✅ Integrates with Azure DevOps boards (for ADO sources)
---
Migrate an entire repository with complete history:
Leave "Only Include Specific Folder" blank
All branches and tags are migrated
Extract a single folder from a larger repository:
Set "Only Include Specific Folder" to folder path (e.g., )
Only that folder's history is preserved
Useful for monorepo splitting
Create an empty repository without migration:
Leave "Source Repository URL" blank
Repository created with README.md only
---
Each repository gets a two-tier team structure:
{team-name} → Maintain permissions
└── {team-name}-admins → Admin permissions
**Permissions by Criticality:**
- **Critical repos:** Private, restricted team access
- **Non-critical repos:** Internal, standard team access
---
## Troubleshooting
### Migration Fails
**Check workflow run:**
1. Go to [Actions](../../actions/workflows/migrate.yml)
2. Click the failed run
3. Review job summary for specific error
**Common issues:**
- Source URL format incorrect
- Authentication not configured for source system
- Team name doesn't follow naming conventions
- Repository name already exists
### Need Help?
- 📖 **View workflow runs:** [Actions page](../../actions)
- 🐛 **Report issues:** [Create issue](../../issues/new)
- 💬 **Contact:** {YOUR-ORG} platform team
- 📚 **Setup documentation:** [SETUP.md](SETUP.md) (for admins)
---
## Administration
Repository administrators can find setup and configuration documentation in [SETUP.md](SETUP.md).
**Admin tasks:**
- Adding new source systems
- Updating secrets and credentials
- Modifying team naming conventions
- Customizing repository properties
- Troubleshooting authentication
---
## Support
**For migration requests:** Use the issue template
**For technical issues:** Contact platform team
**For setup changes:** See [SETUP.md](SETUP.md)
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
## Security
See [SECURITY.md](SECURITY.md) for security policies and reporting vulnerabilities.
## License
This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history.
Step 4: Replace Organization Placeholders
Use the provided script to replace all placeholders with your actual organization:
# Navigate to repository root
cd c:\Users\floreshector\enbridge-enb-migrate
# Run the update script (auto-detects org from git remote)
./.github/skills/template-to-production/scripts/Update-OrganizationPlaceholders.ps1
# Or specify explicitly:
# ./.github/skills/template-to-production/scripts/Update-OrganizationPlaceholders.ps1 -Organization myorg -Repository myrepo
This script will:
- Find ALL files recursively (*.md, *.yml, *.yaml, *.ps1)
- Replace
htekdev with your organization
- Replace
${{ github.repository }} with your org/repo
- Replace
{YOUR-ORG} and {YOUR-REPO} placeholders
- Report all changes made
Step 5: Archive Original Template Documentation
Keep a reference of the original template setup for historical purposes:
# Run the backup script
./.github/skills/template-to-production/scripts/Backup-TemplateDocumentation.ps1
This creates a timestamped backup in docs/archive/ and lists all existing archives.
Step 6: Update Repository Settings
-
Update Repository Description:
- Go to Repository Settings → General
- Set description:
Automated repository migration framework for {YOUR-ORG}
-
Add Repository Topics (for discoverability):
migration
github-actions
automation
repository-management
devops
-
Disable Template Repository (if enabled):
- Repository Settings → General
- Uncheck "Template repository"
-
Update About Section:
- Add link to issue template
- Add link to documentation
Step 7: Verify All Changes
Run comprehensive verification:
# Check for remaining placeholders
./.github/skills/template-to-production/scripts/Test-PlaceholderRemoval.ps1
This script checks for:
- Any remaining
htekdev references
- Placeholder variables like
${{ github.repository }}
- Template placeholders like
{YOUR-ORG}
- Required files (README.md, SETUP.md, docs/archive)
Step 8: Commit and Push Changes
# Stage all changes
git add README.md SETUP.md docs/ .github/
# Commit with descriptive message
git commit -m "docs: Convert from template to production repository
- Refactored README for end-user focus
- Moved setup instructions to SETUP.md for administrators
- Replaced all organization placeholders with actual values
- Archived original template documentation
- Updated repository description and topics
This repository is now production-ready for daily use."
# Push changes
git push origin main
Step 9: Announce to Organization
Prepare an announcement to your organization:
Example Announcement:
## 🎉 New: Automated Repository Migration Framework
We've launched an automated migration framework for {YOUR-ORG}!
**What it does:**
✅ Migrates repos from ADO, BitBucket, SVN, or GitHub
✅ Creates teams and sets up permissions automatically
✅ Preserves complete git history
✅ Configures branch protection and integrations
**How to use:**
1. Go to: [Migration Framework Issues](https://github.com/{YOUR-ORG}/{YOUR-REPO}/issues)
2. Click "New Issue" → "Repository Creation/Migration"
3. Fill out the form
4. Submit and watch it work!
**Documentation:** [README](https://github.com/{YOUR-ORG}/{YOUR-REPO})
**Questions?** Contact the platform team.
Production README Best Practices
Focus on User Actions
Good (Action-oriented):
## Request a Migration
1. Open a new issue
2. Select the migration template
3. Fill in the form
4. Submit
Avoid (Setup-oriented):
## Setup
Before using this framework, you need to:
1. Create a GitHub App
2. Configure secrets
...
Simplify Technical Details
Good (Simple):
The framework migrates your code, history, and branches automatically.
Avoid (Too technical):
The framework uses GitHub App authentication with JWT tokens to create scoped tokens that bypass branch protection...
Emphasize Self-Service
Good:
Request a migration in 2 minutes using our issue template.
Avoid:
Contact the platform team to request a migration.
Post-Conversion Checklist
Confirm all conversion steps are complete:
Rollback Plan
If issues arise after conversion, you can rollback:
# Restore from archive
$latestArchive = Get-ChildItem "docs/archive/TEMPLATE_README_*.md" |
Sort-Object LastWriteTime -Descending |
Select-Object -First 1
if ($latestArchive) {
Copy-Item $latestArchive.FullName "README.md" -Force
Write-Host "✅ Restored README from: $($latestArchive.Name)"
# Commit rollback
git add README.md
git commit -m "Revert README to template version for troubleshooting"
git push
} else {
Write-Host "❌ No archive found"
}
Maintenance After Production
After conversion, maintain the framework:
Regular Updates
Monthly:
- Review migration success rates
- Update documentation based on user feedback
- Check for GitHub Actions updates
Quarterly:
- Rotate credentials
- Review security settings
- Audit team permissions
As Needed:
- Add new source systems
- Update workflows
- Respond to feature requests
Monitoring
Track these metrics:
- Migration success rate
- Workflow execution time
- Common error patterns
- Usage statistics
Related Skills
After production conversion, you may need:
- add-custom-properties: Add organization-specific repository metadata
- add-import-source: Support additional source control systems
Validation
Run the comprehensive validation script to ensure production readiness:
./.github/skills/template-to-production/scripts/Test-ProductionReadiness.ps1
This validates:
- README no longer contains template setup instructions
- SETUP.md exists with admin documentation
- No placeholders remain in main files
- Archive directory created with backups
- Workflow files updated correctly
Additional Resources
Summary
This skill converts your migration framework from a template focused on setup to a production repository focused on daily usage. The key changes are:
- README: Usage-focused documentation for end users
- SETUP.md: Administrative documentation for setup and maintenance
- Placeholders: All org references replaced with actual values
- Archive: Original template documentation preserved for reference
- Repository Settings: Updated for production use
After completing this conversion, your migration framework is ready for your organization to use!
