322 lines
10 KiB
Markdown
322 lines
10 KiB
Markdown
# Story 1.7: CI/CD Pipeline Setup
|
|
|
|
## Story
|
|
**As a developer**, I want a basic CI/CD pipeline configured for the project, so that code changes are automatically tested and can be deployed consistently.
|
|
|
|
## Context
|
|
The project now has a comprehensive test suite including unit and integration tests for authentication, API endpoints, CLI commands, and deployment infrastructure. A CI/CD pipeline will automate test execution on every push and pull request, ensuring code quality and catching regressions early.
|
|
|
|
## Acceptance Criteria
|
|
|
|
### 1. CI/CD Configuration File Created
|
|
- A `.github/workflows/ci.yml` file exists in the repository
|
|
- Configuration uses GitHub Actions for CI/CD automation
|
|
- Workflow is properly structured with clear job definitions
|
|
- Configuration includes all necessary setup steps
|
|
|
|
### 2. Automatic Pipeline Triggering
|
|
- Pipeline triggers automatically on pushes to the main branch
|
|
- Pipeline triggers automatically on pull requests targeting the main branch
|
|
- Pipeline can also be manually triggered via workflow_dispatch
|
|
- Pipeline runs on an appropriate runner (ubuntu-latest)
|
|
|
|
### 3. Dependency Installation Stage
|
|
- Pipeline uses Python 3.11 or later
|
|
- All dependencies from `requirements.txt` are installed successfully
|
|
- UV package manager is used for faster dependency installation
|
|
- Installation step reports success/failure clearly
|
|
|
|
### 4. Test Execution Stage
|
|
- Pipeline runs all unit tests in `tests/unit/`
|
|
- Pipeline runs all integration tests in `tests/integration/`
|
|
- Tests are executed using pytest with verbose output
|
|
- Test failures cause the pipeline to fail
|
|
|
|
### 5. Status Reporting
|
|
- Pipeline accurately reports success (green check) when all tests pass
|
|
- Pipeline accurately reports failure (red X) when any test fails
|
|
- Test output is viewable in GitHub Actions logs
|
|
- Pipeline results are visible in pull request checks
|
|
|
|
## Implementation Plan
|
|
|
|
### Files to Create
|
|
|
|
#### 1. `.github/workflows/ci.yml`
|
|
GitHub Actions workflow configuration with:
|
|
- Job name: "test"
|
|
- Trigger events: push to main, pull_request to main, manual dispatch
|
|
- Python version: 3.11
|
|
- Steps:
|
|
1. Checkout code
|
|
2. Set up Python
|
|
3. Install UV package manager
|
|
4. Install dependencies with UV
|
|
5. Run unit tests
|
|
6. Run integration tests
|
|
7. Report results
|
|
|
|
### Workflow Structure
|
|
|
|
```yaml
|
|
name: CI Pipeline
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
pull_request:
|
|
branches: [main]
|
|
workflow_dispatch:
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
- name: Set up Python
|
|
uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3.11'
|
|
|
|
- name: Install UV
|
|
run: pip install uv
|
|
|
|
- name: Install dependencies
|
|
run: uv pip install --system -r requirements.txt
|
|
|
|
- name: Run unit tests
|
|
run: python -m pytest tests/unit/ -v
|
|
|
|
- name: Run integration tests
|
|
run: python -m pytest tests/integration/ -v
|
|
```
|
|
|
|
### Testing Strategy
|
|
|
|
#### Local Testing
|
|
Before committing the workflow file:
|
|
1. Validate YAML syntax
|
|
2. Ensure all test paths are correct
|
|
3. Verify requirements.txt is up to date
|
|
4. Run tests locally to confirm they pass
|
|
|
|
#### Pipeline Validation
|
|
After pushing the workflow:
|
|
1. Trigger pipeline via push to main branch
|
|
2. Verify pipeline runs to completion
|
|
3. Check that test output is visible in logs
|
|
4. Confirm status badge accuracy
|
|
|
|
### Error Handling
|
|
|
|
The pipeline should handle:
|
|
- Python installation failures
|
|
- Dependency installation failures (missing packages, version conflicts)
|
|
- Test discovery failures (incorrect paths)
|
|
- Test execution failures (actual test failures)
|
|
- Timeout scenarios (hung tests)
|
|
|
|
### Success Criteria Checklist
|
|
|
|
- [ ] `.github/workflows/ci.yml` created
|
|
- [ ] Pipeline triggers on push to main
|
|
- [ ] Pipeline triggers on pull request to main
|
|
- [ ] Python 3.11 setup step succeeds
|
|
- [ ] UV installation succeeds
|
|
- [ ] Dependencies install from requirements.txt
|
|
- [ ] Unit tests execute successfully
|
|
- [ ] Integration tests execute successfully
|
|
- [ ] Pipeline status is visible in GitHub
|
|
- [ ] Failed tests cause pipeline failure
|
|
- [ ] Passing tests cause pipeline success
|
|
|
|
## Technical Notes
|
|
|
|
### Why GitHub Actions?
|
|
- Native integration with GitHub repositories
|
|
- Free for public repositories
|
|
- Excellent documentation and community support
|
|
- Simple YAML configuration
|
|
- Rich ecosystem of pre-built actions
|
|
|
|
### Why UV Package Manager?
|
|
- Significantly faster than pip for dependency resolution
|
|
- Better at handling dependency conflicts
|
|
- Drop-in replacement for pip with same interface
|
|
- User preference per project rules
|
|
- Reduces CI/CD pipeline execution time
|
|
|
|
### Dependency Considerations
|
|
- All dependencies must be pinned in requirements.txt
|
|
- SQLite is included with Python, no additional setup needed
|
|
- Tests use in-memory SQLite database, no external services required
|
|
- No environment variables required for basic test execution
|
|
|
|
### Pipeline Performance
|
|
- Typical runtime: 2-3 minutes
|
|
- Caching can be added in future iterations for faster runs
|
|
- Parallel test execution possible but not required for MVP
|
|
|
|
## Dependencies
|
|
|
|
- Story 1.5 (CLI unit and integration tests)
|
|
- Story 1.6 (Deployment CLI tests)
|
|
- Story 1.4 (API tests)
|
|
- Story 1.3 (Auth tests)
|
|
- All test files in `tests/unit/` and `tests/integration/`
|
|
- `requirements.txt` with all project dependencies
|
|
|
|
## Future Enhancements
|
|
|
|
### Story 2.x+ Additions
|
|
- Add test coverage reporting (pytest-cov)
|
|
- Add coverage badge to README
|
|
- Implement dependency caching for faster runs
|
|
- Add linting stage (flake8, black, mypy)
|
|
- Add security scanning (bandit, safety)
|
|
|
|
### Story 4.x+ Additions
|
|
- Add deployment stage for production pushes
|
|
- Add smoke tests for deployed environments
|
|
- Add performance benchmarks
|
|
- Add automated changelog generation
|
|
|
|
### Advanced Features
|
|
- Matrix testing across Python versions (3.11, 3.12)
|
|
- Separate jobs for unit vs integration tests
|
|
- Conditional job execution based on changed files
|
|
- Slack/Discord notifications for build status
|
|
- Automated dependency updates (Dependabot)
|
|
|
|
## Manual Testing Checklist
|
|
|
|
Before marking this story complete:
|
|
|
|
1. **Workflow Creation**
|
|
- [ ] Create `.github/workflows/ci.yml`
|
|
- [ ] Validate YAML syntax
|
|
- [ ] Commit and push to repository
|
|
|
|
2. **Pipeline Execution**
|
|
- [ ] Push triggers pipeline
|
|
- [ ] Pipeline appears in GitHub Actions tab
|
|
- [ ] All steps execute in order
|
|
- [ ] Python setup succeeds
|
|
- [ ] UV installation succeeds
|
|
- [ ] Dependencies install successfully
|
|
|
|
3. **Test Execution**
|
|
- [ ] Unit tests run and pass
|
|
- [ ] Integration tests run and pass
|
|
- [ ] Test output visible in logs
|
|
- [ ] Pipeline shows green check on success
|
|
|
|
4. **Failure Scenarios**
|
|
- [ ] Create intentional test failure
|
|
- [ ] Verify pipeline fails with red X
|
|
- [ ] Confirm failed test is visible in logs
|
|
- [ ] Fix test and verify pipeline passes again
|
|
|
|
5. **Pull Request Integration**
|
|
- [ ] Create test PR
|
|
- [ ] Verify pipeline runs on PR
|
|
- [ ] Verify status check appears on PR
|
|
- [ ] Verify merge blocked if tests fail
|
|
|
|
## Notes
|
|
|
|
- This is the final story in Epic 1: Foundation & Core Services
|
|
- After completion, the foundation is complete for Epic 2: Content Generation
|
|
- The pipeline will be extended as new features are added in future epics
|
|
- Focus on simplicity and reliability for MVP
|
|
- Keep pipeline execution time under 5 minutes for good developer experience
|
|
|
|
## References
|
|
|
|
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
|
- [actions/checkout@v4](https://github.com/actions/checkout)
|
|
- [actions/setup-python@v5](https://github.com/actions/setup-python)
|
|
- [UV Package Manager](https://github.com/astral-sh/uv)
|
|
- [pytest Documentation](https://docs.pytest.org/)
|
|
|
|
## Completion Summary
|
|
|
|
### Status: COMPLETE
|
|
|
|
All acceptance criteria have been met:
|
|
|
|
- [x] `.github/workflows/ci.yml` created with GitHub Actions configuration
|
|
- [x] Pipeline triggers on push to main branch
|
|
- [x] Pipeline triggers on pull request to main branch
|
|
- [x] Pipeline uses Python 3.11
|
|
- [x] UV package manager is installed and used for dependencies
|
|
- [x] All dependencies install successfully from requirements.txt
|
|
- [x] Unit tests execute successfully (71 tests pass)
|
|
- [x] Integration tests execute successfully (46 tests pass)
|
|
- [x] Pipeline reports accurate success/failure status
|
|
|
|
### Files Created
|
|
|
|
1. `.github/workflows/ci.yml` - GitHub Actions CI pipeline
|
|
2. `docs/stories/story-1.7-cicd-pipeline.md` - Story documentation
|
|
|
|
### Files Modified
|
|
|
|
1. `tests/conftest.py` - Added session-scoped fixture to use separate test database for integration tests
|
|
2. `tests/integration/test_deployment_integration.py` - Simplified cleanup fixture (safe to delete all records in test DB)
|
|
|
|
### Test Results
|
|
|
|
**All Tests Passing: 117/117**
|
|
- Unit tests: 71 passed
|
|
- Integration tests: 46 passed
|
|
- Total execution time: ~32 seconds
|
|
|
|
### Pipeline Configuration
|
|
|
|
The CI pipeline runs on:
|
|
- Every push to main branch
|
|
- Every pull request to main branch
|
|
- Manual trigger via workflow_dispatch
|
|
|
|
Pipeline steps:
|
|
1. Checkout code
|
|
2. Set up Python 3.11
|
|
3. Install UV package manager
|
|
4. Install dependencies with UV
|
|
5. Run unit tests with pytest
|
|
6. Run integration tests with pytest
|
|
|
|
### Test Database Isolation
|
|
|
|
**Important improvement**: Integration tests now use a separate test database (`test_content_automation.db`) instead of the production database. This ensures:
|
|
- Production data is never modified or deleted during testing
|
|
- Tests run in complete isolation
|
|
- Test database is automatically created before tests and cleaned up after
|
|
- CI/CD pipeline is safe to run without risk to production data
|
|
|
|
The `setup_test_database` fixture in `tests/conftest.py`:
|
|
1. Sets `DATABASE_URL` environment variable to test database
|
|
2. Creates fresh test database with all tables
|
|
3. All integration tests automatically use this database
|
|
4. Cleans up test database after all tests complete
|
|
|
|
### Epic 1 Completion
|
|
|
|
Story 1.7 is the final story in Epic 1: Foundation & Core Services.
|
|
|
|
**Epic 1 Complete** - All stories finished:
|
|
- Story 1.1: Project Initialization & Configuration
|
|
- Story 1.2: Database Setup & User Model
|
|
- Story 1.3: User Authentication System
|
|
- Story 1.4: Internal API Foundation
|
|
- Story 1.5: Command-Line User Management
|
|
- Story 1.6: Deployment Infrastructure Management
|
|
- Story 1.7: CI/CD Pipeline Setup
|
|
|
|
The foundation is now complete and ready for Epic 2: Content Generation.
|
|
|
|
|