AgileFlow

AgileFlow reads your commit history and automatically creates a semantic version tag on every merge to main. Your build and deploy pipelines then trigger on the tag — keeping versioning completely separate from everything else.

No config files. No servers. Versions are calculated from your Conventional Commits and pushed as annotated git tags.

---

Quick Start

Preview your next version in any git repository:

npx @logickernel/agileflow

Commits since current version (3):
  a1b2c3d feat: add dark mode
  d4e5f6a fix: resolve login timeout
  7g8h9i0 docs: update README

Current version: v1.4.2
New version:     v1.5.0

Changelog:

### Features
- add dark mode

### Bug fixes
- resolve login timeout

This is read-only — it never creates tags or modifies anything.

---

CI/CD Integration

AgileFlow uses a decoupled two-step approach:

1. Versioning — AgileFlow runs on merge to main and creates a version tag
2. Release — Your existing build and deploy pipelines trigger on the tag

Merge to main → AgileFlow → Tag v1.5.0 → Your build/deploy

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

Requires an AGILEFLOW_TOKEN secret — a Personal Access Token with Contents: Read and write permission.

GitLab CI

.gitlab-ci.yml:

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

Requires an AGILEFLOW_TOKEN CI/CD variable — a Project Access Token with api scope and Maintainer role.

Other platforms

agileflow push           # creates tag and pushes to origin
agileflow push upstream  # pushes to a different remote

---

Conventional Commits

AgileFlow determines the version bump from commit types:

Commit	Example	Before v1.0.0	v1.0.0 and after
Breaking change	feat!: redesign API	minor bump	major bump
feat	feat: add login	minor bump	minor bump
fix	fix: resolve crash	patch bump	patch bump
Everything else	docs: update README	no bump	no bump

The highest-priority bump across all commits since the last tag wins. If no bump-triggering commits exist, AgileFlow exits without creating a tag.

v1.0.0 — First stable release

New projects start at v0.0.0. AgileFlow increments automatically from there. When your API is stable and ready for production, create v1.0.0 manually:

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

After v1.0.0, breaking changes bump the major version.

---

Documentation

Getting Started	Run locally, understand the output, first CI setup
GitHub Actions	Token setup, workflow files, troubleshooting
GitLab CI	Token setup, pipeline config, troubleshooting
Other CI/CD	Git-push integration for any platform
CLI Reference	All commands and options
Conventional Commits	Commit format and changelog behavior