Version Management

The ProductifyFW CLI provides comprehensive version management for your projects, integrating with CI/CD pipelines and application deployments.

Overview

Version management in the CLI:

• Project Version: Stored in project.yaml, used in CI/CD for Docker image tagging
• Application Version: Synced with backend applications, managed through copy/promote operations
• Semantic Versioning: Full support for major.minor.patch versioning

Binary version vs. project version

pfy version manages your project's version in project.yaml — it never reports the version of the CLI binary itself. To print the binary's own version, use the global pfy --version flag instead.

Commands

pfy version show

Display the current project version from project.yaml.

pfy version show
# Output: 1.2.3

pfy version set

Set the project version to a specific value.

pfy version set --version 2.0.0
# Output: Version updated: 1.2.3 → 2.0.0

Flags:

• --version: Version string in format major.minor.patch (required)

pfy version bump

Increment the project version using semantic versioning.

# Increment patch version (1.2.3 → 1.2.4)
pfy version bump --part patch

# Increment minor version (1.2.3 → 1.3.0)
pfy version bump --part minor

# Increment major version (1.2.3 → 2.0.0)
pfy version bump --part major

Flags:

• --part: Version part to increment: major, minor, or patch (default: patch)
• --pre: Pre-release label to append (e.g., --pre rc produces 1.3.0-rc.1)

Behavior:

• Patch: Increments patch number, keeps major and minor
• Minor: Increments minor number, resets patch to 0
• Major: Increments major number, resets minor and patch to 0
• Bumping a version that carries a pre-release identifier strips the identifier (standard semver behavior)

Version in CI/CD

The project version from project.yaml is automatically used in CI/CD templates for Docker image tagging.

GitHub Actions

# Generated CI file includes version tag
tags: |
  ghcr.io/my-app:1.2.3 # From project.yaml
  ghcr.io/my-app:latest

GitLab CI

# GitLab CI builds with version tag
script:
  - docker build -t $IMAGE_NAME:1.2.3 . # From project.yaml
  - docker push $IMAGE_NAME:1.2.3
  - docker push $IMAGE_NAME:latest

Application Version Integration

When copying or promoting applications, the CLI can sync versions with the backend.

Promote with Version

# Use version from project.yaml
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug <slug>

# Specify version explicitly
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug <slug> \
  --version 2.1.0

# Update project.yaml with promoted version (default: true)
pfy application promote \
  --application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug <slug> \
  --version 2.1.0 \
  --update-version

Flags:

• --slug: Application slug in the target tenant (required; not defaulted from the source)
• --version: Version to promote (defaults to project.yaml version)
• --update-version: Update project.yaml with result (default: true)

Copy with Version

# Copy using project.yaml version
pfy application copy \
  --source-application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug new-app

# Specify version for copy
pfy application copy \
  --source-application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug new-app \
  --version 1.5.0

# Update project.yaml after copy
pfy application copy \
  --source-application-id <id> \
  --target-tenant-id <tenant-id> \
  --slug new-app \
  --update-version

Flags:

• --version: Version for copied application (defaults to project.yaml or source version)
• --update-version: Update project.yaml with result (default: false)

Sync from Manager

Pull project configuration from the manager backend.

pfy sync --project-id <project-id>

This command:

1. Fetches project details from manager
2. Updates project.yaml with project ID, name, version, and known environments
3. Preserves existing CI/CD settings

Use Case: Initialize local project.yaml from an existing manager project.

Workflows

Release Workflow

# 1. Bump version for release
pfy version bump --part minor
# Version updated: 1.2.3 → 1.3.0

# 2. Generate updated CI/CD files
pfy ci update
# Creates workflows with version 1.3.0

# 3. Commit and tag
git add project.yaml .github/
git commit -m "Release v1.3.0"
git tag v1.3.0
git push origin main --tags

# 4. CI builds and pushes:
#    - my-app:1.3.0 (version tag)
#    - my-app:latest

Environment Promotion

# 1. Test in staging (tenant_staging)
pfy application create \
  --tenant-id tenant_staging \
  --slug my-app \
  --name "My App" \
  --version 1.2.3

# 2. After testing, promote to production
pfy version bump --part patch  # 1.2.3 → 1.2.4
pfy application promote \
  --application-id app_staging_123 \
  --target-tenant-id tenant_prod \
  --slug web-app \
  --update-version

# project.yaml now has version 1.2.4
# Application in production has version 1.2.4

Multi-Environment Deployment

# Update version in project.yaml
pfy version set --version 2.0.0

# Deploy to multiple environments
for env in dev staging prod; do
  pfy application promote \
    --application-id $APP_ID \
    --target-tenant-id tenant_${env} \
    --slug web-app \
    --update-version=false  # Don't update project.yaml each time
done

Version Format

Versions must follow semantic versioning 2.0.0:

• Format: major.minor.patch with optional -prerelease and +build identifiers
• Example: 1.2.3
• Major: Breaking changes
• Minor: New features, backwards compatible
• Patch: Bug fixes, backwards compatible

Invalid versions:

pfy version set --version 1.2       # [NO] Missing patch
pfy version set --version v1.2.3    # [NO] No 'v' prefix

Valid versions:

pfy version set --version 0.1.0      # [OK] Initial development
pfy version set --version 1.0.0      # [OK] First stable
pfy version set --version 1.3.0-rc.1 # [OK] Pre-release
pfy version set --version 2.15.7     # [OK] Any valid semver

Configuration

Version is stored in project.yaml:

project_name: my-app
version: 1.2.3 # ← Project version
ci:
  type: github
  language: go
  registry: ghcr.io
  image_name: my-app

Best Practices

1. Bump Before Release

Always increment version before creating a release:

pfy version bump --part minor
git commit -am "Bump version to $(pfy version show)"
git tag "v$(pfy version show)"
git push --tags

2. Match Git Tags

Keep git tags in sync with project version:

# Good: tag matches version
pfy version show  # 1.2.3
git tag v1.2.3

# Bad: tag doesn't match
pfy version show  # 1.2.3
git tag v1.2.4    # Mismatch!

3. Automate in CI

Add version bumping to your CI pipeline:

# .github/workflows/release.yml
- name: Bump version
  run: |
    pfy version bump --part patch
    git config user.name "CI Bot"
    git config user.email "ci@example.com"
    git commit -am "Bump version [skip ci]"
    git push

4. Environment-Specific Versions

Environments in project.yaml do not carry their own version field — the deployed version lives on the application in each tenant. Use the description field to note what each environment runs:

# project.yaml
version: 1.2.3 # Project version

environments:
  staging:
    tenant_id: "tenant_def"
    application_id: "app_uvw"
    description: "Staging, currently on 1.3.0-rc.1"
  production:
    tenant_id: "tenant_abc"
    application_id: "app_xyz"
    description: "Production stable"

Troubleshooting

Version not updating in CI

Regenerate CI templates after version bump:

pfy version bump --part minor
pfy ci update  # Regenerate with new version

Version mismatch between project.yaml and application

Sync application version:

# Get current project version
VERSION=$(pfy version show)

# Update application
pfy application update-version \
  --application-id <id> \
  --version $VERSION

Lost version after git operations

Always commit project.yaml changes:

git add project.yaml
git commit -m "Update version to $(pfy version show)"

See Also

• Project Configuration - Full project.yaml reference
• CI/CD Commands - CI template generation
• Application Commands - Application management