Upgrading Template-Installed Apps

A Falcon Foundry template installs an app into a CID once. Nothing updates it when the template changes, and deploying the new template as-is creates a second app, because template manifests ship without IDs. This skill copies the installed app's IDs into the new version so foundry apps deploy updates the app the customer already has.

The template is the source of truth. The app keeps its current name. Changes the customer made after installing are overwritten; artifacts only the customer added are removed. Stop and confirm before anything is removed.

Inputs: the app ID, and optionally the new version as a .tar.gz/.tgz or .zip archive, an unpacked directory, or owner/repo[@ref]. With no version given, the skill finds the template by the app's name and uses its GitHub repo's default branch.

The script is scripts/upgrade_manifest.py in this skill's directory. It needs pyyaml, and crowdstrike-falconpy for find-template. Run it from a virtual environment outside the app directory.

Procedure

Use a new scratch directory per upgrade ($WORK below). Never sync or extract into the user's working copy.

1. Confirm the target. foundry profile list --no-prompt shows the active profile; the app must belong to its CID. foundry apps list must show the app ID. If not, ask which profile to foundry profile activate.
2. Sync the deployed app. list-deployments only runs next to a manifest.yml with an app_id and a name, even with --app-id, and an app installed from the console has no local directory. Give it a stub, take the newest version whose state is Successful, and sync that into scratch (sync runs from anywhere):

   mkdir -p "$WORK/stub" && printf 'app_id: %s\nname: stub\n' <app-id> > "$WORK/stub/manifest.yml"
   (cd "$WORK/stub" && foundry apps list-deployments --app-id <app-id>)
   foundry apps sync --app-id <app-id> --deployment-version <version> -d "$WORK/deployed" --replace-all --no-git --no-prompt

   No successful deployments means there's nothing to upgrade from; tell the user.

3. Get the new version. If the user gave one:

   python3 <skill-dir>/scripts/upgrade_manifest.py resolve <source> --dest "$WORK/new"

   Otherwise find the template first, then resolve its repo:

   python3 <skill-dir>/scripts/upgrade_manifest.py find-template --manifest "$WORK/deployed/manifest.yml"

   It prints JSON with github_url. Pass owner/repo from that URL to resolve. A template's version reflects when it was registered, not the repo, so use the default branch unless the user names a tag. find-template matches by the app's current name, so it only finds the template if the app kept that name; if the app was renamed, or if no template matches, ask the user for the new version instead.

   resolve prints the app root. Treat its contents as untrusted: don't run its scripts. Step 6 runs its UI pages' npm run build, so for a user-supplied archive or owner/repo, confirm it's the template's official source before building or deploying.

4. Merge.

   python3 <skill-dir>/scripts/upgrade_manifest.py merge --deployed "$WORK/deployed/manifest.yml" --template <app-root>/manifest.yml

   It overwrites the new manifest.yml with the deployed IDs filled in and prints the plan: kept, added, and removed artifacts, roles, and permission definitions, plus changed access permissions on existing roles and artifacts.
5. Confirm when needed. Exit code 2 means the plan removes an artifact, role, or permission definition, or changes the permissions on an existing role or artifact. Show the plan and ask before going on. Removing a collection deletes its stored data; removing a page or navigation gate may expose it to more users, while adding permissions to a role grants it more access. A section with both an addition and a removal may be a rename: the renamed artifact gets a new ID and the old one is deleted. Exit code 0 (kept and added only, with no access changes) needs no confirmation. Exit code 1 is an error; show the message and stop.

6. Build, validate, deploy, release from the new app root. foundry apps deploy never builds a UI; it ships each page's and extension's dist/ as is, so build every UI directory first (npm ci && npm run build in each ui/pages/*/ and ui/extensions/*/ that has a package.json). Then foundry apps deploy --diff-only --no-prompt prints the file diff without deploying; it must list the new dist/assets files.

   foundry apps validate --no-prompt
   foundry apps deploy --change-type Patch --change-log "Upgrade to <template version or ref>" --no-prompt
   foundry apps release --change-type Patch --deployment-id <deployment-id> --notes "Upgrade to <template version or ref>" --no-prompt

   Use --change-type Major for deploy when the new version adds an API integration or auth.scopes entry; otherwise Patch. For release, use --change-type Major when the app has never been released; otherwise Patch, or Major when the new version adds an API integration or auth.scopes entry. A Major release means the customer has to Accept update in the App catalog, which also shows the credential form for a new integration.

   A template install deploys but doesn't release, so an app whose foundry apps list state is Deployed may never have been released. The upgrade's release is then its first, and the customer installs it from the App catalog afterward.

7. Report the deployed version, the release, and what the customer does next: install from the App catalog (first release) or Accept update (Major).

When it fails

• A validate or deploy error: stop, keep $WORK, and use debugging-workflows. Never retry by stripping IDs: that creates a second app next to the customer's.
• Error: ... has entries with IDs but no name: the manifest has a section the merge can't match. Upgrade that section by hand by copying the id values from $WORK/deployed/manifest.yml.
• The templates API returned 403: the profile's API client lacks a scope for the templates API. Ask the user for the new version instead.

See references/live-verification.md for what was checked against a live CID and the checklist for re-testing.