CI/CD and Release Process
Relevant source files
The following files were used as context for generating this wiki page:
The StackOne AI Python SDK utilizes an automated pipeline for code validation, testing, and distribution. The process ensures that every contribution meets strict quality gates before integration and that releases are consistently versioned and published to the Python Package Index (PyPI).
The system relies on a combination of local development tools (managed via uv and make), Continuous Integration (CI) workflows triggered by Git events, and automated release management via release-please.
Sources: CLAUDE.md:65-68, CLAUDE.md:144-150
Continuous Integration Workflow
The CI pipeline executes on every push to the repository. It enforces code quality through linting, type checking, and comprehensive test suites. Developers are expected to run these checks locally before pushing to prevent CI failures.
Local Development Lifecycle
Developers follow a structured workflow to maintain repository health:
- Create a feature branch from
main. - Implement changes following the defined code style (Ruff).
- Run
make formatto fix linting and formatting issues. - Run
make testto execute unit and integration tests. - Execute
make validateto ensure compatibility with consumers. - Submit a Pull Request (PR) to
main.
Sources: CLAUDE.md:65-68, CLAUDE.md:129-130
CI Pipeline Components
The following diagram illustrates the sequence of operations performed during the CI process:
The diagram shows the mandatory quality gates that code must pass during the CI cycle. Sources: CLAUDE.md:65-68, scripts/validate.sh:17-21
Validation Framework
The project includes a specialized validation script, scripts/validate.sh, which performs deterministic checks against mock environments. This prevents regressions in how the SDK interacts with downstream consumers and the StackOne API.
Validation Targets
| Target | Description | File/Dependency |
|---|---|---|
| Examples | Proves imports resolve and code type-checks against the current SDK. | examples/*.py |
| Conformance | Validates the wire contract and strict schema pass-through. | sdk-conformance repo |
| SDK Smoke | Tests basic SDK functionality against mock API. | scripts/run_smoke.sh |
| Pydantic AI | Verifies integration with Pydantic AI (1.x and 2.x). | pydantic-ai extra |
| Google ADK | Validates compatibility with Google ADK plugins. | stackone-adk-plugin |
Sources: scripts/validate.sh:110-120
Integration Mocking
For integration tests, the SDK uses a mock Model Context Protocol (MCP) server implemented in TypeScript. This server (tests/mocks/mcp-server.ts) models real API behaviors, including:
- Enforcing
x-account-idheaders. - Returning 400 errors for unscoped requests.
- Simulating tool discovery and execution over
/actions/rpc.
Sources: tests/mocks/mcp-server.ts:60-80, CLAUDE.md:95-103
Release Automation
The release process is fully automated through release-please. Manual publishing from developer machines is strictly prohibited to maintain security and version integrity.
Versioning Logic
Versions are incremented based on Conventional Commits format (type(scope): description).
| Commit Type | Version Impact | Example |
|---|---|---|
feat! | Major (Breaking Change) | feat!: remove deprecated OAS methods |
feat | Minor (New Feature) | feat(search): add semantic search |
fix | Patch (Bug Fix) | fix(deps): update httpx |
chore/docs | None | docs: update README |
Sources: CLAUDE.md:132-142, CHANGELOG.md:158-160
Automated Release Flow
When a PR is merged into main, the following automated steps occur:
release-pleaseanalyzes commits since the last release.- It generates/updates the
CHANGELOG.md. - It creates a new GitHub Release with the calculated version.
- The Release workflow triggers a build and publishes the package to PyPI using the
PYPI_API_TOKEN.
The sequence diagram demonstrates the hands-off nature of the deployment pipeline once code reaches the main branch. Sources: CLAUDE.md:144-150, pyproject.toml:22-25
Build Configuration
The SDK uses hatchling as the build backend. The build configuration in pyproject.toml ensures that only necessary files are included in the distribution packages, omitting development-only assets like TypeScript mocks and environment files.
- Wheel Content: Includes the
stackone_aipackage. - Sdist Content: Includes
stackone_ai,README.md,LICENSE,CHANGELOG.md, andpyproject.toml. - Dependencies: Core dependencies include
pydantic,httpx, andmcp. Framework adapters (LangChain, Pydantic AI) are defined as optional extras to minimize the install footprint.
Sources: pyproject.toml:22-55
Conclusion
The StackOne AI Python SDK employs a robust CI/CD architecture designed for high technical accuracy and release stability. By integrating strict local validation, automated mock-based testing, and a standardized release-please workflow, the project maintains a reliable distribution channel for developers building SaaS-integrated AI agents.