Step Configuration

Steps are the building blocks of Bivvy workflows. Each step represents a task to be executed during setup.

Basic Step

steps:
  install_deps:
    command: npm install
    title: Install dependencies
    description: Install Node.js dependencies from package.json

Sensitive Steps

Mark steps that handle sensitive data:

steps:
  fetch-secrets:
    command: vault read secret/myapp
    sensitive: true
    description: Fetch secrets from Vault

Sensitive steps receive special treatment:

1. Confirmation prompt: In interactive mode, Bivvy asks for confirmation before running sensitive steps

2. Hidden in dry-run: The actual command is not shown during --dry-run, displaying [SENSITIVE - command hidden] instead

3. Suppressed output: Command output is not logged to prevent accidental exposure of sensitive data

4. No history: Sensitive commands are not recorded in execution history

Completed Checks

Determine if a step is already complete:

steps:
  node_modules:
    command: npm install
    completed_check:
      type: file_exists
      path: node_modules

  bundle:
    command: bundle install
    completed_check:
      type: command_succeeds
      command: bundle check

Check Types

• file_exists: Check if a file or directory exists
• command_succeeds: Check if a command exits with code 0
• marker: Use Bivvy’s internal marker system
• all: All sub-checks must pass
• any: At least one sub-check must pass

Preconditions

A precondition is a gate that must pass before a step runs. If the precondition fails, the step fails immediately with a hard error.

steps:
  release:
    command: "git tag v1.0.0 && git push --tags"
    precondition:
      type: command_succeeds
      command: "test $(git branch --show-current) = main"

Preconditions use the same check types as completed_check (command_succeeds, file_exists, all, any, etc.) but with opposite semantics:

	completed_check	precondition
When check passes	Step is skipped (already done)	Step proceeds normally
When check fails	Step runs	Step fails (hard stop)
--force behavior	Bypasses the check	No effect (never bypassed)

Combining with Completed Checks

When a step has both completed_check and precondition, the completed check is evaluated first. If the step is already complete, it is skipped and the precondition is never evaluated.

steps:
  release:
    command: "git tag v1.0.0 && git push --tags"
    completed_check:
      type: command_succeeds
      command: "git tag -l v1.0.0 | grep -q v1.0.0"
    precondition:
      type: all
      checks:
        - type: command_succeeds
          command: "test $(git branch --show-current) = main"
        - type: command_succeeds
          command: "git diff --quiet"

Dependencies

Specify step dependencies:

steps:
  database:
    command: rails db:setup
    depends_on: [deps, migrations]

Environment Variables

Set step-specific environment variables:

steps:
  test:
    command: npm test
    env:
      NODE_ENV: test
      CI: "true"
    env_file: .env.test

Hooks

Run commands before and after the step:

steps:
  database:
    command: rails db:setup
    before:
      - echo "Starting database setup..."
    after:
      - echo "Database ready!"

Requirements

Declare system-level prerequisites that must be available before a step runs:

steps:
  bundle_install:
    command: bundle install
    requires:
      - ruby
      - postgres-server

When a requirement is missing, Bivvy offers to install it before running the step. See Requirements for the full list of built-in requirement names and custom requirement definitions.

Environment Filtering

Restrict a step to specific environments with only_environments:

steps:
  seed_data:
    command: rails db:seed
    only_environments:
      - development
      - staging

Steps with an empty list (the default) run in all environments.

Per-Environment Overrides

Override step fields for specific environments:

steps:
  database_setup:
    command: rails db:setup
    env:
      RAILS_ENV: development

    environments:
      ci:
        command: rails db:schema:load
        env:
          RAILS_ENV: test
      docker:
        env:
          DATABASE_HOST: db
          RAILS_ENV: null  # Removes RAILS_ENV in Docker

Only the fields you specify are overridden; everything else inherits from the base step. Set an env var to null to remove it for that environment.

See Environments for all overridable fields and detection configuration.