|
| 1 | +--- |
| 2 | +title: "Placeholder Package Revision" |
| 3 | +type: docs |
| 4 | +weight: 4 |
| 5 | +description: | |
| 6 | + The placeholder package revision tracks the most recent content of a package in its repository. This page explains its behaviour, lifecycle interactions, and how it relates to GitOps workflows. |
| 7 | +--- |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +The placeholder package revision is a special PackageRevision that Porch creates automatically as a reference to the latest released version of a package. It acts as a "branch-tracking" reference: the placeholder package revision points at the version of the package at the HEAD of the branch of the repository where the package revision is stored. |
| 12 | + |
| 13 | +**Identifying a placeholder:** |
| 14 | + |
| 15 | +| Property | Value | |
| 16 | +|----------|-------| |
| 17 | +| Revision number | `-1` | |
| 18 | +| Workspace name | The branch configured on the Repository CR (`spec.git.branch`), commonly `main` | |
| 19 | +| Naming convention | `{repository-name}.{package-name}.{branch-name}` | |
| 20 | +| Lifecycle | `Published` | |
| 21 | + |
| 22 | +There is one and only one placeholder package revision per package. |
| 23 | + |
| 24 | +## When Is It Created? |
| 25 | + |
| 26 | +The placeholder package revision is created automatically when the **first revision** of a package is published (transitions from Proposed to Published). You cannot create it manually. |
| 27 | + |
| 28 | +For example, publishing `example-repository.my-package.v1` (revision 1) will also create `example-repository.my-package.main` (revision -1) with the same content. |
| 29 | + |
| 30 | +## When Is It Updated? |
| 31 | + |
| 32 | +Each time a **new revision** of the same package is published, the placeholder is updated to reflect that revision's content and tasks. |
| 33 | + |
| 34 | +For example: |
| 35 | +1. Publish v1 (revision 1): placeholder is **created** with v1's content |
| 36 | +2. Publish v2 (revision 2): placeholder is **updated** with v2's content |
| 37 | + |
| 38 | +The placeholder **only moves forward** on each explicit publish operations. |
| 39 | + |
| 40 | +## What Happens When the Latest Package Revision Is Deleted? |
| 41 | + |
| 42 | +Deleting the latest published package revision does **not** cause the placeholder to roll back to a previous revision. The placeholder retains the content it had at the time of the last publish. It still refers to the version of the Package Revision at the HEAD of the branch in git. |
| 43 | + |
| 44 | +This is intentional. Consider the scenario: |
| 45 | + |
| 46 | +1. v1 is published (placeholder reflects v1) |
| 47 | +2. v2 is published (placeholder reflects v2) |
| 48 | +3. v2 is deleted |
| 49 | + |
| 50 | +After step 3, the placeholder **still reflects v2's content**. It does not fall back to v1. |
| 51 | + |
| 52 | +**This occurs because** the deletion of a PackageRevision in Porch: |
| 53 | + |
| 54 | +- Removes the tag/branch reference from Git |
| 55 | +- Removes the Porch metadata |
| 56 | + |
| 57 | +However, it does **not** perform a `git revert` on the tracked branch. The actual content on that branch in Git is unchanged. The placeholder remains consistent with the real Git state. |
| 58 | + |
| 59 | +## How to Roll Back a Package |
| 60 | + |
| 61 | +Since the placeholder only moves forward, the intended way to "roll back" is to publish a new revision with the desired content: |
| 62 | + |
| 63 | +1. Copy the older revision to create a new draft: |
| 64 | + |
| 65 | + ```bash |
| 66 | + porchctl rpkg copy example-repository.my-package.v1 \ |
| 67 | + --namespace=default --workspace=v3 |
| 68 | + ``` |
| 69 | + |
| 70 | +2. Propose and approve it: |
| 71 | + |
| 72 | + ```bash |
| 73 | + porchctl rpkg propose example-repository.my-package.v3 --namespace=default |
| 74 | + porchctl rpkg approve example-repository.my-package.v3 --namespace=default |
| 75 | + ``` |
| 76 | + |
| 77 | +3. The placeholder now reflects v3 (which has v1's content) |
| 78 | + |
| 79 | +This preserves linear Git history and makes the intent **explicit**. |
| 80 | + |
| 81 | +## Relationship to GitOps |
| 82 | + |
| 83 | +In a GitOps workflow, a reconciler (such as Flux or ArgoCD) watches a branch in Git for changes. The placeholder package revision references this branch. |
| 84 | + |
| 85 | +The branch is configured via `spec.git.branch` on the Repository CR. This is commonly `main` but can be any branch name (e.g. `production`, `release`, `staging`). The placeholder's workspace name will match whatever branch is configured. |
| 86 | + |
| 87 | +Because the placeholder mirrors the real state of that branch: |
| 88 | + |
| 89 | +- What the reconciler sees in Git is what the placeholder represents in Porch |
| 90 | +- There is no divergence between Porch's view and the deployed state |
| 91 | +- Deleting a PackageRevision in Porch does not cause unexpected changes in the deployed environment |
| 92 | + |
| 93 | +## Can the Placeholder Be Deleted? |
| 94 | + |
| 95 | +Yes. The placeholder is **not immutable**. It can be deleted via `porchctl` like any other PackageRevision. This is useful during package cleanup (e.g. removing a package entirely from a repository). |
| 96 | + |
| 97 | +Deleting the placeholder **removes the package content from the configured Git branch**. A commit is made to the branch (e.g. `main`) that deletes the package directory and its files. This means any GitOps reconciler watching that branch will also see the removal. |
| 98 | + |
| 99 | +## Summary |
| 100 | + |
| 101 | +| Action | Effect on Placeholder | |
| 102 | +|--------|----------------------| |
| 103 | +| First revision published | Placeholder **created** | |
| 104 | +| Subsequent revision published | Placeholder **updated** to new content | |
| 105 | +| Published revision deleted | Placeholder **unchanged** (no rollback) | |
| 106 | +| Placeholder itself deleted | Removed from Porch and content deleted from Git branch | |
| 107 | +| New revision published after placeholder deletion | Placeholder **recreated** with contents of the new revision | |
| 108 | + |
| 109 | +## Restrictions |
| 110 | + |
| 111 | +The placeholder cannot be used as a source for certain operations: |
| 112 | + |
| 113 | +- **Clone**: cannot clone from a placeholder |
| 114 | +- **Edit/Copy**: cannot edit or copy a placeholder |
| 115 | +- **Upgrade**: cannot upgrade a placeholder or use a placeholder as the target upstream of an upgrade |
| 116 | + |
| 117 | +These operations require a specific published revision with a concrete revision number. |
0 commit comments