Version Management

pfy deals with two versions: the project version in project.yaml (pfy version), and the application version stored on the Manager (pfy application update-version). The project version also reaches generated CI pipelines and Nomad image tags.

Overview

• Project version: the version: key in project.yaml. pfy version show|set|bump manage it. pfy nomad deploy --use-project-version uses it as the image tag, and pfy ci update bakes it into Node.js pipelines.
• Application version: a field on each application in the Manager. Push the project version to it with pfy application update-version, or set it when copying with pfy application copy --version.
• Format: semantic versioning 2.0.0: major.minor.patch, with an optional -prerelease suffix.

Binary version vs. project version

pfy version manages the 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: the new version string (required)

version set writes the value as given and does not validate it. A malformed value (1.2, v1.2.3) is saved and only rejected later, by the next pfy version bump. Check what you pass.

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 attach or advance (--part minor --pre rc turns 1.2.3 into 1.3.0-rc.1; running it again gives 1.3.0-rc.2). Omit it to cut a normal release.

Behavior:

• patch increments the patch number and keeps major and minor
• minor increments the minor number and resets patch to 0
• major increments the major number and resets minor and patch to 0
• A bump without --pre drops any pre-release or build suffix. If the current version is a pre-release of the part you bump, the bump releases it instead of skipping ahead: 1.3.0-rc.1 + --part patch gives 1.3.0, not 1.3.1 (semver orders 1.3.0-rc.1 < 1.3.0). Bumping a more significant part advances normally: 1.3.0-rc.1 + --part minor gives 1.4.0.
• Build metadata (+build) is accepted on input but never carried forward.

Version in CI/CD

pfy ci update copies the project version into the generated pipeline for Node.js projects only. The Node.js pipelines build an image tagged with the version that was in project.yaml when you ran pfy ci update, and on main they bump the patch version themselves before pushing. Go pipelines do not build Docker images or touch the version; a Go release is cut by GoReleaser when you push a v* tag. See ci and Auto-Versioning.

GitHub Actions (Node.js)

# build-and-scan job — the version is baked in when the file is generated
tags: ghcr.io/my-app:1.2.3

GitLab CI (Node.js)

# build job
script:
  - docker build -t $IMAGE_NAME:1.2.3 .

Because the value is baked in, re-run pfy ci update after changing the version by hand, or the build job keeps tagging the old version.

Application Version Integration

When copying applications or updating an application's version, the CLI can sync versions with the backend.

pfy application promote is a deprecated stub that always refuses. Use pfy application enable for per-tenant access, pfy application config-copy for per-tenant configuration, and pfy application update-version to move the version; see application.

Update an application's version

# Push the project.yaml version to the Manager after a release
pfy application update-version \
  --app my-app \
  --project my-saas \
  --version $(pfy version show)

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 <slug-or-id>

This command:

1. Fetches project details from manager
2. Updates project.yaml with the project ID and name, and seeds one environment alias per tenant of the project
3. Preserves existing CI/CD settings and does not touch version

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. (Node.js projects) regenerate the CI files so the build job tags 1.3.0
pfy ci update

# 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 (Node.js pipelines):
#    - my-app:1.3.0 (version tag)
#    - my-app:latest
#    Go pipelines run GoReleaser on the tag instead.

Tenant Rollout

# 1. Create the application once, at the project level
pfy application create \
  --project my-saas \
  --slug my-app \
  --name "My App" \
  --version 1.2.3

# 2. Enable it for the staging tenant and test there
pfy application enable --app my-app --tenant staging --project my-saas

# 3. After testing, bump and push the new version
pfy version bump --part patch  # 1.2.3 → 1.2.4
pfy application update-version --app my-app --project my-saas --version $(pfy version show)

# 4. Enable for production
pfy application enable --app my-app --tenant prod --project my-saas

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 (accepted by version set, but the next version bump fails with invalid version format):

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 (the generated Node.js pipeline already does this; add it yourself for Go):

# .github/workflows/ci.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 image tag is chosen at deploy time (--tag or --use-project-version), and the application's own version field lives on the Manager. Use the alias's 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

Node.js pipelines bake the version into the build job when the file is generated. Regenerate after a manual bump:

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

Go pipelines never use the project version; tag the release in git instead.

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