{"id":34736258,"url":"https://github.com/wislertt/zerv-flow","last_synced_at":"2026-04-01T19:19:29.509Z","repository":{"id":329292481,"uuid":"1118958059","full_name":"wislertt/zerv-flow","owner":"wislertt","description":"Demo: zerv versioning integration with CI/CD pipelines - multi-format version generation (semver/PEP440/Docker), environment-specific deployments, and flexible branching strategy framework.","archived":false,"fork":false,"pushed_at":"2026-03-20T04:16:21.000Z","size":160,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T19:54:09.051Z","etag":null,"topics":["cicd","github-acti","gitops","semantic-versioning","versioning","zerv"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wislertt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-18T14:29:39.000Z","updated_at":"2026-03-20T04:09:21.000Z","dependencies_parsed_at":"2026-03-07T07:02:18.114Z","dependency_job_id":null,"html_url":"https://github.com/wislertt/zerv-flow","commit_stats":null,"previous_names":["wislertt/zerv-flow"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/wislertt/zerv-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wislertt","download_url":"https://codeload.github.com/wislertt/zerv-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wislertt%2Fzerv-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cicd","github-acti","gitops","semantic-versioning","versioning","zerv"],"created_at":"2025-12-25T03:40:51.411Z","updated_at":"2026-04-01T19:19:29.497Z","avatar_url":"https://github.com/wislertt.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![tests](https://img.shields.io/github/actions/workflow/status/wislertt/zerv-flow/cd.yml?branch=main\u0026label=tests\u0026logo=github)](https://github.com/wislertt/zerv-flow/actions/workflows/cd.yml)\n[![release](https://img.shields.io/github/actions/workflow/status/wislertt/zerv-flow/cd.yml?branch=main\u0026label=release\u0026logo=github)](https://github.com/wislertt/zerv-flow/actions/workflows/cd.yml)\n[![quality gate status](https://sonarcloud.io/api/project_badges/measure?project=wislertt_zerv-flow\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=wislertt_zerv-flow)\n[![security rating](https://sonarcloud.io/api/project_badges/measure?project=wislertt_zerv-flow\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=wislertt_zerv-flow)\n[![vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=wislertt_zerv-flow\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=wislertt_zerv-flow)\n[![codecov](https://img.shields.io/codecov/c/github/wislertt/zerv-flow?label=codecov\u0026logo=codecov)](https://codecov.io/gh/wislertt/zerv-flow)\n\n# zerv flow\n\nA demonstration of [**zerv**](https://github.com/wislertt/zerv) in action. Shows how to implement automated versioning for CI/CD pipelines, generating multiple formats (semver, PEP440, Docker tags) with flexible branching strategy framework.\n\n## Overview\n\n**What is zerv?**\n\n- A Rust-based versioning tool that generates semantic versions from git current state (latest tag and current commit)\n- Generates versions in multiple formats: semver, pep440, and docker_tag\n- Supports flexible branching strategies and version generation rules\n- More details can be found at [https://github.com/wislertt/zerv](https://github.com/wislertt/zerv)\n\n**Why use this setup?**\n\n- Automated versioning for multi-environment CI/CD pipelines\n- Flexible deployment controls to match your team's speed vs quality needs\n- Dynamic GitOps approach: main branch represents all environments by default, PR labels can temporarily shift environment representation to specific branches\n- Compatible with popular branching strategies (Trunk-based, GitFlow, Release Trains)\n\n**Quick start**\n\n1. Fork this repository\n2. Install zerv locally for testing\n3. Create a PR to test the workflow\n4. Add `deploy-d`, `deploy-n`, `deploy` and `pre-release` labels\n\n## Prerequisites\n\n- Main branch tagged with semantic version format (major.minor.patch) - recommend using [semantic-release](https://github.com/semantic-release/semantic-release)\n- For multiple long-live branches (e.g., git flow with develop branch): Enable \"Require branches to be up to date before merging\" protection rule for main branch\n- Deployment pipeline must follow function pattern and be idempotent. There are 2 common deployment patterns:\n    - `deploy_without_env(repo, versions)`: For immutable releases (e.g., Python packages)\n        - Each new version does not override previous versions\n        - Example: Publishing to PyPI with incrementing version numbers\n    - `deploy_with_env(repo, env_name, versions)`: For environment-specific deployments (e.g., Cloud Run services)\n        - New version overrides existing version in specified environment\n\n## Deployment Assumptions for This Repo (Configurable)\n\n- **Environment codes**: d (development), n (nonproduction), p (production) following [GCP landing zone convention](https://docs.cloud.google.com/architecture/blueprints/security-foundations/summary#naming-conventions)\n    - Note: These can be configured to any naming convention (e.g., dev/staging/prod)\n- **Version formats**: This repository demonstrates 3 formats: - Semver: For git repository tags and releases - PEP440: For Python package versions - Docker Tag: For container registry tags\n    - Note: This demo repository only echoes these formats as examples, but in a real deployment pipeline they would be used for their respective purposes.\n    - Note: Configure zerv to generate formats based on your deployment requirements and constraints. See [zerv documentation](https://github.com/wislertt/zerv) for all supported formats.\n- **Deployment triggers**: Uses PR labels with configurable prefixes:\n    - `deploy-` prefix for environment-specific deployments (e.g., `deploy-d`, `deploy-n`)\n    - `deploy` for environment-less deployments (e.g., immutable releases)\n    - `pre-release` for creating release candidates with tagging\n    - These label prefixes can be configured to match your deployment naming conventions\n\n## Branching Strategy Design\n\n- **Core concept**: GitOps approach where branches represent environment states\n- **Main branch**: Represents all environments by default, uses semantic version control\n- **All non-main branches**: Versioned by zerv when creating PRs\n- **Environment representation via PR labels**: Temporarily shifts environment representation from main branch to the PR branch\n    - PR with `deploy-d` label = branch represents development environment\n    - PR with `deploy-n` label = branch represents nonproduction environment\n- **Environment-less deployment trigger**:\n    - PR with `deploy` label = deploy without environment using version from the branch (e.g., for immutable releases)\n- **Locking mechanism**: Prevents concurrent deployments to same environment\n    - First PR with deploy-X label acquires lock for environment X\n    - Subsequent PRs with same label fail until lock is released\n    - Lock releases when PR merges/closes or label is removed\n- **Deployment flow**:\n    - PR with label deploys to specific environment immediately\n    - When PR merges to main, CD pipeline deploys to ALL environments\n\n## Speed vs Quality Tradeoff\n\n- Flexible deployment controls to match your team's needs\n- Example for higher quality nonproduction: Only allow `deploy-n` on `release/*` branches, with required PR reviews before merging to release branch\n- Example for fast POC development: Allow `deploy-p` directly in PRs for rapid iteration (accepting potential failures in production environment)\n- Adapt the strategy to your context - balance speed vs quality based on your project requirements\n\n## Deployment Flow Examples\n\nThe following scenarios demonstrate how the deployment flow works in practice:\n\n- **Initial State**: Only the main branch exists. All environments (development, nonproduction, production) and environment-less deployments reference version `v1.1.2` from the main branch.\n  ![Initial Deployment State](https://raw.githubusercontent.com/wislertt/zerv-flow/main/docs/assets/deployment-flow-1.excalidraw.svg)\n\n- **Feature Branch Deployment**: A `feature/1` branch is created with PR labels `deploy-n` and `deploy`. The nonproduction environment deploys version `v1.1.3-alpha.1.post.2` from the feature branch and becomes locked to it. Development and production remain on main branch `v1.1.2`. The environment-less deployment creates a new version `v1.1.3-alpha.1.post.2` without overriding previous versions.\n  ![Feature Branch Deployment](https://raw.githubusercontent.com/wislertt/zerv-flow/main/docs/assets/deployment-flow-2.excalidraw.svg)\n\n- **Concurrent Feature Deployment**: While `feature/1` PR is active, a `feature/2` branch is created with PR labels `deploy-d`, `deploy-n`, and `deploy`. Nonproduction deployment fails due to being locked by `feature/1`. Development deploys successfully with version `v1.1.3-alpha.2.post3` from `feature/2`. Environment-less deployment creates another new version `v1.1.3-alpha.2.post.3` alongside the existing version.\n  ![Concurrent Feature Deployment](https://raw.githubusercontent.com/wislertt/zerv-flow/main/docs/assets/deployment-flow-3.excalidraw.svg)\n\n## Branch Rules and Version Generation (Configurable)\n\nThis repository uses the default branch rules from `zerv flow` command. For complete implementation details, see the [shared workflow](https://github.com/wislertt/zerv/blob/main/.github/workflows/shared-zerv-versioning.yml).\n\n- **Feature branches** (default): Generate alpha pre-releases with branch-based identification\n    - Numbered feature branches (`feature/1/xyz`): Extracts number from branch name\n        - Example: `1.0.1-alpha.1.post.1+feature.1.xyz.1.g4e9af24`\n    - Non-numbered feature branches (`feature/xyz`): Uses 5-digit hash for identification\n        - Example: `1.0.1-alpha.48993.post.1+feature.xyz.3.g4e9af24`\n    - Uses commit distance for post count\n\n- **\"develop\" branch**: Generates beta pre-releases with stable numbering\n    - Example: `1.0.1-beta.1.post.1+develop.3.g4e9af24`\n    - Uses commit distance for post count\n\n- **\"release/\\*\" branches**: Generates release candidates with extracted or hash-based numbering\n    - Regular release branches: `1.0.1-rc.1.post.1.dev.1764382150+release.1.do.something.3.g4e9af24` (full version)\n    - With `pre-release` label: `1.0.1-rc.1.post.1` (short version, creates tag)\n    - Numbered release branches (`release/1/xyz`): `1.0.1-rc.1.post.1`\n    - Non-numbered release branches (`release/xyz`): `1.0.1-rc.48993.post.1` (5-digit hash RC number)\n    - Uses tag distance for post count\n\n- **Customization**: All branch rules can be configured with `--branch-rules` argument\n\n## Zerv Flow with Common Branching Strategies\n\nZerv Flow is designed as a generalized branching framework that builds on top of version generation rules. Rather than being a rigid branching strategy itself, it provides a flexible foundation that's compatible with existing popular branching strategies.\n\n- **Trunk-based / GitHub Flow**:\n    - Structure: Main branch + short-lived feature branches\n    - Compatible out-of-the-box with default branch rules\n\n- **GitFlow** (Adaptive - not 100% traditional GitFlow):\n    - Structure: Main + develop long-lived branches + feature/release/hotfix branches\n    - Simplified release branches: `release/1/feature-name` or `release/feature-name` (no manual version bumping needed)\n    - Requirements: Enable \"Require branches to be up to date before merging\" for main branch protection rule\n    - Configuration: Update branch rules if develop branch has different name\n    - Note: This adapts traditional GitFlow (designed 2010, pre-CI/CD) for modern workflows. Even the author now suggests adapting it to your context: [nvie.com](https://nvie.com/posts/a-successful-git-branching-model/)\n\n- **Release Trains**:\n    - Structure: Main + develop as accumulation branch, feature branches from develop, periodic releases\n    - Process: Create release branches from develop on schedule, merge to main for releases\n    - Requirements: Enable \"Require branches to be up to date before merging\" for main branch protection rule\n\n- **GitLab Flow (Environment Branches)**:\n    - Note: Not designed to support this strategy by default\n    - Could work with custom configuration but considered out of scope for this framework\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwislertt%2Fzerv-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwislertt%2Fzerv-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwislertt%2Fzerv-flow/lists"}