Deploy to Shopware PaaS by delegating to the paas-cli plugin

[lasomethingsomething]

User story

As a Shopware developer, I want PaaS deployments to use the same CLI workflow as SSH deployments, without managing the PaaS CLI myself.

Scope

• Implement PaaS support after the SSH deployment interface is complete.
• When a PaaS target is selected, verify that a supported paas-cli-as-plugin is available.
• If missing or incompatible, show a clear installation or update message.
• Delegate deployment operations to the PaaS CLI; do not reimplement them.

Prerequisites

• Agree on the warning flow and actionable install/update message for a missing or incompatible PaaS CLI.
• Confirm the supported PaaS CLI version range.

Acceptance criteria

• When shopware-cli project deploy resolves a PaaS target, it verifies plugin availability before code selection or deployment begins.
• If the plugin is unavailable or incompatible, deployment stops and displays the required action.
• Once available, project deploy delegates the PaaS workflow to the plugin.
• SSH targets never perform the PaaS plugin check.

Readiness checklist

• Acceptance criteria are clearly defined.
• Backward compatibility impact addressed.
• Documentation written.
• Tests added or adjusted accordingly.

[lasomethingsomething]

Renaud Hager (@renaudhager) Sandor Akszenovics (@axasanya) Hey both, please see the "prerequisites." I can draft the messaging, but wanted to check from your side if you have preferences or reqts.

[axasanya]

somethings (@lasomethingsomething) Thanks for the ping.
Please allow to confirm the baseline of referred paas-cli plugin first, as aligned with Renaud Hager (@renaudhager), since the rest of this builds on it:

• The paas-cli plugin is the paas-cli binary itself, and shopware-cli downloads it automatically.
• There's no separate wrapper artifact to build or maintain.

If that's correct, I can see two consequences for this ticket.

• Availability stops being something the user has to fix, shopware-cli resolves it.
• And version compatibility gets simpler, because shopware-cli decides which version it fetches, so we need a minimum rather than a range.

With that settled, the acceptance criteria as written cover one precondition. Four others have to hold before the handover is safe, and each fails differently:

Precondition	Why it matters	How it's resolved
Compatible paas-cli available	Auto-resolvable — shopware-cli downloads it	Fetch the minimum supported version — CLI setup
Authenticated session	Present ≠ logged in. The one I'd most want added: an unauthenticated CLI passes the current check and then fails mid-deployment	sw-paas auth interactively; token or service account in CI — Account
Actor is allowed to deploy	Being authenticated doesn't mean being permitted. Rights are granted per application, so a valid login can still have no deploy permission on this one	The user or token needs deploy rights on the target application — Account
Target is resolvable	PaaS deploys a commit from the repository configured on the PaaS Native project	Tree clean, HEAD pushed, and the git remote matching the repository configured on the PaaS Native project — Applications
Application is deployable	After a failed deployment the platform can't resolve which image to use	No deployment in flight, previous deployment succeeded — Applications

On authentication specifically: sw-paas auth opens a browser to log in with a Shopware account, so in an interactive terminal the precondition can resolve itself. CI can't use the browser flow and needs a token or service account, so that path should fail with the token instructions. Account + Token details

Suggested acceptance criteria

• When project deploy resolves a PaaS target, it verifies before handing over:
  • a compatible paas-cli is available, downloading it if necessary
  • paas-cli has a valid authenticated session
  • the actor has deploy rights on the target application
  • the target is resolvable: tree clean, HEAD pushed, git remote matching the repository configured on the PaaS Native project
  • the application is deployable: no deployment in flight, previous deployment did not fail
• Each failed precondition stops the deployment and names the required action,
  with a distinct message per case.
• Where the session is interactive, a missing authentication offers the browser
  login rather than only failing.
• Once preconditions pass, project deploy routes to paas-cli and surfaces its
  output and exit status.

One thing worth adding on failures

When paas-cli exits with an error, the message should tell the user to check the current state — sw-paas application list or sw-paas watch , rather than stating the deployment failed. See Known issues.

On your two prerequisites

Version range: covered above: a minimum rather than a range, with Renaud Hager (@renaudhager) owning the policy.
Messaging: yes please, and the preconditions give you the cases. I can send you the exact command that resolves each one so you're not guessing at our side. Just let me know 👍

One more thing

I saw there's an open question in the parent about how project deploy create selects a commit on PaaS, and this ticket is the one that will hit it first. I'll add that and a few other notes on the command mapping over in #1553 rather than here.