cascade

README

Cascade

A Go CLI tool that orchestrates automated dependency updates across multiple Go repositories.

Purpose

Cascade manages dependency updates by coordinating operations across multiple Go repositories. It reads a manifest file that defines module dependencies and their relationships, then plans and executes update operations through GitHub pull requests.

How It Works

Cascade follows a unidirectional data flow:

1. Load dependency manifest (YAML configuration)
2. Plan update operations based on dependency graph
3. Execute Git and Go module operations
4. Create and manage GitHub pull requests
5. Track operation state and checkpoints

Architecture

Packages are segmented by responsibility:

• internal/manifest – manifest loading, validation, (future) generation
• internal/planner – computes deterministic work items
• internal/executor – performs git/go/command execution
• internal/broker – manages PR lifecycle and notifications
• internal/state – persists run summaries and item state for resume/revert
• pkg/di – dependency injection container wiring CLI to implementations

Installation

Go install

go install github.com/goliatone/cascade@latest

Homebrew (macOS)

brew tap goliatone/homebrew-tap
brew install cascade

Homebrew downloads the latest formula from goliatone/homebrew-tap. Each GoReleaser publication updates that tap automatically, so after a release you can run brew update && brew upgrade cascade to pull the new build.

Usage

End-to-End Example: Updating github.com/goliatone/go-errors

The following workflow shows how to bootstrap, plan, execute, and monitor a dependency rollout for the local go-errors module located at ~/Development/GO/src/github.com/goliatone/go-errors.

Prerequisites

• Go 1.21+
• GitHub token with repo scope exported as CASCADE_GITHUB_TOKEN
• Optional Slack webhook/token for notifications

export CASCADE_GITHUB_TOKEN=ghp_example123
export CASCADE_SLACK_TOKEN=xoxb-example # optional

1. Generate a Manifest

WORKSPACE=$HOME/.cache/cascade
TARGET_MODULE=github.com/goliatone/go-errors
TARGET_VERSION=v1.4.0

cascade manifest generate \
  --module-path="$TARGET_MODULE" \
  --version="$TARGET_VERSION" \
  --workspace="$WORKSPACE" \
  --github-org=goliatone \
  --yes \
  --output=.cascade.yaml

Highlights:

• Workspace discovery scans $WORKSPACE for Go modules that already depend on go-errors and pre-populates the manifest.
• GitHub discovery (enabled by --github-org or config defaults) augments the workspace scan by hitting the GitHub API to find other dependents in the organization.
• Version resolution understands --version=latest or an omitted version flag and resolves the latest published tag, falling back to local usage when offline.
• Config-driven defaults for tests, notifications, branch naming, and discovery filters reduce the number of CLI flags you need.

The generated .cascade.yaml lands in the current directory unless you pass an absolute --output path.

2. Inspect & Adjust

cat .cascade.yaml

Confirm branch names, commands, labels, and notification targets before executing. Edit as needed. Cascade shows a discovery summary (workspace + GitHub results) and, unless --yes/--non-interactive is set, prompts for confirmation so you can deselect repositories before generation.

3. Plan the Rollout (Dry Run)

cascade plan \
  --manifest=.cascade.yaml \
  --module="$TARGET_MODULE" \
  --version="$TARGET_VERSION" \
  --dry-run \
  --quiet

The plan output lists repositories, branches, commands, and PR metadata without touching any repositories.

Local Dependency Updates

Use the local workflow when the current Go module depends on sibling repositories in the same workspace and you want to update those dependencies from each sibling's local .version or VERSION file. This does not use manifests, GitHub, branches, pull requests, or release state.

# Preview outdated direct github.com/goliatone/* dependencies
cascade plan local

# Apply the same local plan from the current module
cascade update local

# Preview the update path without changing go.mod or go.sum
cascade update local --dry-run

