|
| 1 | +# GitHub Actions CI/CD |
| 2 | + |
| 3 | +This directory contains GitHub Actions workflows for the sqlite-mcp-server project. |
| 4 | + |
| 5 | +## Workflows |
| 6 | + |
| 7 | +### `ci.yml` - Continuous Integration |
| 8 | + |
| 9 | +This workflow runs on: |
| 10 | +- Every push to `main` and `develop` branches |
| 11 | +- Every pull request targeting `main` and `develop` branches |
| 12 | +- Pull request events (opened, synchronize, reopened) |
| 13 | + |
| 14 | +#### Jobs |
| 15 | + |
| 16 | +1. **Test** - Runs tests across multiple Go versions |
| 17 | + - Go versions: 1.21, 1.22, 1.23 |
| 18 | + - Runs unit tests with race detection |
| 19 | + - Generates coverage reports |
| 20 | + - Uploads coverage to Codecov (only for Go 1.23) |
| 21 | + |
| 22 | +2. **Lint** - Code quality checks |
| 23 | + - Runs golangci-lint with comprehensive linting rules |
| 24 | + - Checks code formatting, style, and potential issues |
| 25 | + - Uses custom configuration from `.golangci.yml` |
| 26 | + |
| 27 | +3. **Integration Test** - End-to-end testing |
| 28 | + - Builds the server binary |
| 29 | + - Sets up test databases |
| 30 | + - Runs quick integration tests |
| 31 | + - Depends on test and lint jobs passing |
| 32 | + |
| 33 | +4. **Security** - Security scanning |
| 34 | + - Runs Gosec security scanner |
| 35 | + - Uploads results to GitHub Security tab |
| 36 | + - Scans for common security vulnerabilities |
| 37 | + |
| 38 | +5. **Status Check** - PR status summary |
| 39 | + - Summarizes all job results for PR requirements |
| 40 | + - Posts status comments on pull requests |
| 41 | + - Updates existing status comments instead of creating duplicates |
| 42 | + - Required for PR merges |
| 43 | + |
| 44 | +### `release.yml` - Automatic Tagging and Releases |
| 45 | + |
| 46 | +This workflow automatically creates tags and releases when code is merged to the `main` branch. |
| 47 | + |
| 48 | +#### Triggers |
| 49 | +- **Automatic**: Every push to `main` branch (after successful PR merge) |
| 50 | +- **Manual**: Workflow dispatch with version type selection |
| 51 | + |
| 52 | +#### Jobs |
| 53 | + |
| 54 | +1. **Check Changes** - Analyzes commits for release-worthy changes |
| 55 | + - Examines commit messages since last tag |
| 56 | + - Determines appropriate version bump (major/minor/patch) |
| 57 | + - Skips release if no significant changes |
| 58 | + |
| 59 | +2. **Create Tag** - Generates new version tag and GitHub release |
| 60 | + - Calculates semantic version based on commit analysis |
| 61 | + - Supports manual version override via workflow dispatch |
| 62 | + - Runs final tests before tagging |
| 63 | + - Generates automated changelog |
| 64 | + - Creates annotated Git tag |
| 65 | + |
| 66 | +3. **Build Release Assets** - Cross-platform binary compilation |
| 67 | + - Linux AMD64/ARM64 |
| 68 | + - macOS AMD64/ARM64 (Intel/Apple Silicon) |
| 69 | + - Windows AMD64 |
| 70 | + - Generates SHA256 checksums |
| 71 | + |
| 72 | +4. **Create GitHub Release** - Publishes release with assets |
| 73 | + - Uploads all platform binaries |
| 74 | + - Includes automated changelog |
| 75 | + - Links to full commit comparison |
| 76 | + |
| 77 | +5. **Notify** - Reports release status |
| 78 | + - Success/failure notifications |
| 79 | + - Links to new release |
| 80 | + |
| 81 | +#### Version Bump Logic |
| 82 | +- **Major** (`1.x.x`): Commits with `BREAKING`, `major`, `feat!`, `fix!` |
| 83 | +- **Minor** (`x.1.x`): Commits with `feat`, `feature` |
| 84 | +- **Patch** (`x.x.1`): All other changes (fixes, docs, etc.) |
| 85 | + |
| 86 | +## Manual Release |
| 87 | + |
| 88 | +You can manually trigger a release from the GitHub Actions tab: |
| 89 | + |
| 90 | +1. Go to **Actions** → **Release and Tagging** |
| 91 | +2. Click **Run workflow** |
| 92 | +3. Choose: |
| 93 | + - **Version bump type**: `patch`, `minor`, or `major` |
| 94 | + - **Custom version**: Override with specific version (e.g., `v2.1.0`) |
| 95 | +4. Click **Run workflow** |
| 96 | + |
| 97 | +This is useful for: |
| 98 | +- Creating releases outside of the normal merge cycle |
| 99 | +- Fixing version numbering issues |
| 100 | +- Creating custom version numbers |
| 101 | + |
| 102 | +## Local Development |
| 103 | + |
| 104 | +You can run the same checks locally using the Makefile: |
| 105 | + |
| 106 | +```bash |
| 107 | +# Install golangci-lint and run all CI checks |
| 108 | +make ci-local |
| 109 | + |
| 110 | +# Run just the linter |
| 111 | +make lint |
| 112 | + |
| 113 | +# Run linter with auto-fix |
| 114 | +make lint-fix |
| 115 | + |
| 116 | +# Run tests with race detection |
| 117 | +make test-race |
| 118 | + |
| 119 | +# Generate coverage report |
| 120 | +make coverage |
| 121 | +``` |
| 122 | + |
| 123 | +## Configuration Files |
| 124 | + |
| 125 | +- `.golangci.yml` - golangci-lint configuration |
| 126 | + - Enables comprehensive set of linters |
| 127 | + - Customized rules for the project |
| 128 | + - Excludes certain checks for test files |
| 129 | + |
| 130 | +## Pull Request Features |
| 131 | + |
| 132 | +The CI workflow includes several PR-specific enhancements: |
| 133 | + |
| 134 | +### Automated Comments |
| 135 | +- **Test Results**: Comments with build and test status |
| 136 | +- **Status Summary**: Comprehensive status check with all job results |
| 137 | +- **Smart Updates**: Updates existing comments instead of creating duplicates |
| 138 | + |
| 139 | +### Status Checks |
| 140 | +- All jobs must pass for PR merge approval |
| 141 | +- Clear visual indicators for each job status |
| 142 | +- Links to detailed action logs |
| 143 | + |
| 144 | +### Security Integration |
| 145 | +- SARIF upload to GitHub Security tab |
| 146 | +- Security findings visible in PR conversations |
| 147 | +- Automated security scanning on every PR |
| 148 | + |
| 149 | +## Coverage Reports |
| 150 | + |
| 151 | +- Coverage reports are generated for each test run |
| 152 | +- Codecov integration provides detailed coverage tracking |
| 153 | +- HTML coverage reports are generated locally with `make coverage-html` |
| 154 | +- Coverage changes are tracked and reported on PRs |
| 155 | + |
| 156 | +## Badge Status |
| 157 | + |
| 158 | +Add these badges to your README.md: |
| 159 | + |
| 160 | +```markdown |
| 161 | +[](https://github.com/nipunap/sqlite-mcp-server/actions/workflows/ci.yml) |
| 162 | +[](https://codecov.io/gh/nipunap/sqlite-mcp-server) |
| 163 | +``` |
0 commit comments