@ferrflow/doc 7.17.0

package/docs-v2/self-hosting.md

@@ -0,0 +1,101 @@
+---
+title: Self-hosting
+description: Run FerrFlow on your own infrastructure with a single Docker image.
+---
+
+The self-host bundle is a single Docker image that contains the API and the
+dashboard. The API serves the dashboard assets on the same origin, so there is
+only one container to run and no CORS configuration to manage.
+
+Image: `ghcr.io/ferrlabs/ferrflow-selfhost:latest`
+
+## Prerequisites
+
+- Docker 24+ and Docker Compose
+- A PostgreSQL 16 database with the TimescaleDB extension (the reference compose
+  file below provisions one for you)
+
+## Quickstart with Docker Compose
+
+Download the reference compose file and environment template from the
+[Application repository](https://github.com/FerrLabs/Application):
+
+```bash
+curl -O https://raw.githubusercontent.com/FerrLabs/Application/main/docker-compose.selfhost.yml
+curl -o .env https://raw.githubusercontent.com/FerrLabs/Application/main/.env.example.selfhost
+```
+
+Generate secrets and edit `.env`:
+
+```bash
+# Database password (any long random string)
+echo "DB_PASSWORD=$(openssl rand -base64 32)" >> .env.secrets
+# JWT signing secret
+echo "JWT_SECRET=$(openssl rand -base64 64)" >> .env.secrets
+# AES-256-GCM key for encrypting secrets at rest (must be base64-encoded 32 bytes)
+echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env.secrets
+# HMAC secret used by the FerrFlow CLI telemetry endpoint
+echo "FERRFLOW_HMAC_SECRET=$(openssl rand -hex 32)" >> .env.secrets
+```
+
+Merge `.env.secrets` into `.env` manually, then start the stack:
+
+```bash
+docker compose -f docker-compose.selfhost.yml up -d
+```
+
+The dashboard is now available on `http://localhost:3000`.
+
+## Environment variables
+
+| Variable                   | Required               | Purpose                                               |
+| -------------------------- | ---------------------- | ----------------------------------------------------- |
+| `DATABASE_URL`             | yes                    | Postgres connection string                            |
+| `JWT_SECRET`               | yes                    | Signing key for session JWTs                          |
+| `ENCRYPTION_KEY`           | yes                    | 32-byte base64 key for the secrets at-rest encryption |
+| `FERRFLOW_HMAC_SECRET`     | yes                    | HMAC key for CLI telemetry ingestion                  |
+| `SERVER_HOST`              | no (default `0.0.0.0`) | Bind address                                          |
+| `SERVER_PORT`              | no (default `3000`)    | Bind port                                             |
+| `DATABASE_MAX_CONNECTIONS` | no (default `10`)      | Postgres pool size                                    |
+| `RATE_LIMIT_REQUESTS`      | no (default `60`)      | Requests per minute before rate-limiting              |
+| `RUST_LOG`                 | no (default `info`)    | Log level                                             |
+
+## Using an external Postgres
+
+Remove the `db` service and the `depends_on` block from the compose file, then
+point `DATABASE_URL` at your existing instance. The TimescaleDB extension is
+required — create it once with:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS timescaledb;
+```
+
+Migrations run automatically on startup.
+
+## Reverse proxy and TLS
+
+Terminate TLS at a proxy in front of the container. Example Caddyfile:
+
+```caddy
+ferrflow.example.com {
+  reverse_proxy localhost:3000
+}
+```
+
+No CORS origins need to be whitelisted because the browser only talks to the
+single proxy origin.
+
+## Updating
+
+```bash
+docker compose -f docker-compose.selfhost.yml pull
+docker compose -f docker-compose.selfhost.yml up -d
+```
+
+Database migrations are applied on startup. Take a database backup before
+upgrading across a major version.
+
+## Health check
+
+`GET /health` returns `200` once the API has connected to Postgres and applied
+migrations.

package/docs-v3/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@v3` 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@v3
+        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@v3
+  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@v3
+        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@v3
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# Creates api@v1.3.0 and site@v0.5.1 in one step if both changed
+```

package/docs-v3/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-v3/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@v3
+        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@v3
+        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@v3
+        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@v3
+        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 |