By default, local commands inspect direct require entries matching github.com/goliatone/*, skip indirect dependencies, and skip dependencies with replace directives. Workspace resolution uses --workspace, CASCADE_WORKSPACE, config file workspace.path, then local detection. If the workspace cannot be detected from the current module location, pass it explicitly:

cascade plan local --workspace="$HOME/Development/GO/src/github.com/goliatone"
cascade update local --workspace="$HOME/Development/GO/src/github.com/goliatone"

Useful filters:

• --prefix - include module prefixes; repeat it or pass comma-separated values
• --include-indirect - include indirect require entries
• --only - include only specific module paths or basenames
• --exclude - skip specific module paths or basenames
• --no-tidy - for update local, skip the default go mod tidy
• --no-hooks - for update local, skip configured local update hooks

cascade update local runs one go get <module>@<local-version> per outdated candidate and then runs go mod tidy once after at least one successful update unless --no-tidy is set. If one go get fails, later candidates are still attempted; the command prints the summary and exits with a failure.

Local Update Hooks

Configure optional post-update hooks in .cascade.yaml under hooks.update.local. Hooks run from the current module directory by default, in the order listed for each phase:

hooks:
  update:
    local:
      after:
        - name: test
          run: go test ./...
      after_failure:
        - name: report
          cmd: [./scripts/report-local-update-failure.sh]
      always:
        - name: cleanup
          run: ./scripts/cleanup.sh

after is accepted as an alias for after_success and runs before explicit after_success hooks. Successful updates run after_success and always; failed updates run after_failure and always.

Use run for shell commands and cmd for direct argv execution without shell interpretation. A hook can also set dir, env, and timeout:

hooks:
  update:
    local:
      after_success:
        - name: generated-check
          cmd: [go, test, ./...]
          dir: ./services/api
          env:
            CASCADE_LOCAL_CHECK: "1"
          timeout: 2m

Hooks can also be defined as named rules in a user config such as ~/.config/cascade/config.yaml. Global config loads before ancestor workspace configs and project .cascade.yaml files. When multiple ancestor .cascade.* files exist, Cascade loads them from outermost to nearest, so the nearest project config has the highest file precedence:

hooks:
  update:
    local:
      rules:
        - name: goliatone/test-local
          match:
            module_prefixes: [github.com/goliatone/]
            workspace_prefixes: ["~/Development/GO/src/github.com/goliatone"]
          after_success:
            - name: test
              run: go test ./...

Rule matchers support modules, module_prefixes, workspaces, workspace_prefixes, module_dirs, module_dir_prefixes, exclude_modules, and exclude_module_prefixes. Empty match criteria are unconditional for that rule. A project can override an inherited rule by reusing the same name, or disable inherited rules by name:

hooks:
  update:
    local:
      disabled_rules:
        - goliatone/test-local

If the same config layer defines a rule and lists that rule in disabled_rules, the disable wins and the rule is not evaluated. Keep disables in the nearest project config when the goal is to suppress inherited global or workspace rules.

Dry runs do not execute hooks and print a skip note when hooks are configured, including matched rule names and source scopes for rule-based hooks. Use cascade update local --no-hooks to apply local updates without running hooks. A failed hook stops later hooks in the same phase, still allows later selected phases such as always to run, and makes cascade update local exit with an execution error after hook results are printed.

4. Execute the Release

cascade release \
  --manifest=.cascade.yaml \
  --workspace="$WORKSPACE" \
  --parallel=2 \
  --timeout=15m \
  --state-dir="$WORKSPACE/state" \
  --verbose

Cascade will clone or update repos under the workspace, create branches like auto/go-errors-v1.4.0, update Go modules, run tests/commands, push commits, open PRs, and (if configured) notify Slack. Run state is persisted for recovery.

5. Monitor & Recover

# Preview stored state without mutating anything
cascade resume go-errors@v1.4.0 --dry-run

# Continue an interrupted run
cascade resume go-errors@v1.4.0

# Roll back branches/PRs recorded in state
cascade revert go-errors@v1.4.0

Command Reference

• cascade manifest generate – scaffold manifests with defaults, dependents, and notifications
• cascade plan – preview work items from a manifest or flags
• cascade plan local – preview local sibling dependency updates
• cascade update local – apply local sibling dependency updates
• cascade release – execute the plan (honors --dry-run)
• cascade resume – resume an interrupted release using module@version
• cascade revert – delete branches/PRs captured in state summaries

# Quick cheatsheet
cascade manifest generate --module-path=$TARGET_MODULE --version=latest --github-org=goliatone --yes --dry-run
cascade plan --manifest=.cascade.yaml --dry-run
cascade plan local --workspace=$HOME/Development/GO/src/github.com/goliatone
cascade update local --dry-run
cascade release --manifest=.cascade.yaml
cascade resume go-errors@v1.4.0
cascade revert go-errors@v1.4.0

Workflow Generation

cascade workflow generate scaffolds a GitHub Actions workflow that runs Cascade whenever a release tag is pushed. The command creates .github/workflows/cascade-release.yml by default, infers repository metadata, and can be re-run safely to overwrite the workflow when templates change.

cascade workflow generate --output .github/workflows/cascade-release.yml

Flags:

• --output (default .github/workflows/cascade-release.yml) – choose a different path or filename
• --template – render an alternate Go text/template file instead of the embedded default
• --module – override the module detected from go.mod (handy for tests or monorepos)
• Global flags like --dry-run, --yes, and --force control preview and confirmation behaviour

Secrets and tokens:

• The generated workflow expects a repository secret named CASCADE_GITHUB_TOKEN. Map this to a personal access token with the repository scopes Cascade requires (cross-repo cloning, PR creation).
• GitHub automatically exposes GITHUB_TOKEN, but it is limited to the current repository. If you only need repo-scoped permissions you can define a secret named CASCADE_GITHUB_TOKEN that references ${{ secrets.GITHUB_TOKEN }}.
• Slack notifications (optional) read from CASCADE_SLACK_TOKEN; omit the secret if Slack is not used.

Custom templates:

1. Copy cmd/cascade/templates/workflow/github_actions.yaml.tmpl to a location you control.
2. Adjust steps, matrix definitions, or secrets as needed.
3. Run cascade workflow generate --template custom-workflow.tmpl --output .github/workflows/cascade-release.yml to render your version.

Use --dry-run to print the rendered YAML to stdout without touching the filesystem. The command always creates missing parent directories, so it is safe to run in a fresh repository.

CI/CD Mode

Cascade supports running in CI/CD environments without requiring a local workspace. This enables dependency checking and PR automation directly from your CI pipeline.

Dependency Checking Strategies

Cascade uses intelligent dependency checking to avoid unnecessary updates:

• local - Check dependencies using local workspace repositories (fastest, requires workspace)
• remote - Clone repositories remotely via shallow git clones (works without workspace)
• auto - Try local first, fall back to remote if unavailable (recommended)

When a local workspace reports that a repository still requires an update, Cascade confirms the result against the remote repository before scheduling work. This keeps plan/release runs accurate even if a cached workspace has not been refreshed since the dependent was fixed upstream.

CI/CD Configuration

Use the following flags to optimize for CI/CD environments:

cascade release \
  --manifest=.cascade.yaml \
  --check-strategy=remote \
  --check-parallel=8 \
  --check-cache-ttl=10m \
  --skip-up-to-date

Flags:

• --check-strategy - Dependency checking mode (local, remote, auto)
• --check-parallel - Number of parallel dependency checks (default: CPU count)
• --check-cache-ttl - Cache expiration time (default: 5m)
• --check-timeout - Per-repository check timeout (default: 30s)
• --skip-up-to-date - Skip repositories already at target version

Authentication

For private repositories, configure authentication via environment variables:

# GitHub token (required for private repos)
export CASCADE_GITHUB_TOKEN=ghp_example123
# or
export GITHUB_TOKEN=ghp_example123
# or
export GH_TOKEN=ghp_example123

# SSH key path (optional, defaults to ~/.ssh/id_rsa)
export SSH_KEY_PATH=~/.ssh/cascade_deploy_key

Performance Optimization

Cache Hit Rate: Cascade caches dependency information to avoid redundant git operations. Monitor cache performance:

Dependency Checking (remote mode):
- Checked 14 repositories (5 cached, 9 fetched)
- 11 repositories up-to-date, skipped
- 3 require updates
- Check duration: 12.3s (parallel: 4)

Tuning Tips:

• Increase --check-parallel for large dependency graphs
• Use --check-strategy=remote in CI environments without workspace
• Set --check-cache-ttl=10m for repeated CI runs
• Monitor warnings for slow checks (>30s) and low cache hit rates (<50%)

Example: GitHub Actions Workflow

See the "CI/CD Pipeline Examples" section below for complete workflow configurations.

Configuration

Manifest File

The .cascade.yaml manifest file defines module dependencies and update rules. You can generate a starter manifest using cascade manifest generate, or craft one manually. Each repository can now describe both how it should be released (the top-level module block) and how it expects upstream releases to validate against it (entries under the top-level dependents map):

manifest_version: 1

module:
  module: github.com/goliatone/go-errors
  branch: main
  tests:
    - cmd: [go, test, ./...]
  extra_commands:
    - cmd: [go, vet, ./...]
  notifications:
    slack_channel: "#go-errors"

defaults:
  branch: main
  tests:
    - cmd: [go, test, ./..., -race]
  commit_template: "chore(deps): bump {{ .Module }} to {{ .Version }}"
  pr:
    title_template: "chore(deps): bump {{ .Module }} to {{ .Version }}"
    body_template: |
      Automated update for {{ .Module }} to {{ .Version }}.

      **Changes:**
      - {{ .Module }}: {{ .OldVersion }} → {{ .Version }}

modules:
  - name: go-errors
    module: github.com/goliatone/go-errors
    repo: goliatone/go-errors
    dependents:
      - repo: goliatone/go-logger
        module: github.com/goliatone/go-logger
        tests:
          - cmd: [go, test, ./...]
      - repo: goliatone/go-router
        module: github.com/goliatone/go-router
        tests:
          - cmd: [go, test, ./...]
          - cmd: [go, test, ./...]
            dir: router/

notifications:
  slack:
    channel: "#releases"
  github_issues:
    enabled: true
    labels:
      - cascade-failure
      - dependencies

dependents:
  github.com/goliatone/go-errors:
    tests:
      - cmd: [task, dependent:test]
    extra_commands:
      - cmd: [task, dependent:lint]
    env:
      CI: "true"

When Cascade plans a release it merges configuration in this order:

1. Global defaults from the releasing repository
2. The dependent repository's own module block (if present in its .cascade.yaml)
3. The dependent repository's dependents[<module>] override for the module being updated

This precedence keeps legacy manifests working while giving each dependent full control over the tests, extra commands, environment, notifications, and timeouts it requires.

Configuration Sources

Cascade uses the following precedence (highest to lowest):

1. Command-line flags
2. Environment variables (CASCADE_*)
3. Configuration files (~/.config/cascade/config.yaml)
4. Built-in defaults

Manifest Generator Defaults

Populate manifest_generator in config.yaml to predefine discovery behavior, test commands, and notifications:

manifest_generator:
  default_workspace: ~/.cache/cascade
  default_branch: main
  tests:
    command: go test ./... -race -count=1
  notifications:
    enabled: true
    channels: ["#releases"]
    on_success: false
    on_failure: true
    github_issues:
      enabled: true
      labels: ["cascade-failure", "dependencies"]
  discovery:
    enabled: true
    max_depth: 3

The logic that maps configuration into manifest defaults lives in `pkg/config/defaults.go`. Update those helpers to adjust the built-in branch, test command, or discovery filters across the CLI.
    include_patterns: ["services/*"]
    exclude_patterns: ["vendor/*", ".git/*", "node_modules/*"]
    github:
      enabled: true
      organization: goliatone
      include_patterns: ["go-*", "lib-*"]

integration:
  github:
    token: ${CASCADE_GITHUB_TOKEN}

With this configuration in place, manifest generation typically only needs the module path and desired version:

cascade manifest generate --module-path=$TARGET_MODULE --version=latest --yes

Cascade resolves the latest tag, discovers dependents in the workspace and GitHub org, applies the default test command, and writes the manifest to .cascade.yaml.

Examples

See the examples/ directory for complete manifests:

• basic-manifest.yaml – minimal configuration
• full-featured-manifest.yaml – multiple dependents and notifications
• custom-templates-manifest.yaml – advanced templating and workflows

CI/CD Pipeline Examples

GitHub Actions

Create .github/workflows/cascade-release.yml to run whenever a new tag matching v*.*.* is pushed. The workflow builds Cascade from the tagged source, resolves the module/version automatically, and keeps the state directory aligned with the uploaded artifact.

name: Cascade Dependency Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    env:
      TARGET_VERSION: ${{ github.ref_name }}
      CASCADE_STATE_DIR: ${{ github.workspace }}/.cascade/state
      CASCADE_GITHUB_TOKEN: ${{ secrets.CASCADE_GITHUB_TOKEN }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.21'

      - name: Discover module path
        id: module
        run: echo "module=$(go list -m)" >> "$GITHUB_OUTPUT"

      - name: Build Cascade CLI from tag
        run: go build -o /usr/local/bin/cascade ./cmd/cascade

      - name: Generate Manifest
        env:
          GITHUB_OWNER: ${{ github.repository_owner }}
        run: |
          cascade manifest generate \
            --module-path="${{ steps.module.outputs.module }}" \
            --version="${TARGET_VERSION}" \
            --github-org="${GITHUB_OWNER}" \
            --yes \
            --output=.cascade.yaml

      - name: Plan Release
        run: |
          cascade plan \
            --manifest=.cascade.yaml \
            --module="${{ steps.module.outputs.module }}" \
            --version="${TARGET_VERSION}" \
            --check-strategy=remote \
            --check-parallel=8 \
            --skip-up-to-date \
            --quiet

      - name: Execute Release
        env:
          CASCADE_SLACK_TOKEN: ${{ secrets.CASCADE_SLACK_TOKEN }}
        run: |
          cascade release \
            --manifest=.cascade.yaml \
            --module="${{ steps.module.outputs.module }}" \
            --version="${TARGET_VERSION}" \
            --check-strategy=remote \
            --check-parallel=8 \
            --check-cache-ttl=10m \
            --skip-up-to-date \
            --parallel=4 \
            --timeout=20m \
            --verbose

      - name: Upload Cascade state
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cascade-state
          path: ${{ env.CASCADE_STATE_DIR }}

Secrets: Provision CASCADE_GITHUB_TOKEN with a PAT that can push branches and open PRs across dependent repositories. CASCADE_SLACK_TOKEN remains optional.

GitLab CI

Create .gitlab-ci.yml:

cascade:release:
  stage: deploy
  image: golang:1.21
  script:
    - go install github.com/goliatone/cascade@latest
    - |
      cascade manifest generate \
        --module-path="${MODULE}" \
        --version="${VERSION}" \
        --github-org="${CI_PROJECT_NAMESPACE}" \
        --yes \
        --output=.cascade.yaml
    - |
      cascade release \
        --manifest=.cascade.yaml \
        --check-strategy=remote \
        --check-parallel=8 \
        --check-cache-ttl=10m \
        --skip-up-to-date \
        --parallel=4 \
        --timeout=20m \
        --verbose
  variables:
    MODULE: "github.com/example/module"
    VERSION: "v1.0.0"
  artifacts:
    paths:
      - .cascade/state/
    when: always
  only:
    - web

Environment Variables for CI

Configure these secrets in your CI environment:

• CASCADE_GITHUB_TOKEN or GITHUB_TOKEN - GitHub API access
• CASCADE_SLACK_TOKEN - Slack notifications (optional)
• SSH_KEY_PATH - Custom SSH key path (optional)

Development

Prerequisites

• Go 1.21 or later
• Git
• GitHub access token (for PR operations)

Commands

# Run tests
./taskfile dev:test

# Run tests with coverage
./taskfile dev:cover

# Install development tools
./taskfile dev:install

# Build binary
go build -o cascade ./cmd/cascade

Testing

The project uses fixture-driven testing with contract tests. Test data is stored in testdata/ directories within each package.

Status

This is an early-stage project. Core interfaces are defined and the CLI supports planning, releasing, resuming, and reverting cascades, but expect rough edges while tasks in the *_TSK.md files are completed.

License

MIT License — see LICENSE for details.