recipe-maintainer/.claude/commands/recipe-upgrade-apply.md

---
description: Execute a planned recipe upgrade — apply changes, deploy, test, commit/tag
argument-hint: <recipe-name>
allowed-tools: [Bash, Read, Write, Glob, Grep, WebFetch, WebSearch]
---

# Recipe Upgrade Apply

Execute a previously planned upgrade for a Co-op Cloud recipe. Reads the plan file, applies the changes, deploys to the test instance, runs tests, and commits/tags if everything passes.

The recipe name is: $ARGUMENTS

Read and follow the instructions in `.claude/commands/includes/logging.md`.
Read and follow the instructions in `.claude/commands/includes/guidelines.md`.

## Steps

1. **Get the domain and server for this recipe**:
   ```
   python3 scripts/get_test_instance.py --recipe $ARGUMENTS
   ```
   This outputs DOMAIN and SERVER for the active instance.
   - If the recipe has no `recipe-info/$ARGUMENTS/recipe.toml`, tell the user to run `/recipe-init $ARGUMENTS` first and stop.

2. **Find and read the upgrade plan** — look for the most recent plan file matching `plans/$ARGUMENTS-upgrade-*.md`.
   - If no plan file exists, tell the user to run `/recipe-upgrade-plan $ARGUMENTS` first and stop.
   - Read the plan file to get the image tag changes, version bump, recipe changes, risks, and deployment notes.

3. **Present the plan summary** to the user:
   - Image tag changes (service / current → new)
   - Recipe version bump
   - Risks and caveats
   - Any post-deploy steps

