Skip to content

GITHUB_SETUP_SUMMARY.md

Latest commit

 

History

History
328 lines (252 loc) · 8.12 KB

GITHUB_SETUP_SUMMARY.md

File metadata and controls

328 lines (252 loc) · 8.12 KB
Raw

GitHub Workflows Setup Summary

📅 Setup Date: March 2, 2026
📦 Project: ClyCites API
🔗 Repository: Clycites-api-upgrade

✅ What's Been Created

1. GitHub Actions Workflows (.github/workflows/)

Workflow File Purpose Triggers
CI Pipeline ci.yml Test, lint, build Push to main/develop, PRs
Build Artifacts build-and-push.yml Build & release artifacts Push to main, git tags
Release release.yml Automated GitHub releases Git tags (v*..)
Code Quality code-quality.yml SonarCloud, security checks Push/PR to main/develop
Deployment deploy.yml Deploy to staging/production Manual dispatch, main push
Scheduled Tests schedule-tests.yml Extended test suite Daily 2 AM UTC, weekly
PR Checks pull-request.yml PR validation PR opened/updated
Commit Lint lint-commit.yml Validate commit messages PR submitted

2. Configuration Files

  • commitlint.config.js - Commit message validation rules (Conventional Commits)
  • .github/CODEOWNERS - Code ownership by path/module
  • .github/README.md - GitHub workflows directory overview

3. Setup Guides

  • GITHUB_ORGANIZATION_SETUP.md - Complete step-by-step GitHub organization setup
  • GITHUB_WORKFLOWS.md - Detailed workflow documentation
  • GITHUB_QUICK_REFERENCE.md - Quick reference for developers

4. Setup Scripts

  • github-setup.sh - Automated setup for macOS/Linux
  • github-setup.bat - Automated setup for Windows (batch)
  • github-setup.ps1 - Automated setup for Windows (PowerShell)

🚀 Quick Start

For Organization Admin

  1. Create GitHub Organization:

    https://github.com/organizations/new

  2. Run Setup Script:

    # macOS/Linux
chmod +x github-setup.sh
./github-setup.sh

# Windows (PowerShell)
./github-setup.ps1

# Windows (Batch)
github-setup.bat

  3. Follow Guide:

    • Read GITHUB_ORGANIZATION_SETUP.md
    • Configure secrets
    • Set branch protection rules

For Developers

  1. Read Quick Reference:

    GITHUB_QUICK_REFERENCE.md

  2. Follow Branch Naming:

    feature/{name}
fix/{name}
docs/{name}

  3. Follow Commit Format:

    type(scope): description

📋 Organization Setup Checklist

Phase 1: Organization Creation

Phase 2: Configuration

  • Add organization secrets:
    • SONAR_TOKEN
    • SLACK_WEBHOOK
    • AWS_ROLE_TO_ASSUME (optional)
    • CODECOV_TOKEN (optional)
  • Add repository variables:
    • AWS_REGION
    • REGISTRY
    • NODE_VERSION
  • Create repository environments: staging, production

Phase 3: Branch Protection

  • Configure master branch protection:
    • ✓ Require 2+ PR approvals (production safety)
    • ✓ Require status checks: lint-and-test, code-quality
    • ✓ Require signed commits
    • ✓ Require up-to-date branches
  • Configure staging branch protection:
    • ✓ Require 1+ PR approvals
    • ✓ Require status checks (same as master)

Phase 4: Security

  • Enable Secret Scanning
  • Enable Push Protection
  • Enable Dependabot Alerts
  • Enable Code Scanning (if using Advanced Security)

Phase 5: Verification

  • Create test PR
  • Verify all workflows run and pass
  • Get approvals and merge
  • Require branches to be up to date before merging
  • Verify push to master triggers build and deployment workflows
  • Verify push to staging triggers CI workflows
  • Verify deployments to appropriate environments
  • Create test tag (v0.1.0)
  • Verify release created automatically

🔑 Required Secrets

Organization Secrets

These are shared across all repositories in the organization.

