Getting Package Revisions

A guide to getting/listing, reading, querying, and inspecting package revisions in Porch

Prerequisites

Porch deployed on a Kubernetes cluster Setup Porch Guide.
Porchctl CLI tool installed Setup Porchctl Guide.
A Git repository registered with Porch Setup Repositories Guide.
Kubectl configured to access your cluster.

Understanding Terminology

In Porch, you work with PackageRevisions - there is no separate “Package” resource. When we say “package” colloquially, we’re referring to a PackageRevision. The rpkg command stands for “revision package”.

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:

porchctl rpkg list --namespace default

Example output:

NAME                             PACKAGE            WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
porch-test.my-app.v1             my-app             v1              1          true     Published   porch-test
porch-test.my-app.v2             my-app             v2              0          false    Draft       porch-test
blueprints.nginx.main            nginx              main            5          true     Published   blueprints
blueprints.postgres.v1           postgres           v1              0          false    Proposed    blueprints

Understanding the output:

NAME: Full package revision identifier following the pattern repository.([pathnode.]*)package.workspace
- Format: <repository>.[<path-nodes>.]<package>.<workspace>
- Example: porch-test.basedir.subdir.edge-function.v1
  - Repository: porch-test
  - Path: basedir/subdir (directory structure)
  - Package: edge-function
  - Workspace: v1
- Simple example: blueprints.nginx.main (no path nodes)
  - Repository: blueprints
  - Package: nginx
  - Workspace: main
PACKAGE: Package name with directory path if not in repository root
- Example: basedir/subdir/network-function shows location in repository
WORKSPACENAME: User-selected identifier for this PackageRevision
- Scoped to the package - v1 in package A is independent from v1 in package B
- Maps to Git branch or tag name
REVISION: Version number indicating publication status
- 1+: Published PackageRevisions (increments with each publish: 1, 2, 3…)
- 0: Unpublished PackageRevisions (Draft or Proposed)
- -1: Placeholder PackageRevisions pointing to Git branch/tag head
LATEST: Whether this is the latest published PackageRevision
- Only one PackageRevision per package marked as latest
- Based on highest revision number
LIFECYCLE: Current state of the PackageRevision
- Draft: Work-in-progress, freely editable, visible to authors
- Proposed: Read-only, awaiting approval, can be approved or rejected
- Published: Immutable, production-ready, assigned revision numbers
- DeletionProposed: Marked for removal, awaiting deletion approval
REPOSITORY: Source repository name

Get Detailed PackageRevision Information

Get complete details about a specific PackageRevision:

porchctl rpkg get porch-test.my-app.v1 --namespace default -o yaml

What this does:

Retrieves the full PackageRevision resource
Shows all metadata, spec, and status fields
Displays in YAML format for easy reading

Example output:

apiVersion: porch.kpt.dev/v1alpha1
kind: PackageRevision
metadata:
  creationTimestamp: "2025-11-24T13:00:14Z"
  labels:
    kpt.dev/latest-revision: "true"
  name: porch-test.my-first-package.v1
  namespace: default
  resourceVersion: 5778e0e3e9a92d248fec770cef5baf142958aa54
  uid: f9f6507d-20fc-5319-97b2-6b8050c4f9cc
spec:
  lifecycle: Published
  packageName: my-first-package
  repository: porch-test
  revision: 1
  tasks:
  - init:
      description: My first Porch package
    type: init
  workspaceName: v1
status:
  publishTimestamp: "2025-11-24T16:38:41Z"
  upstreamLock: {}

Key fields to inspect:

spec.lifecycle: Current PackageRevision state
spec.tasks: History of operations performed on this PackageRevision
status.publishTimestamp: When the PackageRevision was published

Tip

Use jq to extract specific fields: porchctl rpkg get <name> -n default -o json | jq '.metadata'

Reading PackageRevision Resources

Read the actual contents of a PackageRevision:

porchctl rpkg read porch-test.my-first-package.v1 --namespace default

What this does:

Fetches PackageRevision resources and outputs to stdout
Shows all KRM resources in ResourceList format
Displays the complete PackageRevision contents

Example output:

apiVersion: config.kubernetes.io/v1
kind: ResourceList
items:
- apiVersion: ""
  kind: KptRevisionMetadata
  metadata:
    name: porch-test.my-first-package.v1
    namespace: default
    creationTimestamp: "2025-11-24T13:00:14Z"
    resourceVersion: 5778e0e3e9a92d248fec770cef5baf142958aa54
    uid: f9f6507d-20fc-5319-97b2-6b8050c4f9cc
    annotations:
      config.kubernetes.io/path: '.KptRevisionMetadata'
- apiVersion: kpt.dev/v1
  kind: Kptfile
  metadata:
    name: my-first-package
    annotations:
      config.kubernetes.io/local-config: "true"
      config.kubernetes.io/path: 'Kptfile'
  info:
    description: My first Porch package
  pipeline:
    mutators:
    - image: gcr.io/kpt-fn/set-namespace:v0.4.1
      configMap:
        namespace: production