4. **Apply the upgrades** — update image tags in the local recipe checkout:
   ```
   abra recipe upgrade $ARGUMENTS -n
   ```
   - If the plan specifies manual tag changes (tags that `abra recipe upgrade` won't handle), apply those by editing `~/.abra/recipes/$ARGUMENTS/compose.yml` directly.

5. **Do NOT bump the recipe version label here — record the recommended release bump instead.** The
   `coop-cloud.${STACK_NAME}.version` label is **not** changed in this PR. The version bump + tag + publish
   all happen at the very end, after the upstream PR merges, via a single real `abra recipe release`
   command (see `/recipe-upstream`). All this step does is **decide and record the semver bump** so that
   command is ready:
   - Pick the bump from the upgrade's nature per the plan: `-x` (major) for breaking changes, `-y` (minor)
     for a new feature, `-z` (patch) for a patch/security bump.
   - Record the recommended release command — `abra recipe release $ARGUMENTS -x|-y|-z` (no `--dry-run`) —
     for the PR body (step 12). `/recipe-upstream` reads this line back out of the PR to drive the publish.
   - Leave the version label as-is. (`abra recipe release` at release time computes the final
     `a.b.c+x.y.z` from the current label + the flag + the app image tag, and syncs the label then.)
   - Note the current version + the recommended bump for the report.

6. **Apply any additional recipe changes** noted in the plan:
   - New env vars, changed config templates, new volumes, updated labels, added/removed services, etc.
   - Only make changes that are documented in the plan file.

7. **Lint the upgraded recipe**:
   ```
   abra recipe lint $ARGUMENTS -C
   ```
   - If lint errors are found, report them and attempt to fix obvious issues. If unfixable, warn the user and continue.

8. **Deploy the upgraded recipe** — follow the same process as `/recipe-deploy $ARGUMENTS`:
   ```
   abra app deploy <DOMAIN> --chaos --force --no-input
   ```
   - If the plan mentioned post-upgrade migration commands, run them after deployment.

9. **Run the test suite** — follow the same process as `/recipe-test $ARGUMENTS`:
   - Discover and run all test scripts from `recipe-info/$ARGUMENTS/tests/*.py`.
   - Read `recipe-info/$ARGUMENTS/test.md` and perform URL-based manual checks using `curl` or `WebFetch`.
   - If no test directory exists, do a basic health check by curling `https://<DOMAIN>` and checking for HTTP 200.

10. **Write an upgrade report** for future reference:
    - Create the `planned-updates/` directory if it doesn't already exist.
    - Write to `planned-updates/$ARGUMENTS-upgrade-<YYYY-MM-DD>.md` (using today's date).
    - Include:
      - Current recipe version + the recommended release bump (e.g. `1.0.2+5.8.3`, bump `-y` minor →
        published as `abra recipe release` at release time)
      - Which image tags were upgraded per service
      - Changelog summary with links to full release notes
      - Any **Operator Action Required** items
      - Lint results
      - Test results (PASS/FAIL for each test)
      - Any manual steps still needed
    - Tell the user the file path.

11. **Commit the upgrade** (only if all tests passed):
    - `cd ~/.abra/recipes/$ARGUMENTS`
    - Stage the changed files: `git add compose.yml` (and any other modified recipe files).
    - Commit the image-tag/config changes — e.g. `git commit -m "chore: upgrade <service> to <new-tag>"`.
      Do **not** mention a recipe version in the message: the version label is not bumped here, and the
      branch name is derived from the commit (see `/recipe-create-pr`).
    - Do **NOT** create a tag or bump the version label. The tag + version bump + publish are done at the
      end by `abra recipe release` (see `/recipe-upstream`), after the upstream PR merges.
    - If any tests failed, skip this step entirely.

12. **Open a review PR on git.autonomic.zone** (only if step 11 ran):
    - Before following the `/recipe-create-pr $ARGUMENTS` steps, construct the PR body and export it as `RECIPE_PR_BODY`. Use this format (fill in real values):

      ```markdown
      Upgrade `<recipe>` image tags (current recipe version `<current-version>`).

      ## Image tag changes

      | Service | Old tag | New tag |
      |---------|---------|---------|
      | app | 1.0.0 | 1.1.0 |

      ## Upstream release notes

      **<service> <old>→<new>:** <url>
      <!-- one line per upgraded image/service; pull each URL from recipe-info/<recipe>/upstream.md
           (between the current → new version). These links MUST be in the PR body itself, not just
           the report — so a reviewer sees exactly what changed upstream. -->

      ## Test results

      | Test | Result |
      |------|--------|
      | `tests/test_foo.py` | ✓ PASS |
      | URL `https://<domain>` | ✓ PASS |

      ## Recommended release bump

      This PR does **not** bump the `coop-cloud.${STACK_NAME}.version` label. After the upstream PR
      merges, publish the release (which bumps the label + tags + pushes) with:

          abra recipe release <recipe> -<x|y|z>

      <!-- pick -x major / -y minor / -z patch per the upgrade; /recipe-upstream reads this line. -->

      ## Next steps (after PR review)

      ```bash
      # 1. Review the PR on git.autonomic.zone:
      #    <gitea-pr-url>

      # 2. Pull the PR branch to your local dev machine:
      cd ~/.abra/recipes/<recipe>
      git fetch git@git.autonomic.zone:recipe-maintainers/<recipe>.git <branch>:<branch>
      git checkout <branch>

      # 3. Push to your upstream fork:
      git push dev HEAD:<branch>

      # 4. Open a PR on upstream and merge it:
      #    https://git.coopcloud.tech/coop-cloud/<recipe>/pulls

      # 5. After the upstream PR merges, publish the release (bumps the version label,
      #    commits, tags AND pushes the tag — all in one step):
      abra recipe release <recipe> -<x|y|z>
      ```
      ```

    - Then follow the same process as `/recipe-create-pr $ARGUMENTS` (read that skill file). The recipe-create-pr script will use `RECIPE_PR_BODY` as the PR body when that variable is set.
    - Capture the resulting PR URL — you'll include it in the summary.
    - If the PR creation fails, do not block: report the error and tell the user they can run `/recipe-create-pr $ARGUMENTS` manually after fixing.

13. **Summarise**:
    - The current recipe version + the recommended release bump (e.g. `1.0.2+5.8.3`, bump `-y` minor).
    - Which image tags were upgraded per service (old → new).
    - Whether the deployment succeeded.
    - Test results — all passed, or which failed with details.
    - If any tests failed: highlight failures, suggest troubleshooting, and note the recipe can be rolled back by re-fetching (`abra recipe fetch $ARGUMENTS --force`).
    - Any manual actions still required (from the plan).
    - The git.autonomic.zone review PR URL from step 12 (or note that PR creation failed and how to retry).
    - If all tests passed AND the review PR was opened, give the user these next steps verbatim — substituting `<gitea-pr-url>`, `<branch>`, the release flag `-<x|y|z>`, and `$ARGUMENTS`:

      ```bash
      # 1. Review the PR on git.autonomic.zone:
      #    <gitea-pr-url>

      # 2. Pull the PR branch to your local dev machine:
      cd ~/.abra/recipes/$ARGUMENTS
      git fetch git@git.autonomic.zone:recipe-maintainers/$ARGUMENTS.git <branch>:<branch>
      git checkout <branch>

      # 3. Push to your upstream fork:
      git push dev HEAD:<branch>

      # 4. Open a PR on upstream and merge it:
      #    https://git.coopcloud.tech/coop-cloud/$ARGUMENTS/pulls

      # 5. After the upstream PR merges, publish the release (bumps the version label,
      #    commits, tags AND pushes the tag — all in one step):
      abra recipe release $ARGUMENTS -<x|y|z>
      ```