# Code Quality
SONAR_TOKEN: <from SonarCloud>
CODECOV_TOKEN: <from Codecov> (optional)

# Deployments
AWS_ROLE_TO_ASSUME: arn:aws:iam::ACCOUNT:role/github-actions

# Monitoring
SLACK_WEBHOOK: https://hooks.slack.com/services/...

Repository Variables

AWS_REGION: us-east-1
REGISTRY: ghcr.io
NODE_VERSION: "22"
PNPM_VERSION: "8"

Environment Secrets

Configure in Repository → Environments → staging/production

# Staging
DEPLOYMENT_ROLE_ARN: arn:aws:iam::STAGING:role/...
DATABASE_URL: postgresql://...

# Production
DEPLOYMENT_ROLE_ARN: arn:aws:iam::PROD:role/...
DATABASE_URL: postgresql://...

📚 Documentation Files

For Admins

  • GITHUB_ORGANIZATION_SETUP.md - Complete setup guide with detailed steps
  • GITHUB_WORKFLOWS.md - In-depth workflow documentation

For Developers

  • GITHUB_QUICK_REFERENCE.md - Branch naming, commits, PR workflow
  • .github/README.md - Quick overview of workflows directory

For AutomationOwner

  • .github/CODEOWNERS - Code ownership rules
  • commitlint.config.js - Commit validation rules

🔄 Workflow Triggers Reference

Continuous Integration (Every Push/PR)

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

Docker Build (Main & Tags)

on:
  push:
    branches: [ main ]
    tags:
      - 'v*.*.*'

Release (Tags Only)

on:
  push:
    tags:
      - 'v*.*.*'

Scheduled Tests

on:
  schedule:
    - cron: '0 2 * * *'     # Daily 2 AM UTC
    - cron: '0 8 * * 1'     # Weekly Monday 8 AM UTC

📊 Status Check Requirements

For main branch, require these status checks to pass before merging:

  1. lint-and-test (18.x) - Node.js 18 tests
  2. lint-and-test (20.x) - Node.js 20 tests
  3. code-quality / sonarcloud - Code quality analysis
  4. code-quality / type-check - TypeScript validation

🎯 Next Steps

For Developers (Right Now)

  1. Read GITHUB_QUICK_REFERENCE.md
  2. Review branch naming conventions
  3. Review commit message format
  4. Setup git hooks (optional): 
    npm install husky @commitlint/cli @commitlint/config-conventional --save-dev
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

For Organization Admin

  1. Create GitHub organization
  2. Run setup script to get instructions
  3. Configure all secrets and variables
  4. Set branch protection rules
  5. Test with a PR
  6. Document access instructions for team

For Team Leads

  1. Create teams in organization
  2. Assign members to teams
  3. Review and update CODEOWNERS file
  4. Share GITHUB_QUICK_REFERENCE.md with team
  5. Schedule onboarding session

🔗 Important Links

Documentation

Local Files

  • .github/workflows/ - All workflow definitions
  • GITHUB_ORGANIZATION_SETUP.md - Setup guide
  • GITHUB_WORKFLOWS.md - Workflow details
  • GITHUB_QUICK_REFERENCE.md - Developer reference
  • commitlint.config.js - Commit rules
  • .github/CODEOWNERS - Code ownership

💡 Pro Tips

  1. Test Workflows Locally: Use act to run GitHub Actions locally

    npm install -g act
act push  # Simulate push event

  2. Quick Merges: Use "Squash and merge" to keep history clean

  3. Semantic Releases: Tag with v1.2.3 format for automatic releases

  4. Breaking Changes: Use commit message:

    feat!: breaking change description

  5. Dependency Updates: Enable Dependabot for automatic updates

📞 Support

For questions or issues:

  1. Check relevant documentation file
  2. Review workflow logs in Actions tab
  3. Check GitHub Actions documentation
  4. Contact DevOps team (@devops on GitHub)

Created: March 2, 2026
For: ClyCites API
Organization: clycites-org
Repository: clycites-api-upgrade