Working with Package Revisions on Porch Documentation

Creating Package Revisions

Mon, 01 Jan 0001 00:00:00 +0000

Tutorial Overview

You will learn how to:

Initialize a new package revision
Pull the package revision locally
Modify the package revision contents
Push changes back to Porch
Propose the package revision for review
Approve or reject the package revision

Note

The tutorial assumes a porch repository is initialized with the “porch-test” name. We recommended to use this for simpler copy-pasting of commands otherwise replace any “porch-test” value with your repository’s name in the below commands.

Getting Package Revisions

Mon, 01 Jan 0001 00:00:00 +0000

Basic Operations

These operations cover the fundamental commands for viewing and inspecting package revisions in Porch.

Getting All Package Revisions

Get all package revisions across all repositories in a namespace:

porchctl rpkg get --namespace default

This command queries Porch for all PackageRevisions in the specified namespace and displays a summary table with key information. It shows PackageRevisions from all registered repositories in that namespace.

Note

porchctl rpkg list is an alias for porchctl rpkg get and can be used interchangeably:

Copying Package Revisions

Mon, 01 Jan 0001 00:00:00 +0000

Tutorial Overview

You will learn how to:

Find a PackageRevision to copy
Copy a PackageRevision to create a new revision
Modify the copied PackageRevision
Propose and approve the new revision

Note

The tutorial assumes a porch repository is initialized with the “porch-test” name. We recommended to use this for simpler copy pasting of commands otherwise replace any “porch-test” value with your repository’s name in the below commands.

Key Concepts

Copy: Creates a new independent PackageRevision within the same repository
Source PackageRevision: The original PackageRevision being copied
Target PackageRevision: The new PackageRevision created by the copy operation
Workspace: Must be unique within the package for the target
Same-repository operation: Copy only works within a single repository
Immutability: Published PackageRevisions cannot be modified, only copied
Clone vs Copy: Use clone for cross-repository operations, copy for same-repository versions

Understanding Copy Operations

Copying creates a new PackageRevision based on an existing one within the same repository. The copied PackageRevision is completely independent with no upstream link to the source.

Cloning Package Revisions

Mon, 01 Jan 0001 00:00:00 +0000

Tutorial Overview

You will learn how to:

Find a PackageRevision to clone
Clone a PackageRevision to a different repository
Modify the cloned PackageRevision
Propose and approve the new revision

Note

Please note the tutorial assumes repositories are initialized with the “blueprints” and “deployments” names. We recommended to use these for simpler copy pasting of commands otherwise replace these values with your repository names in the below commands.

Understanding Clone Operations

Cloning creates a new PackageRevision based on an existing one and works across different repositories. The cloned PackageRevision maintains an upstream reference to its source, allowing it to receive updates.

Upgrading Package Revisions

Mon, 01 Jan 0001 00:00:00 +0000

The package upgrade feature in Porch is a powerful mechanism for keeping deployed packages (downstream) up-to-date with their source blueprints (upstream). This guide walks through the entire workflow, from creating packages to performing an upgrade, with a special focus on the different upgrade scenarios and merge strategies.

For detailed command reference, see the porchctl CLI guide.

Key Concepts

To understand the upgrade process, it’s essential to be familiar with the three states of a package during a merge operation:

Deleting Package Revisions

Mon, 01 Jan 0001 00:00:00 +0000

Tutorial Overview

You will learn how to:

Delete Draft and Proposed PackageRevisions directly
Propose Published PackageRevisions for deletion
Approve or reject deletion proposals
Understand the deletion workflow and safety mechanisms

Note

This tutorial assumes a porch repository is initialized with the “porch-test” name. Replace any “porch-test” value with your repository’s name in the commands below.

Understanding PackageRevision Deletion

PackageRevision deletion in Porch follows different workflows depending on the lifecycle state:

Direct Deletion:

Working with Subpackages

Mon, 01 Jan 0001 00:00:00 +0000

Independent subpackages allow you to compose a single package from multiple upstream sources, where each subpackage can be cloned and upgraded independently. This guide walks through the complete workflow of adding an independent subpackage to an existing package and then upgrading it when a new upstream version becomes available.

For the conceptual overview, see Subpackages. For detailed command reference, see the porchctl CLI guide.

Key Concepts

Independent subpackage: A kpt package nested in a subdirectory of a parent package that maintains its own upstream tracking via its Kptfile. See the kpt package documentation for a full description of independent subpackages
Parent package revision: The Draft package revision into which subpackages are cloned or upgraded.
Subpackage directory: The relative path within the parent package where the subpackage resides.

Unlike a regular clone (which creates a new package revision), a subpackage clone adds content into an existing Draft package revision. Similarly, a subpackage upgrade modifies the parent package revision in-place rather than creating a new one.