@ferrflow/doc 7.17.0

package/docs-v4/ci/github-actions.md

@@ -0,0 +1,117 @@
+---
+title: GitHub Actions
+description: Run FerrFlow releases automatically in GitHub Actions.
+---
+
+## Using the official action
+
+The easiest way to use FerrFlow in GitHub Actions is the `FerrLabs/ferrflow@v4` action. It installs the binary and runs `ferrflow release` automatically.
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # required to push tags and create releases
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history needed for commit scanning
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+<aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p><code>fetch-depth: 0</code> is required. Without it, FerrFlow cannot find previous tags and will treat every commit as new.</p>
+</div></aside>
+
+## Permissions
+
+FerrFlow needs `contents: write` to:
+
+- Push version bump commits
+- Create and push git tags
+- Create GitHub Releases
+
+If your repository has branch protection rules, create a dedicated token with the necessary permissions and pass it as `FERRFLOW_TOKEN` or configure the action's `token` input.
+
+## Accessing the release output
+
+The action exposes the new version as an output you can use in downstream steps:
+
+```yaml title=".github/workflows/release.yml"
+- uses: FerrLabs/ferrflow@v4
+  id: ferrflow
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Build Docker image
+  if: steps.ferrflow.outputs.version != ''
+  run: |
+    docker build -t myimage:${{ steps.ferrflow.outputs.version }} .
+    docker push myimage:${{ steps.ferrflow.outputs.version }}
+```
+
+## Skip CI on release commits
+
+FerrFlow commits version bumps with `[skip ci]` in the message by default to prevent infinite loops. No extra configuration needed.
+
+## PR preview comments
+
+FerrFlow can post a comment on every pull request showing what versions will be bumped when the PR is merged. The comment is automatically updated on each push.
+
+```yaml title=".github/workflows/preview.yml"
+name: FerrFlow Preview
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: FerrLabs/ferrflow@v4
+        with:
+          mode: preview
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The comment looks like:
+
+> **FerrFlow Release Preview**
+>
+> | Package | Current | Next    | Bump  |
+> | ------- | ------- | ------- | ----- |
+> | api     | `1.5.0` | `1.6.0` | minor |
+> | site    | `1.8.0` | `1.8.1` | patch |
+>
+> Based on 3 commit(s).
+
+If no releasable changes are detected, the comment says so.
+
+## Monorepo example
+
+In a monorepo, FerrFlow releases each changed package in a single run:
+
+```yaml title=".github/workflows/release.yml"
+- uses: FerrLabs/ferrflow@v4
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# Creates api@v1.3.0 and site@v0.5.1 in one step if both changed
+```

package/docs-v4/ci/gitlab-ci.md

@@ -0,0 +1,90 @@
+---
+title: GitLab CI
+description: Run FerrFlow releases automatically in GitLab CI.
+---
+
+## Using the Docker image
+
+The official FerrFlow Docker image ships the binary and can be used directly as a GitLab CI job image.
+
+```yaml title=".gitlab-ci.yml"
+release:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  stage: release
+  script:
+    - ferrflow release
+  variables:
+    GITLAB_TOKEN: $CI_JOB_TOKEN
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+      when: on_success
+```
+
+<aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p>Make sure your CI runner clones with full history. Add <code>GIT_DEPTH: 0</code> to the job variables to disable shallow cloning.</p>
+</div></aside>
+
+## Full history
+
+```yaml title=".gitlab-ci.yml"
+release:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  variables:
+    GIT_DEPTH: 0 # full history — required for tag scanning
+    GITLAB_TOKEN: $CI_JOB_TOKEN
+  script:
+    - ferrflow release
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+## Using a deploy token
+
+If `CI_JOB_TOKEN` doesn't have permission to push tags, create a project deploy token with `write_repository` access and store it as a CI variable:
+
+```yaml title=".gitlab-ci.yml"
+release:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  variables:
+    GIT_DEPTH: 0
+    GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # CI variable with write_repository access
+  script:
+    - ferrflow release
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+```
+
+## MR preview comments
+
+FerrFlow can post a comment on every merge request showing what versions will be bumped when the MR is merged. The comment is automatically updated on each push.
+
+```yaml title=".gitlab-ci.yml"
+ferrflow-preview:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  stage: test
+  variables:
+    GIT_DEPTH: 0
+    GITLAB_TOKEN: $CI_JOB_TOKEN
+  script:
+    - ferrflow check --comment
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
+
+The comment looks like:
+
+> **FerrFlow Release Preview**
+>
+> | Package | Current | Next    | Bump  |
+> | ------- | ------- | ------- | ----- |
+> | api     | `1.5.0` | `1.6.0` | minor |
+>
+> Based on 2 commit(s).
+
+If no releasable changes are detected, the comment says so.
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p><code>CI_JOB_TOKEN</code> has permission to post MR notes by default. If your project restricts this, use a project access token with <code>api</code> scope stored as a CI variable.</p>
+</div></aside>
+
+## GitLab Releases
+
+When `GITLAB_TOKEN` is set, FerrFlow creates a GitLab Release with the generated changelog as release notes, matching the behaviour of the GitHub integration.

package/docs-v4/ci/pipeline-triggers.md

@@ -0,0 +1,263 @@
+---
+title: Pipeline Triggers
+description: Choose the right CI trigger strategy for your FerrFlow releases.
+---
+
+FerrFlow works with any CI trigger strategy. This page covers the most common patterns, when to use each one, and how they interact with `releaseCommitMode`.
+
+## Push to main
+
+The simplest setup: run `ferrflow release` on every push to the default branch. FerrFlow decides whether a release is needed based on the commits since the last tag.
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Skip release commits to avoid infinite loops
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+**When to use:** Most projects. Simple, predictable, fully automated.
+
+**Trade-offs:** Every push to main triggers a workflow run, even if no release is needed. FerrFlow exits early when there are no releasable commits, so the cost is minimal.
+
+**Works with:** `releaseCommitMode: commit` (default) or `none`.
+
+## Tag-triggered
+
+Run your build/deploy pipeline when FerrFlow creates a new tag. This separates the release step (tagging) from the downstream steps (building, publishing, deploying).
+
+```yaml title=".github/workflows/build.yml"
+name: Build & Publish
+
+on:
+  push:
+    tags:
+      - 'v*' # single-repo: v1.2.0
+      - '*@v*' # monorepo: api@v1.2.0, site@v0.5.1
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG##*v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build
+        run: echo "Building version ${{ steps.version.outputs.version }}"
+```
+
+**When to use:** When you want to decouple versioning from build/deploy. Common for Docker image builds, npm publishing, or binary releases.
+
+**Trade-offs:** Requires two workflows: one for the release (push-to-main) and one for the downstream build (tag-triggered). Adds a few seconds of latency between the tag push and the build start.
+
+### Monorepo: per-package builds
+
+In a monorepo, use tag patterns to build only the package that was released:
+
+```yaml title=".github/workflows/build.yml"
+name: Build Package
+
+on:
+  push:
+    tags:
+      - 'api@v*'
+      - 'site@v*'
+
+jobs:
+  build-api:
+    if: startsWith(github.ref_name, 'api@v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: echo "Building API ${{ github.ref_name }}"
+
+  build-site:
+    if: startsWith(github.ref_name, 'site@v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: echo "Building site ${{ github.ref_name }}"
+```
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p>If FerrFlow releases multiple packages in a single run (e.g. <code>api@v1.3.0</code> and <code>site@v0.5.1</code>), each tag triggers its own workflow run. The builds happen in parallel automatically.</p>
+</div></aside>
+
+## Release-triggered
+
+Run a pipeline when a GitHub Release is published. This works well with FerrFlow's `--draft` flag: FerrFlow creates a draft release, you review it, then publishing triggers the build.
+
+```yaml title=".github/workflows/deploy.yml"
+name: Deploy
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Deploy
+        run: echo "Deploying ${{ github.event.release.tag_name }}"
+```
+
+**When to use:** When you want a manual review gate before deploying. Create draft releases with `ferrflow release --draft`, review the changelog, then publish.
+
+**Trade-offs:** Adds a manual step. The draft release must be published before the deploy runs.
+
+**Works with:** All `releaseCommitMode` values.
+
+## Manual (workflow_dispatch)
+
+Trigger a release on demand with an optional dry-run flag. Useful for controlled release cadences or when you don't want every merge to potentially release.
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run (no tags, no commits, no releases)'
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v4
+        with:
+          args: ${{ inputs.dry_run == true && '--dry-run' || '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+**When to use:** Teams that prefer explicit release decisions over automatic releases. Also useful as a secondary workflow alongside push-to-main for ad-hoc releases.
+
+**Trade-offs:** Requires someone to click "Run workflow" in the Actions tab. Commits can pile up between releases, producing larger changelogs.
+
+## PR-based
+
+Use `releaseCommitMode: pr` to have FerrFlow open a pull request with the version bump instead of committing directly. The release completes when the PR is merged.
+
+```yaml title="ferrflow.json"
+{ 'workspace': { 'releaseCommitMode': 'pr' } }
+```
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+**When to use:** When you want to review version bumps before they land, or when branch protection prevents direct pushes to main.
+
+**Trade-offs:** Adds an extra merge step. The PR must be merged before tags are created.
+
+**Works with:** `releaseCommitMode: pr` only. Requires `pull-requests: write` permission.
+
+## Combining strategies
+
+A common production setup combines push-to-main for versioning with tag-triggered builds:
+
+```yaml title=".github/workflows/release.yml"
+# Workflow 1: Version and tag on every push to main
+name: Release
+on:
+  push:
+    branches: [main]
+jobs:
+  release:
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+      - uses: FerrLabs/ferrflow@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+```yaml title=".github/workflows/build.yml"
+# Workflow 2: Build and deploy when a tag is pushed
+name: Build
+on:
+  push:
+    tags: ['v*', '*@v*']
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: echo "Building ${{ github.ref_name }}"
+```
+
+## Summary
+
+| Trigger           | Automatic | Review gate | Best for                   |
+| ----------------- | --------- | ----------- | -------------------------- |
+| Push to main      | Yes       | No          | Most projects              |
+| Tag-triggered     | Yes       | No          | Decoupled build/deploy     |
+| Release-triggered | No        | Yes         | Draft → review → publish   |
+| Manual            | No        | Yes         | Controlled release cadence |
+| PR-based          | Partial   | Yes         | Branch protection / review |