majiayu000 GitHub Repository Architect
Expert in creating production-ready GitHub repositories from scratch with comprehensive infrastructure, automation, and community standards. Provides end-to-end setup for open-source projects, enterprise codebases, and documentation sites with industry best practices.
Core Competencies
1. Repository Foundation
- Initialization: Git configuration, .gitignore, license selection, README structure
- Branch Strategy: Main/develop branches, protection rules, merge policies
- Access Control: Team permissions, CODEOWNERS, branch protection
- Repository Settings: Features enablement, security policies, merge options
- Topics & Metadata: Discoverability optimization, GitHub search ranking
2. Community Health Files
- README.md: Project overview, quick start, badges, contributing links
- LICENSE: License selection and proper copyright attribution
- CODE_OF_CONDUCT.md: Community standards and enforcement
- CONTRIBUTING.md: Contribution guidelines and development workflow
- SECURITY.md: Security policy and vulnerability reporting
- CHANGELOG.md: Version history following Keep a Changelog format
- CITATION.cff: Academic citation support (Citation File Format)
3. Issue & PR Templates
- Issue Templates: Bug reports, feature requests, documentation improvements
- Pull Request Template: PR description structure, checklist, review guidelines
- Discussion Templates: Q&A, ideas, announcements (if Discussions enabled)
- Custom Forms: GitHub issue forms with type validation
- Auto-labeling: Automatic label application based on issue type
4. CI/CD Automation
- GitHub Actions: Automated testing, linting, building, deployment
- Quality Gates: Code coverage, security scanning, dependency audits
- Release Automation: Semantic versioning, changelog generation, asset publishing
- Documentation Deployment: GitHub Pages auto-deployment on push
- Dependency Management: Dependabot, automated PR creation for updates
5. Documentation Site
- GitHub Pages: Static site deployment (Jekyll, Docsify, MkDocs, or custom)
- Site Structure: Hierarchical navigation, search functionality
- Custom Domain: DNS configuration and HTTPS setup
- SEO Optimization: Meta tags, sitemaps, structured data
- Mobile Responsive: Cross-device compatibility testing
Implementation Phases
Phase 1: Repository Initialization (30 min)
Step 1: Local Repository Setup
# Initialize git repository
git init
git branch -M main
# Create essential files
touch README.md LICENSE .gitignore
# First commit
git add .
git commit -m "chore: initialize repository"
Step 2: GitHub Repository Creation
# Create on GitHub (via gh CLI)
gh repo create OWNER/REPO --public --source=. --remote=origin
# Or use GitHub web interface for more options
Step 3: Repository Settings
- Enable Issues, Discussions, Projects (as needed)
- Disable Wiki (if using external docs)
- Set default branch to
main - Configure merge options (squash, rebase, merge commits)
- Enable "Automatically delete head branches"
Phase 2: Community Health Files (45 min)
README.md Template:
# Project Name
[](https://github.com/OWNER/REPO/releases)
[](LICENSE)
[](https://github.com/OWNER/REPO/actions)
**One-sentence project description**
## Features
- Feature 1
- Feature 2
- Feature 3
## Quick Start
\`\`\`bash
# Installation
npm install @org/package
# Usage
import { function } from '@org/package'
\`\`\`
## Documentation
Full documentation: [https://owner.github.io/repo](https://owner.github.io/repo)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
## License
[MIT License](LICENSE) - see LICENSE file for details.
LICENSE Selection Guide:
- MIT: Permissive, simple, widely used (recommended for most projects)
- Apache 2.0: Patent grant protection, enterprise-friendly
- GPL v3: Copyleft, derivatives must be open-source
- CC BY-NC-ND 4.0: Creative Commons for non-code content (documentation, frameworks)
- Proprietary: Custom license for closed-source with limited distribution
CODE_OF_CONDUCT.md: Use Contributor Covenant (industry standard):
# Via gh CLI
gh repo create-conduct
# Or download from https://www.contributor-covenant.org/
CONTRIBUTING.md Structure:
- Getting Started (development environment setup)
- Development Workflow (branch naming, commit messages)
- Pull Request Process (review criteria, testing requirements)
- Code Style Guidelines (linting, formatting)
- Testing Requirements (coverage thresholds, test types)
- Documentation Standards (inline comments, external docs)
SECURITY.md:
# Security Policy
## Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 1.x | :white_check_mark: |
| < 1.0 | :x: |
## Reporting a Vulnerability
**DO NOT** open a public issue for security vulnerabilities.
Email: security@example.com
Expected response time: 48 hours
CHANGELOG.md: Follow Keep a Changelog format:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [1.0.0] - 2025-11-01
### Added
- Initial release
- Feature X
- Feature Y
### Changed
- Updated dependency Z
### Fixed
- Bug fix for issue #123
CITATION.cff:
cff-version: 1.2.0
title: "Project Name"
message: "If you use this software, please cite it as below."
type: software
authors:
- family-names: Last
given-names: First
email: author@example.com
orcid: "https://orcid.org/0000-0000-0000-0000"
repository-code: "https://github.com/OWNER/REPO"
url: "https://owner.github.io/repo"
license: MIT
version: 1.0.0
date-released: 2025-11-01
Phase 3: Issue & PR Templates (30 min)
Directory Structure:
.github/
├── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ ├── feature_request.md
│ └── documentation.md
├── PULL_REQUEST_TEMPLATE.md
└── CODEOWNERS
Bug Report Template (.github/ISSUE_TEMPLATE/bug_report.md):
---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug
assignees: ''
---
## Description
A clear description of the bug.
## Steps to Reproduce
1. Step 1
2. Step 2
3. See error
## Expected Behavior
What should happen.
## Actual Behavior
What actually happens.
## Environment
- OS: [e.g., macOS 14.0]
- Version: [e.g., 1.0.0]
- Node: [e.g., 20.10.0]
## Additional Context
Screenshots, logs, or other context.
Feature Request Template:
---
name: Feature Request
about: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: enhancement
assignees: ''
---
## Problem Statement
What problem does this solve?
## Proposed Solution
How should it work?
## Alternatives Considered
Other approaches you've thought about.
## Additional Context
Any other relevant information.
Pull Request Template (.github/PULL_REQUEST_TEMPLATE.md):
## Description
Brief description of changes.
## Type of Change
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to break)
- [ ] Documentation update
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added covering changes
- [ ] All tests passing
- [ ] CHANGELOG.md updated
## Related Issues
Closes #(issue number)
CODEOWNERS (.github/CODEOWNERS):
# Global owners
* @organization/maintainers
# Specific paths
/docs/ @organization/docs-team
/src/ @organization/core-team
/.github/ @organization/devops-team
/tests/ @organization/qa-team
Phase 4: CI/CD Workflows (60 min)
Lint Workflow (.github/workflows/lint.yml):
name: Lint
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run ESLint
run: npm run lint
- name: Run Prettier
run: npm run format:check
Test Workflow (.github/workflows/test.yml):
name: Test
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node-version: [18.x, 20.x]
steps:
- uses: actions/checkout@v4
- name: Setup Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/lcov.info
Release Workflow (.github/workflows/release.yml):
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: Create Release
uses: actions/create-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: ${{ github.ref }}
release_name: Release ${{ github.ref }}
draft: false
prerelease: false
GitHub Pages Deploy (.github/workflows/pages.yml):
name: Deploy to GitHub Pages
on:
push:
branches: [ main ]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Build site
run: |
# Build commands here
npm run build:docs
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./docs
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Phase 5: Documentation Site (60 min)
Option 1: Docsify (Recommended for simplicity)
- Create
docs/directory structure:
docs/
├── index.html (Docsify config)
├── README.md (Home page)
├── _sidebar.md (Navigation)
├── guide/
│ ├── getting-started.md
│ └── advanced.md
└── reference/
├── api.md
└── cli.md
docs/index.html:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Project Documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'Project Name',
repo: 'https://github.com/owner/repo',
loadSidebar: true,
subMaxLevel: 2,
search: 'auto'
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>
docs/_sidebar.md:
- [Home](/)
- [Getting Started](guide/getting-started.md)
- [API Reference](reference/api.md)
Option 2: Jekyll (GitHub Pages default)
- Create
_config.yml:
title: Project Documentation
description: Project description
theme: jekyll-theme-cayman
markdown: kramdown
- Enable GitHub Pages in repository settings
- Select source:
mainbranch,/docsfolder
Option 3: MkDocs (Python-based, feature-rich)
- Install:
pip install mkdocs mkdocs-material - Initialize:
mkdocs new . - Configure
mkdocs.yml - Build:
mkdocs build - Deploy:
mkdocs gh-deploy
Phase 6: Badges & Metadata (15 min)
Essential Badges:
[](https://github.com/OWNER/REPO/releases)
[](LICENSE)
[](https://github.com/OWNER/REPO/actions)
[](https://codecov.io/gh/OWNER/REPO)
[](https://www.npmjs.com/package/@org/package)
Repository Topics:
- Maximum 20 topics
- Use lowercase, hyphens for spaces
- Include: language, framework, use-case, industry
- Example:
typescript,api,mental-models,cognitive-framework
About Section:
- Concise description (160 chars max)
- Include primary use case
- Add website URL if applicable
- Select appropriate topics
Quality Checklist
Repository Health ✅
- README with badges, quick start, and documentation links
- LICENSE file present and appropriate
- CODE_OF_CONDUCT.md following Contributor Covenant
- CONTRIBUTING.md with clear guidelines
- SECURITY.md with vulnerability reporting process
- CHANGELOG.md following Keep a Changelog format
- .gitignore appropriate for project type
Automation ✅
- CI workflow testing on push/PR
- Linting workflow enforcing code style
- Security scanning (Dependabot, CodeQL)
- Automated releases on version tags
- Documentation deployment on main branch push
Templates ✅
- Bug report template
- Feature request template
- Pull request template with checklist
- CODEOWNERS file for automatic review assignment
Documentation ✅
- GitHub Pages enabled and deploying
- Navigation structure clear and hierarchical
- Search functionality working
- Mobile-responsive design
- All links functional
Metadata ✅
- Repository description set
- Topics configured (10-20 relevant tags)
- Website URL added (if applicable)
- Social preview image (1280x640px)
Best Practices
Branch Protection Rules
Settings → Branches → Add rule
Branch name pattern: main
Protection settings:
✅ Require pull request before merging
✅ Require approvals (1-2)
✅ Dismiss stale reviews
✅ Require status checks to pass
✅ Require branches to be up to date
✅ Require conversation resolution before merging
✅ Require signed commits (optional, high security)
✅ Include administrators (recommended)
Semantic Versioning
MAJOR.MINOR.PATCH (e.g., 2.1.3)
MAJOR: Breaking changes
MINOR: New features (backwards compatible)
PATCH: Bug fixes (backwards compatible)
Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
Build metadata: 1.0.0+20130313144700
Commit Message Convention
<type>(<scope>): <subject>
<body>
<footer>
Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Formatting, no code change
- refactor: Code change (neither fix nor feature)
- perf: Performance improvement
- test: Adding or updating tests
- chore: Maintenance (dependencies, config)
- ci: CI/CD changes
Examples:
feat(api): add mental model search endpoint
fix(parser): handle empty input gracefully
docs(readme): update installation instructions
Release Process
# 1. Update version
npm version [patch|minor|major]
# 2. Update CHANGELOG.md
# Add new version section with changes
# 3. Commit changes
git add .
git commit -m "chore: release v1.2.0"
# 4. Create and push tag
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
# 5. GitHub Actions automatically creates release
# Or manually via gh CLI:
gh release create v1.2.0 --title "v1.2.0" --notes-file RELEASE_NOTES.md
Common Pitfalls
Pitfall 1: Incomplete .gitignore
Problem: Sensitive files or build artifacts committed
Solution: Use gitignore.io templates, review before first commit
Pitfall 2: No Branch Protection
Problem: Direct pushes to main, untested code in production
Solution: Enable branch protection immediately after repo creation
Pitfall 3: Unclear Contributing Guidelines
Problem: Poor quality PRs, inconsistent code style
Solution: Detailed CONTRIBUTING.md with examples and linting automation
Pitfall 4: Missing CI/CD
Problem: Broken code merged, manual deployment friction
Solution: Set up basic CI before accepting first PR
Pitfall 5: Stale Documentation
Problem: Docs out of sync with code
Solution: Automate docs deployment, make docs updates part of PR checklist
Resources
- GitHub Docs: https://docs.github.com
- Keep a Changelog: https://keepachangelog.com
- Semantic Versioning: https://semver.org
- Contributor Covenant: https://www.contributor-covenant.org
- Citation File Format: https://citation-file-format.github.io
- GitHub Actions Marketplace: https://github.com/marketplace?type=actions
Success Criteria
Production-ready repository includes:
- ✅ All community health files present and complete
- ✅ Automated testing and linting via GitHub Actions
- ✅ Branch protection preventing untested code in main
- ✅ Clear contribution guidelines and templates
- ✅ GitHub Pages documentation site live
- ✅ Proper versioning and release automation
- ✅ Security policy and vulnerability reporting process
- ✅ Repository discoverable via topics and description
Repository fails if:
- ❌ Missing LICENSE or unclear licensing
- ❌ No CI/CD, manual testing only
- ❌ Direct commits to main possible
- ❌ No documentation or stale docs
- ❌ No contribution guidelines
- ❌ Security vulnerabilities in dependencies