Secrets and Workflow Setup Guide

This guide walks you through setting up GitHub secrets and configuring the CI/CD workflows for the Cosmic MCP project.

🔐 GitHub Secrets Setup

Required Secrets

Your repository needs the following secrets for automated workflows:

1. NPM Publishing Secrets

Secret Name	Description	How to Get
NPM_TOKEN	NPM authentication token for publishing	Create NPM Access Token

2. Code Quality Secrets (Optional)

Secret Name	Description	How to Get
CODECOV_TOKEN	Token for code coverage reporting	Get Codecov Token

Creating NPM Access Token

1. Login to NPM

   npm login

2. Create Access Token

   • Go to npmjs.com and login
   • Click on your profile → "Access Tokens"
   • Click "Generate New Token"
   • Choose "Automation" type for CI/CD
   • Copy the generated token

3. Add to GitHub Secrets

   • Go to your GitHub repository
   • Navigate to Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: NPM_TOKEN
   • Value: Paste your NPM token
   • Click "Add secret"

Setting Up Codecov

1. Sign up for Codecov

   • Go to codecov.io
   • Sign in with your GitHub account
   • Add your repository

2. Get Repository Token

   • In Codecov dashboard, go to your repository
   • Copy the repository token

3. Add to GitHub Secrets

   • Name: CODECOV_TOKEN
   • Value: Paste your Codecov token

🔧 Workflow Configuration

Current Workflows

The project includes three main workflows:

1. CI Workflow (.github/workflows/ci.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main or develop branches

What it does:

• Runs tests across Node.js 18.x and 20.x
• Performs linting and type checking
• Generates code coverage reports
• Uploads coverage to Codecov

Configuration:

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

2. Release Workflow (.github/workflows/release.yml)

Triggers:

• Push to main branch (excluding commits with 'skip ci')

What it does:

• Automatically determines version bump based on commit messages
• Updates CHANGELOG.md
• Creates GitHub release
• Publishes to NPM
• Commits version changes back to repository

Configuration:

name: Release
on:
  push:
    branches:
      - main

3. Code Quality Workflow (.github/workflows/code-quality.yml)

Triggers:

• Push to main or develop branches
• Pull requests to main or develop branches
• Weekly schedule (Mondays at 9 AM UTC)

What it does:

• Security audits
• Dependency vulnerability scanning
• Code analysis
• Performance monitoring

📝 Commit Message Convention

The release workflow uses Conventional Commits to automatically determine version bumps:

Commit Types

Type	Description	Version Bump
feat:	New feature	Minor (1.1.0)
fix:	Bug fix	Patch (1.0.1)
docs:	Documentation changes	Patch (1.0.1)
style:	Code style changes	Patch (1.0.1)
refactor:	Code refactoring	Patch (1.0.1)
test:	Adding tests	Patch (1.0.1)
chore:	Maintenance tasks	Patch (1.0.1)

Breaking Changes

Add BREAKING CHANGE: in the commit body or ! after type for major version bump:

feat!: redesign API interface

BREAKING CHANGE: The API now uses different parameter names

Examples

# Minor version bump (new feature)
git commit -m "feat: add new search functionality to MCP tools"

# Patch version bump (bug fix)
git commit -m "fix: resolve connection timeout in Cosmic client"

# Major version bump (breaking change)
git commit -m "feat!: change MCP tool parameter structure"

# No version bump (documentation)
git commit -m "docs: update API examples in README"

🚀 Release Process

Automatic Releases

1. Make Changes

   • Create feature branch: git checkout -b feat/new-feature
   • Make your changes
   • Commit with conventional commit messages

2. Create Pull Request

   • Push branch: git push origin feat/new-feature
   • Create PR to main branch
   • CI workflow runs automatically

3. Merge to Main

   • Once PR is approved and merged
   • Release workflow triggers automatically
   • Version is bumped based on commit messages
   • Package is published to NPM
   • GitHub release is created

Manual Release (if needed)

If you need to trigger a release manually:

1. Update Version

   npm version patch  # or minor, major

2. Push Changes

   git push origin main --tags

3. Publish to NPM

   npm publish

🔍 Monitoring Workflows

Viewing Workflow Status

1. GitHub Actions Tab

   • Go to your repository on GitHub
   • Click "Actions" tab
   • View running/completed workflows

2. Status Badges

   • Check README.md for status badges
   • Green = passing, Red = failing

Common Issues and Solutions

NPM Publish Fails

Error: 403 ForbiddenSolution:

• Check NPM_TOKEN is valid
• Ensure you have publish permissions
• Verify package name is available

Tests Fail

Error: Test failures in CI Solution:

• Run tests locally: bun test
• Fix failing tests
• Commit and push fixes

Build Fails

Error: Build errors in CI Solution:

• Run build locally: bun run build
• Fix TypeScript errors
• Commit and push fixes

📊 Workflow Optimization

Performance Tips

1. Cache Dependencies

   • Workflows already include dependency caching
   • Reduces build times significantly

2. Parallel Jobs

   • Tests run on multiple Node.js versions in parallel
   • Faster feedback on compatibility

3. Conditional Execution

   • Release only runs on main branch
   • Code quality runs on schedule to avoid overload

Security Best Practices

1. Secrets Management

   • Never commit secrets to repository
   • Use GitHub Secrets for sensitive data
   • Rotate tokens regularly

2. Dependency Security

   • Dependabot automatically updates dependencies
   • Security audit runs weekly
   • Vulnerability scanning on PRs

3. Access Control

   • Limit who can modify workflows
   • Require PR reviews for main branch
   • Use branch protection rules

🛠️ Customizing Workflows

Adding New Workflows

1. Create Workflow File

   touch .github/workflows/my-workflow.yml

2. Basic Structure

   name: My Workflow
   on:
     push:
       branches: [main]
   
   jobs:
     my-job:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Setup Bun
           uses: oven-sh/setup-bun@v1
         - name: Install dependencies
           run: bun install
         - name: Run my task
           run: bun run my-task

Modifying Existing Workflows

1. Edit Workflow Files

   • Located in .github/workflows/
   • Use YAML syntax
   • Test changes in feature branch first

2. Common Modifications

   • Add new test commands
   • Change trigger conditions
   • Add deployment steps
   • Modify notification settings

📋 Checklist for New Repository

• [ ] Set up NPM_TOKEN secret
• [ ] Configure Codecov (optional)
• [ ] Enable branch protection on main
• [ ] Set up Dependabot alerts
• [ ] Test CI workflow with dummy commit
• [ ] Verify release workflow works
• [ ] Update README badges
• [ ] Configure notification preferences

🆘 Getting Help

Resources

• GitHub Actions Documentation
• NPM Publishing Guide
• Conventional Commits
• Semantic Versioning

Common Commands

# Check workflow status
gh workflow list

# View workflow runs
gh run list

# Download workflow logs
gh run download <run-id>

# Trigger workflow manually
gh workflow run ci.yml

---

🎯 Next Steps

1. Set up secrets following the guide above
2. Test the workflows with a sample commit
3. Configure branch protection rules
4. Set up monitoring and notifications
5. Customize workflows for your specific needs

The automated workflows will handle versioning, testing, and publishing, allowing you to focus on developing features and improving the Cosmic MCP server!