AgileFlow

In today's fast-paced software development landscape, maintaining clarity, consistency, and efficiency in the release process is essential. AgileFlow is a streamlined yet powerful versioning system designed for software teams of all sizes and projects of any scale.

AgileFlow enforces Semantic Versioning and integrates seamlessly with your CI/CD pipeline to ensure a structured, efficient, and predictable development lifecycle. All versions are calculated from the main branch's commit history using Conventional Commits, ensuring consistent versioning and release notes. Whether for small projects or large-scale deployments, AgileFlow simplifies versioning and release management.

AgileFlow works with your CI/CD engine to automatically create a new version tag every time there's a merge into the main branch. Your existing build and deploy pipelines then trigger on tag creation, creating a clean separation between versioning and release processes. This decoupled architecture means AgileFlow focuses solely on versioning, while your build and deploy workflows remain independent.

Quick Start

Install the tool

npm install -g @logickernel/agileflow

Preview Your Next Version

agileflow

Create a Version Tag

Push to Remote Git Repository:

agileflow push

CD/CI

GitHub Actions:

agileflow github

GitLab CI:

agileflow gitlab

Learn More: Getting Started Guide • CLI Reference

CI/CD Integration

AgileFlow uses a two-step decoupled approach:

Step 1: Version Creation (AgileFlow)

Create a workflow that runs AgileFlow when code is merged to main:

GitHub Actions (.github/workflows/version.yml):

name: Version
on:
  push:
    branches: [main]

jobs:
  version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Create version tag
        env:
          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
        run: npx @logickernel/agileflow github

GitLab CI (.gitlab-ci.yml):

For a job tagged with agileflow for a GitLab Runner:

include:
  - remote: https://code.logickernel.com/tools/agileflow/-/raw/main/.gitlab-ci.yml

Or manually:

agileflow:
  image: node:20
  script:
    - npm install -g @logickernel/agileflow
    - agileflow gitlab
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Step 2: Build & Deploy (Your Pipelines)

Configure your existing build and deploy pipelines to trigger on tag creation. When AgileFlow creates a version tag (e.g., v1.2.3), your CI/CD platform triggers your release workflow. Use the tag name as the version identifier for your builds and deployments.

Learn More: Installation Guide for detailed setup instructions and examples.

Benefits of Decoupled Architecture

• Separation of concerns — Versioning is independent from build/deploy
• Flexibility — Hook any process to tag creation
• Reusability — Same build pipeline works for any version
• Simplicity — Each pipeline has a single responsibility

Learn More: Installation Guide • Configuration

Conventional Commits

AgileFlow uses Conventional Commits to automatically determine version bumps and generate release notes. Commit messages follow a structured format that encodes the intent of each change:

type(scope): description

The commit type (feat, fix, perf, etc.) indicates what kind of change was made, while the optional scope identifies the area affected. Breaking changes are marked with ! or a BREAKING CHANGE: footer.

Learn More: Conventional Commits Guide

Release Management

Automatic Versioning

Each merge to main triggers automatic version generation based on commit types. See the Version Calculation table below for details on how versions are bumped in 0.x.x vs 1.0.0+.

New projects start at v0.0.0 and automatically increment based on commits. AgileFlow will keep automatically generating versions as you develop (0.0.1, 0.0.2, 0.1.0, etc.). When your product has reached maturity and you have a stable API ready for production, create version 1.0.0 manually.

Version 1.0.0 — First Stable Release

Version 1.0.0 represents your first stable API and marks the transition from initial development to a stable, production-ready release. This version must be created manually when your team decides the API is stable and ready for production use.

Create it when ready:

git tag -a v1.0.0 -m "First stable release"
git push origin v1.0.0

After 1.0.0, AgileFlow continues automatic versioning with standard semantic versioning rules: features bump minor, fixes bump patch, and breaking changes bump major.

Learn More: Release Management Guide

Version Calculation

AgileFlow analyzes commits since the last version tag to determine the appropriate version bump:

| Commit Type | Example | Changelog | 0.x.x | 1.0.0+ | |-------------|---------|-----------|-------|--------| | Breaking change | feat!: redesign API | Add entry | Minor (0.1.0 → 0.2.0) | Major (1.0.0 → 2.0.0) | | Feature | feat: add login | Add entry | Minor | Minor | | Fix | fix: resolve crash | Add entry | Patch | Patch | | Chore | chore: update dependencies | No entry | No bump | No bump | | Everything else | docs: update README | Add entry | No bump | No bump |

Core Principles

Main Branch Strategy

The main branch is the single source of truth for all releases:

• Single Version Sequence — All versions created from the same branch
• Simplified Workflow — No release branches needed
• Consistent History — All releases share the same commit history
• Easy Rollbacks — Deploy any previous version tag

Version-Centric Deployments

Every environment runs the same immutable version:

Tag v1.2.3 ──▶ Build ──▶ Staging
                    ──▶ Production
                    ──▶ Any environment

Learn More: Branching Strategy • Version-Centric CI/CD

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Quick start for new users | | Installation | Setup for GitHub Actions and GitLab CI | | CLI Reference | Command-line options and usage | | Configuration | Environment variables and options | | Conventional Commits | Commit message formatting | | Branching Strategy | Development workflow | | Version-Centric CI/CD | Pipeline methodology | | Release Management | Managing releases effectively | | Migration Guide | Transitioning from other approaches | | Best Practices | Recommended patterns | | Troubleshooting | Common issues and solutions |