Production-grade API release automation CLI.
From merged code to healthy pods in production — one command.

1. What Apiforge does
2. Installation
3. Quick start
4. CLI reference
5. Release pipeline behavior
6. Rollback semantics
7. Configuration reference (apiforge.toml)
8. Template variables
9. CI/CD integration
10. Security and reliability model
11. Developer guide
12. Troubleshooting
13. Known limitations
14. Contributing
15. License

Apiforge automates a full release path for API services:

1. Preflight checks for repo and environment.
2. Version bump in language-specific version files.
3. Optional changelog generation.
4. Commit and tag creation.
5. Push to git remote.
6. Optional Docker build/push.
7. Optional Kubernetes image update and rollout wait.
8. Optional GitHub release creation.
9. Optional health-check verification.
10. Automatic rollback of completed steps when a later step fails.

The goal is to make releases repeatable, reviewable, and recoverable.

• Rust 1.70.0+ (for building/running from source)
• git
• docker (if using Docker steps)
• kubectl (if using Kubernetes steps)
• aws CLI credentials/profile (if using ECR)

cargo install apiforge

# Linux (x86_64 / amd64)
curl -L https://github.com/PrazwalR/Apiforge/releases/latest/download/apiforge-linux-amd64.tar.gz -o apiforge.tar.gz
tar -xzf apiforge.tar.gz
chmod +x apiforge
sudo mv apiforge /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/PrazwalR/Apiforge/releases/latest/download/apiforge-linux-arm64.tar.gz -o apiforge.tar.gz
tar -xzf apiforge.tar.gz
chmod +x apiforge
sudo mv apiforge /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/PrazwalR/Apiforge/releases/latest/download/apiforge-darwin-arm64.tar.gz -o apiforge.tar.gz
tar -xzf apiforge.tar.gz
chmod +x apiforge
sudo mv apiforge /usr/local/bin/

# macOS (Intel / amd64)
curl -L https://github.com/PrazwalR/Apiforge/releases/latest/download/apiforge-darwin-amd64.tar.gz -o apiforge.tar.gz
tar -xzf apiforge.tar.gz
chmod +x apiforge
sudo mv apiforge /usr/local/bin/

Windows artifact is published as apiforge-windows-amd64.zip.

git clone https://github.com/PrazwalR/Apiforge.git
cd Apiforge
cargo build --release --locked
./target/release/apiforge --version

apiforge init

This creates apiforge.toml with defaults.

apiforge doctor

apiforge release patch --dry-run

apiforge release patch

apiforge history --limit 20
apiforge status

Global flags:

• --config <path>: config file path (default: apiforge.toml)
• --debug: enable debug logs (APIFORGE_DEBUG=true also works)

Initializes a new config file.

apiforge init [--name my-service] [--force]

Checks:

• required tools (git, docker, kubectl, aws)
• config file parse/validation
• repository visibility/basic git status

apiforge doctor

Runs the release pipeline.

apiforge release patch \
  --dry-run \
  --skip-docker \
  --skip-k8s \
  --skip-github \
  --skip-notify \
  --no-changelog \
  --output json \
  --yes

Flags:

Rolls Kubernetes deployment image back to a target version.

apiforge rollback --to v1.2.3
apiforge rollback --to v1.2.3 --dry-run

Reads audit records from .apiforge/audit.

apiforge history --limit 50 --filter success --output text
apiforge history --output json

Shows project metadata, git HEAD/tag, and Kubernetes deployment image/replica state.

apiforge status

When you run apiforge release <bump>, step order is:

1. git-preflight
2. version-bump
3. changelog (if enabled and not skipped)
4. git-commit
5. git-tag
6. git-push
7. docker-build (if not skipped)
8. docker-push (if not skipped)
9. k8s-update (if not skipped)
10. k8s-rollout (if not skipped)
11. github-release (if configured and not skipped)
12. health-check (if configured)

On success, Apiforge can send notification(s) and records a release audit entry.

Automatic rollback is triggered when a step fails after prior steps succeeded. Rollback runs in reverse order for completed steps.

Important design choice: on git-push rollback, commit history is preserved and only release marker tags are removed.

[project]
name = "my-api"
language = "rust" # rust | node | python | go | java

[git]
main_branch = "main"
tag_format = "v{version}"
changelog = true
commit_message = "chore: release v{{ version }}"
remote = "origin"
require_clean = true
require_main_branch = true
fetch_timeout_secs = 60
push_timeout_secs = 120
operation_timeout_secs = 30

