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

Please 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.

Step 1: Initialize Your First Package Revision

Create a new package revision in Porch using the init command:

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

What this does:

Queries Porch for all PackageRevisions in the specified namespace
Displays a summary table with key information
Shows PackageRevisions from all registered repositories

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: