Skip to main content

Overview

BarStrad-Bot uses GitHub Actions for automated Continuous Integration and Continuous Deployment (CI/CD). This system ensures code quality, automates testing, and handles production deployments seamlessly.

Pipeline Architecture​

The CI/CD pipeline consists of three main workflows:

🔄 CI Workflow (ci.yml)​

  • Purpose: Validates code changes and ensures quality
  • Triggers: Pull requests, feature branch pushes, manual execution
  • Duration: ~2-3 minutes
  • Output: Validation results (no artifacts)

🚀 Release Workflow (release.yml)​

  • Purpose: Builds and deploys production releases
  • Triggers: Main branch pushes, manual execution
  • Duration: ~5-10 minutes
  • Output: Docker images, GitHub releases, notifications

📚 Documentation Workflow (docs.yml)​

  • Purpose: Builds and deploys documentation to GitHub Pages
  • Triggers: Manual execution, external API calls
  • Duration: ~3-5 minutes
  • Output: Static documentation site on GitHub Pages

Workflow Separation Strategy​

The pipeline uses a separation of concerns approach:

Benefits of This Approach​

  1. Fast Feedback: Developers get quick validation on feature branches
  2. Resource Efficiency: No unnecessary artifact creation during development
  3. Clear Responsibilities: CI validates, Release deploys
  4. Risk Reduction: Separate validation from deployment concerns

Build Environment​

Both workflows use a custom build agent container:

Build Agent Container​

  • Image: ghcr.io/the-running-dev/build-agent:latest
  • Capabilities: Node.js, Docker-in-Docker, GitVersion, custom build scripts
  • Benefits: Consistent build environment, pre-installed tools, isolated execution

Container Features​

  • Node.js Runtime: Latest LTS version with npm/yarn
  • Docker Support: Docker-in-Docker for container builds
  • GitVersion: Automatic semantic versioning
  • Build Scripts: Custom node-in-docker-build command
  • Security: Isolated execution environment

Versioning Strategy​

The project uses GitVersion for automatic semantic versioning:

Version Calculation Rules​

  • Major: Breaking changes (manual bump required)
  • Minor: New features on main branch
  • Patch: Bug fixes and hotfixes
  • Pre-release: Feature branch builds

GitVersion Configuration​

mode: ContinuousDeployment
next-version: v1.0.0-alpha

branches:
  main:
    increment: Minor
  feature:
    increment: Inherit
  hotfix:
    increment: Patch

Security & Permissions​

Required Secrets​

All workflows require these GitHub Secrets:

SecretPurposeWorkflows
REGISTRY_TOKENGitHub Container Registry accessCI, Release
NOTIFICATIONS_WEBHOOK_URLBuild status notificationsCI, Release
DISCORD_BOT_TOKENDiscord bot configurationCI, Release
DISCORD_WEBHOOK_URLDiscord notificationsCI, Release

Permission Model​

  • CI Workflow: packages: write (minimal permissions)
  • Release Workflow: packages: write, contents: write (deployment permissions)

Monitoring & Observability​

Build Status Monitoring​

  • GitHub Actions: Real-time workflow status
  • Status Badges: README.md status indicators
  • Webhook Notifications: External system integration

Metrics Tracked​

  • Build success/failure rates
  • Build duration trends
  • Deployment frequency
  • Error patterns and resolution

Path-based Optimization​

Both workflows use path exclusions to avoid unnecessary runs:

Excluded Paths​

  • documentation/** - Documentation changes don't require builds
  • .github/** - Workflow changes don't require validation

Benefits​

  • Resource Savings: Fewer unnecessary builds
  • Faster Feedback: Focus on code changes that matter
  • Cost Optimization: Reduced CI/CD usage costs

Integration Points​

Discord Integration​

  • Bot Runtime: Environment variables for Discord connection
  • Notifications: Webhook integration for build/deployment status
  • Error Reporting: Automated error notifications

Container Registry​

  • Storage: GitHub Container Registry (ghcr.io)
  • Tagging: Semantic version tags + latest
  • Access: Private registry with token authentication

GitHub Integration​

  • Releases: Automated release creation with notes
  • Pull Requests: Status checks and validation
  • Issues: Automatic linking and references

Deployment Flow​

Development Flow​

1. Developer creates feature branch
2. CI workflow validates changes on push
3. Developer opens pull request
4. CI workflow validates PR changes
5. Code review process
6. Merge to main branch
7. Release workflow builds and deploys
8. Notifications sent to team

Emergency Release Flow​

1. Manual trigger of Release workflow
2. Build from current main branch
3. Deploy to production
4. Notifications sent
5. Post-deployment verification

Best Practices Implemented​

Development Best Practices​

  1. Automated Validation: Every change is automatically tested
  2. Branch Protection: Main branch requires PR validation
  3. Code Quality: Consistent build environment ensures quality
  4. Fast Feedback: Quick validation for rapid development

Deployment Best Practices​

  1. Automated Deployment: No manual deployment steps
  2. Rollback Capability: Docker tags enable easy rollbacks
  3. Health Checks: Automated deployment verification
  4. Notifications: Team awareness of deployments

Security Best Practices​

  1. Secret Management: Secure storage of sensitive data
  2. Minimal Permissions: Least privilege access model
  3. Container Security: Isolated build environments
  4. Token Rotation: Regular credential updates

Required GitHub Secrets​

The CI/CD workflows require the following secrets to be configured in GitHub:

SecretPurposeWorkflows
REGISTRY_TOKENGitHub token with package write permissionsRelease
NOTIFICATIONS_WEBHOOK_URLWebhook URL for build notificationsCI, Release
DISCORD_BOT_TOKENDiscord bot authentication tokenCI, Release
DISCORD_WEBHOOK_URLDiscord webhook URL for order notificationsCI, Release

Secret Configuration​

  1. Navigate to Repository Settings → Secrets and variables → Actions
  2. Add each required secret with the appropriate values
  3. Verify permissions ensure tokens have necessary access
  4. Test workflows to confirm secrets are working correctly

Troubleshooting CI/CD Issues​

Common Build Failures​

  1. TypeScript Errors: Check source code compilation
  2. Docker Build Issues: Review Dockerfile and dependencies
  3. Permission Errors: Verify GitHub token permissions
  4. Container Access: Check build agent availability

Debugging Strategies​

  1. Workflow Logs: Review detailed GitHub Actions logs
  2. Local Testing: Reproduce builds locally with Docker
  3. Manual Triggers: Test workflows manually for debugging
  4. Environment Validation: Verify all required secrets
  5. Local Workflow Testing: Use Act to test workflows locally - see Local Testing with Act

Next Steps​

Ready to dive deeper? Check out the detailed CI Workflow, Release Workflow, or Documentation Workflow documentation.