[docker]
registry = "aws_ecr" # aws_ecr | docker_hub | ghcr | custom
repository = "my-api"
dockerfile = "Dockerfile"
context = "."
tags = ["{version}", "{major}.{minor}", "latest", "{git_sha}"]
# build_args = { APP_ENV = "production" }

[kubernetes]
context = "production"
namespace = "default"
deployment = "my-api"
manifest_path = "k8s/deployment.yaml"
image_field = ".spec.template.spec.containers[0].image"
rollout_timeout = 300
min_ready_percent = 100

[aws]
region = "us-east-1"
# profile = "prod"

[github]
repository = "org/repo"
token = "${GITHUB_TOKEN}"
create_release = true
prerelease = false
draft = false

[notifications.slack]
webhook_url = "${SLACK_WEBHOOK_URL}"
message = "{{ status_emoji }} Release {{ version }} of {{ project }}: {{ status }}"
notify_on = "both" # success | failure | both

# Optional generic webhook payload
# [notifications.webhook]
# url = "https://hooks.example.com/release"
# method = "POST"
# headers = { "Authorization" = "Bearer ${WEBHOOK_TOKEN}" }
# body = "{\"project\":\"{{ project }}\",\"version\":\"{{ version }}\",\"status\":\"{{ status }}\"}"

[health_check]
url = "https://api.example.com/health"
method = "GET" # GET | POST | HEAD | PUT
expected_status = 200
# expected_body_field = "/status"
# expected_body_value = "ok"
timeout = 60
interval = 5

Docker tag placeholders supported by validation/runtime:

• {version}
• {major}
• {minor}
• {patch}
• {git_sha}
• {git_sha_full}

Slack:

Webhook:

Apiforge uses templates in multiple places. Available keys depend on context:

• {{ version }}
• {{ project }}

• {version}, {major}, {minor}, {patch}, {git_sha}, {git_sha_full}

Commonly provided:

• {{ version }}
• {{ project }}
• {{ status }}
• {{ status_emoji }}

• {{ version }}
• {{ project }}

name: Release via Apiforge

on:
  workflow_dispatch:
    inputs:
      bump:
        description: "Version bump type"
        required: true
        default: "patch"
        type: choice
        options: [patch, minor, major]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Apiforge
        run: |
          curl -L https://github.com/PrazwalR/Apiforge/releases/latest/download/apiforge-linux-amd64.tar.gz -o apiforge.tar.gz
          tar -xzf apiforge.tar.gz
          chmod +x apiforge
          sudo mv apiforge /usr/local/bin/

      - name: Run release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: apiforge release ${{ inputs.bump }} --yes

• Config validation before release execution.
• Timeout wrappers around network-prone git operations.
• Automatic rollback orchestration for completed steps.
• Sanitization of sensitive data in rendered/logged error messages.
• Audit log persistence under .apiforge/audit.

• Location: .apiforge/audit
• Retention: bounded record count
• Supports compaction and retry-aware writes

Use:

cargo audit

If advisories are intentionally suppressed due transitive ecosystem constraints, they are documented in .cargo/audit.toml.

src/
  cli.rs                 # CLI definition
  config.rs              # Config model + validation
  orchestrator/          # Pipeline execution + rollback orchestration
  steps/                 # Concrete step implementations
    git/
    docker/
    kubernetes/
    github/
    health/
  integrations/          # Service clients (git, docker, k8s, aws, github)
  audit/                 # Release history store
  output/                # CLI output rendering
  utils/                 # Helpers (semver/template/retry/sanitize/version)

cargo fmt --all -- --check
cargo test --all-features --locked
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo build --release --locked
cargo doc --no-deps --locked
cargo bench --no-run --locked
cargo audit

Your [git].tag_format is invalid. Use a format like:

tag_format = "v{version}"

Check:

1. endpoint URL and network reachability
2. method (GET/POST/HEAD/PUT)
3. expected status code
4. optional JSON pointer/value match
5. timeout/interval values

Verify:

• correct aws.region
• IAM credentials/profile
• ability to call STS/ECR

Check deployment events and image pull/access:

kubectl -n <namespace> describe deploy <name>
kubectl -n <namespace> get pods
kubectl -n <namespace> logs <pod>

• apiforge rollback currently requires explicit --to <version>; automatic rollback-target detection is not implemented yet.
• Git push rollback intentionally avoids force-rewriting remote commit history; it removes release tags instead.

See CONTRIBUTING.md.

MIT — see LICENSE.