- apiVersion: v1
  kind: ConfigMap
  metadata:
    name: kptfile.kpt.dev
    annotations:
      config.kubernetes.io/local-config: "true"
      config.kubernetes.io/path: 'package-context.yaml'
  data:
    name: example
- apiVersion: v1
  kind: ConfigMap
  metadata:
    name: test-config
    namespace: production
    annotations:
      config.kubernetes.io/path: 'test-config.yaml'
  data:
    Key: "Value"

Advanced Filtering

Porch provides multiple ways to filter PackageRevisions. You can either use porchctl’s built-in flags, Kubernetes label selectors, or field selectors depending on your needs.

Using Porchctl Flags

Filter PackageRevisions using built-in porchctl flags:

Filter by package name (substring match):

porchctl rpkg get --namespace default --name my-app

Filter by revision number (exact match):

porchctl rpkg get --namespace default --revision 1

Filter by workspace name:

porchctl rpkg get --namespace default --workspace v1

Example output:

$ porchctl rpkg get --namespace default --name network-function
NAME                                    PACKAGE            WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
porch-test.network-function.v1          network-function   v1              1          false    Published   porch-test
porch-test.network-function.v2          network-function   v2              2          true     Published   porch-test
porch-test.network-function.main        network-function   main            0          false    Draft       porch-test

Using Kubectl Label Selectors

Filter using Kubernetes labels with the --selector flag:

Get all “latest” published PackageRevisions:

kubectl get packagerevisions -n default --selector 'kpt.dev/latest-revision=true'

Example output:

$ kubectl get packagerevisions -n default --show-labels --selector 'kpt.dev/latest-revision=true'
NAME                        PACKAGE   WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY        LABELS
porch-test.my-app.v2        my-app    v2              2          true     Published   porch-test        kpt.dev/latest-revision=true
blueprints.nginx.main       nginx     main            5          true     Published   blueprints        kpt.dev/latest-revision=true

Note

PackageRevision resources have limited labels. To filter by repository, package name, or other attributes, use --field-selector instead (see next section).

Using Kubectl Field Selectors

Filter using PackageRevision fields with the --field-selector flag:

Supported fields:

metadata.name
metadata.namespace
spec.revision
spec.packageName
spec.repository
spec.workspaceName
spec.lifecycle

Filter by repository:

kubectl get packagerevisions -n default --field-selector 'spec.repository==porch-test'

Filter by lifecycle:

kubectl get packagerevisions -n default --field-selector 'spec.lifecycle==Published'

Filter by package name:

kubectl get packagerevisions -n default --field-selector 'spec.packageName==my-app'

Combine multiple filters:

kubectl get packagerevisions -n default \
  --field-selector 'spec.repository==porch-test,spec.lifecycle==Published'

Example output:

$ kubectl get packagerevisions -n default --field-selector 'spec.repository==porch-test'
NAME                             PACKAGE            WORKSPACENAME   REVISION   LATEST   LIFECYCLE   REPOSITORY
porch-test.my-app.v1             my-app             v1              1          false    Published   porch-test
porch-test.my-app.v2             my-app             v2              2          true     Published   porch-test
porch-test.my-service.main       my-service         main            3          true     Published   porch-test

Note

The --field-selector flag supports only the = and == operators. The != operator is not supported due to Porch’s internal caching behavior.

Additional Operations

Beyond basic listing and filtering, these operations help you monitor changes and format output.

Watch for PackageRevision Changes

Monitor PackageRevisions in real-time:

kubectl get packagerevisions -n default --watch

Sort by Creation Time

Find recently created PackageRevisions:

kubectl get packagerevisions -n default --sort-by=.metadata.creationTimestamp

Output Formatting

Both porchctl and kubectl support standard Kubernetes output formatting flags:

-o yaml - YAML format
-o json - JSON format
-o wide - Additional columns
-o name - Resource names only
-o custom-columns=... - Custom column output

Note

For a complete reference of all available command options and flags, see the Porch CLI Guide.

Troubleshooting

No PackageRevisions shown?

Verify repositories are registered and healthy (see Repository Management Guide)
Ensure PackageRevisions exist in the Git repository

Permission denied errors?

Check RBAC permissions: kubectl auth can-i get packagerevisions -n default
Verify service account has proper roles

PackageRevision not found?

Confirm the exact PackageRevision name: porchctl rpkg get --namespace default
Check you’re using the correct namespace
Verify the PackageRevision hasn’t been deleted

Key Concepts

PackageRevision: The Kubernetes resource managed by Porch (there is no separate “Package” resource)
Namespace: Kubernetes namespace where PackageRevisions are managed
Repository: Git repository containing PackageRevision sources
Lifecycle: Current state of the PackageRevision (Draft, Proposed, Published, DeletionProposed)
Workspace: Unique identifier for a PackageRevision within a package (maps to Git branch/tag)
Latest: Flag indicating the most recent published PackageRevision of a package
Path nodes: Directory structure within repository where PackageRevision is located
Revision Number: 0 for Draft/Proposed, 1+ for Published (increments with each publication)