@ferrflow/doc 7.17.0

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

@@ -0,0 +1,120 @@
+---
+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@v5` 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@v5
+        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.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Prefer not to manage a token? Set <code>bot: true</code> to author releases as <code>ferrflow[bot]</code> with zero secrets: see the <a href="/docs/ci/hosted-bot">Hosted bot</a> guide.</p>
+</div></aside>
+
+## 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@v5
+  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@v5
+        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@v5
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# Creates api@v1.3.0 and site@v0.5.1 in one step if both changed
+```

package/docs-en/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-en/ci/hosted-bot.md

@@ -0,0 +1,82 @@
+---
+title: Hosted bot (ferrflow[bot])
+description: Author releases as ferrflow[bot] with zero secrets, using the hosted FerrFlow GitHub App and OIDC token exchange.
+---
+
+By default, the releases and tags FerrFlow pushes are authored by whoever owns the token in your workflow: usually a personal access token, so releases show up under _your_ account. The hosted bot lets releases be authored by **`ferrflow[bot]`** instead, with a clean, consistent identity across every repo.
+
+It works like Renovate or Dependabot:
+
+- **Zero secrets** in your workflow. No PAT to create, store, or rotate.
+- Releases authored by **`ferrflow[bot]`**.
+- **Short-lived, scoped tokens**: each run gets a fresh token that expires in an hour and is scoped to the single repository.
+
+## 1. Install the app
+
+Go to **[github.com/apps/ferrflow](https://github.com/apps/ferrflow)** and click **Install**, then choose the organization and repositories you want FerrFlow to release. That's it. There are no secrets to create.
+
+The app asks only for **Contents** (read & write, to push tags and create releases) and **Metadata** (read). You can review or uninstall it at any time from your organization's settings.
+
+## 2. Enable it in your workflow
+
+Add `bot: true` to the action and grant the workflow permission to mint an OIDC token:
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # lets the runner prove the repo's identity to FerrFlow
+      contents: read # for checkout; the release push uses the bot token
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history is needed for commit scanning
+
+      - uses: FerrLabs/FerrFlow@v5
+        with:
+          bot: true
+```
+
+`permissions.id-token: write` is required. It's what lets the runner request the OIDC token that proves which repository is calling. Without it, FerrFlow stops with a clear error rather than falling back silently.
+
+## How it works
+
+No secret ever leaves your repository. Each run exchanges a proof of identity for a token:
+
+1. The GitHub Actions runner issues a short-lived **OIDC token** describing your repository (audience `ferrflow.ferrlabs.com`).
+2. FerrFlow sends that token to **`api.ferrflow.com`**, which verifies it against GitHub's public keys.
+3. The service signs a **scoped installation token** for the FerrFlow app on your repo (using a private key that never leaves FerrLabs' KMS) and returns it. The token lives for one hour.
+4. FerrFlow uses that token to push tags, commits, and releases, so they're authored by `ferrflow[bot]`.
+
+## Security model
+
+- **The app's private key never leaves FerrLabs' servers**: it lives in a KMS and is only ever used to sign installation tokens server-side.
+- **Your identity is proven by OIDC, not a shared secret**: nothing sensitive is stored in your repo or transmitted from it.
+- **Tokens are minimal and short-lived**: scoped to one repository, expiring after an hour.
+- **You stay in control**: uninstall the app at any time to revoke all access immediately.
+
+## Troubleshooting
+
+FerrFlow never falls back silently: if bot mode can't get a token, it fails with a message naming the exact cause.
+
+| Message                                                           | Cause and fix                                                                                          |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `bot mode requires permissions: id-token: write in your workflow` | The job is missing `permissions.id-token: write`. Add it (see above).                                  |
+| `FerrFlow App not installed on this repository's owner`           | Install the app at [github.com/apps/ferrflow](https://github.com/apps/ferrflow) for this org / repo.   |
+| `FerrFlow hosted bot rate limit hit (429)`                        | Token requests are rate-limited per repository. Retry shortly, or use a PAT via `token:` for that run. |
+| `FerrFlow hosted bot service unavailable`                         | A transient service issue. Check [status.ferrlabs.com](https://status.ferrlabs.com) or retry.          |
+
+## Alternatives
+
+The hosted bot is the recommended path, but it isn't the only one:
+
+- **`token:` with a PAT**: supply your own [personal access token](/docs/ci/github-actions). Releases are authored by that token's owner. Works anywhere, including non-GitHub-Actions CI.
+- **`token:` with your own GitHub App**: if you'd rather run your own bot identity, pass a token minted from your own app.
+- **Default `GITHUB_TOKEN`**: the simplest option, but note that pushes made with `GITHUB_TOKEN` **do not trigger downstream workflows** (so a tag push won't kick off a separate publish job). The hosted bot and PATs don't have this limitation.

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

@@ -0,0 +1,287 @@
+---
+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@v5
+        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@v5
+        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@v5
+        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@v5
+        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 }}"
+```
+
+## Concurrency safety
+
+Since v5.2, `ferrflow release` acquires `.git/ferrflow.lock` atomically (`O_CREAT|O_EXCL`) at the start of every mutating run. A second concurrent invocation on the same repo fails fast with a clear error rather than racing on git refs: the classic failure mode is a manually-triggered release firing at the same time as a cron-driven `auto-release`, producing half-pushed tag sets, non-fast-forward rejects, or duplicate draft releases.
+
+You don't need to wire anything up. The lock is automatic on every `release` invocation. Read-only commands (`check`, `status`, `version`, `tag`) skip it.
+
+If a previous run crashed without releasing the lock, the next invocation takes it over automatically after 30 minutes (the host + PID stamped inside the lockfile lets FerrFlow detect stale locks). To take it over sooner, delete `.git/ferrflow.lock` manually.
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p>The lock is per-repo, scoped to <code>.git/</code>. It does not protect across separate clones of the same repo: if you run releases concurrently from two different runners against two different checkouts of the same remote, the lock won&#39;t see the other side. Use a single release runner, or serialize at the CI level (<code>concurrency:</code> in GitHub Actions, <code>interruptible: false</code> in GitLab).</p>
+</div></aside>
+
+## Crash-resume
+
+A release does several side-effecting steps in sequence: write versioned files → commit → tag → push commit → push tags → create GitHub Releases → run `post_publish` hooks. If the process dies between any of those (network blip, runner termination, SIGKILL), the repo is in a half-released state.
+
+Since v5.3, FerrFlow writes a `.git/ferrflow.checkpoint.json` after each phase succeeds. The next `ferrflow release` invocation on the same commit resumes from the recorded phase and skips the work that already happened: useful at CI scale where transient failures are routine. The checkpoint is deleted automatically when a release finishes cleanly.
+
+Two safety rails:
+
+- HEAD-pinning: the checkpoint records the commit SHA the release was operating on. If you advance HEAD between runs, FerrFlow refuses to resume and tells you to either reset HEAD back to the recorded commit or delete the checkpoint manually. This avoids replaying old tags onto a different commit graph.
+- Idempotency: the underlying git and forge operations already no-op when their target exists (a tag that's already pushed is a no-op, a release that already exists is reused), so a mid-phase crash still recovers cleanly on the next run.
+
+To start fresh after a crash you don't want to resume from, delete `.git/ferrflow.checkpoint.json` manually.
+
+## 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 |