Remove deprecated `workload-identity-provider` + `service-account` workflow inputs in the next v3 minor

[krisrowe]

Remove deprecated workload-identity-provider + service-account workflow inputs in the next v3 minor

Problem

The reusable workflow at .github/workflows/deploy.yml carries two inputs that are now functionally vestigial:

• workload-identity-provider
• service-account

These were the canonical inputs in v3.2.x and earlier. v3.3.0 introduced project-id and project-number as the new canonical pair — the workflow now derives the SA email and WIF provider path from those, and uses project-id to pass --project to gapp setup/gapp deploy (which eliminated the prior CI dependency on resourcemanager.projects.list).

To smooth the transition, v3.3.0 kept the old inputs as optional fallbacks with in-place DEPRECATED comments referencing a future v4 removal.

That deferral is excessive. The "compat" benefit is illusory, the carrying cost is real, and there's no semver constraint that forces removal to wait for a major bump.

Why this isn't a breaking change in the semver sense

The gapp major version is defined by the contract between deployed projects and the gapp build that manages them. That contract lives in:

• Solution label key/value format (gapp_<owner>_<name>=v-N)
• Bucket naming (gapp-<name>-<project>)
• Secret naming convention
• Terraform state path layout
• Cloud Run service name format
• Role label format

The v3.3.0 workflow input change touched none of these. It was purely CLI / workflow input surface. A v3.4 (or later) CLI can manage any project a v3.0 CLI set up, before and after removing the deprecated inputs. The persistent-state contract is unchanged.

The classic "CLI version Y can't manage projects deployed by CLI version X" fear — which is the real reason gapp's contract version exists — does not apply here.

Why the "compat" the deprecated inputs provide is vestigial

The only thing the deprecated inputs let a caller do today is:

Bump the @vX.Y.Z ref in a CI workflow file without simultaneously updating the input names.

That's not a real win. The workflow's path resolution and --project flag passing depend on the new inputs (project-id, project-number). A caller who bumps the ref but doesn't migrate the inputs gets a workflow that loads but doesn't actually exercise the new functionality. They have to migrate eventually anyway.

The cost of the deprecated inputs being present:

• More inputs in the workflow signature (more cognitive load for new callers reading it)
• || fallback expressions in auth step (workload_identity_provider: ${{ inputs.workload-identity-provider || format(...) }}) — non-trivial to reason about
• Two ways to do the same thing — confusion for first-time users about which is canonical
• Maintenance drag: any future change to the auth step needs to consider both paths

Why existing callers won't be silently broken

All existing callers pin the gapp workflow ref explicitly in their own CI repo:

uses: <owner>/gapp/.github/workflows/deploy.yml@v3.4.0

They do not auto-upgrade. A caller voluntarily bumping the ref to a version that removed the deprecated inputs would receive a clear, deterministic error from GitHub Actions:

Error: Unexpected input(s) 'workload-identity-provider, service-account', valid inputs are [...]

No silent breakage. No state corruption. The error names the inputs and points at the gap. The caller updates their workflow file to use project-id + project-number, which is the migration they would have done eventually anyway.

This is normal workflow-ref migration practice — bumping a pinned ref is an explicit, deliberate action, and the rare cases that require coordinated input changes are exactly what the explicit pin is for.

Proposed resolution

Remove workload-identity-provider and service-account inputs entirely from deploy.yml in the next v3 minor release. No long deprecation window, no v4 forcing function.

Concretely:

• Remove the two input definitions from the workflow_call.inputs block
• Remove the DEPRECATED comment headers that precede them
• Simplify the Authenticate to Google Cloud step's workload_identity_provider and service_account expressions — drop the || fallback, derive purely from project-id / project-number
• Update the example caller snippet in the top-of-file doc comment if it still mentions the old inputs
• Update README.md example workflow if applicable
• Add a CONTRIBUTING.md note (if not already present) clarifying that workflow-input renames are fair game in minor releases as long as no persistent-state contract changes

Optional: helpful error step instead of GH Actions default

A small if: inputs.workload-identity-provider != '' || inputs.service-account != ''-style guard step that emits a clear error message before the auth step ("These inputs were removed in vX.Y.Z. Use project-id + project-number. See [migration doc].") would be slightly more helpful than the default GH error.

However, this requires re-introducing the input definitions just to detect them — partially defeating the cleanup. Probably not worth the complexity. The default GH Actions error names the bad inputs and that's enough to point the caller at this issue or the README.

Recommendation: skip the helpful-error step; rely on the default GH Actions error plus a release-note callout.

Alternatives considered and rejected

• Wait for v4. The in-place comments currently say to remove in v4. But v4 has no forcing function — there's no other contract-breaking change accumulating. Pegging removal to a major-bump milestone that doesn't exist just defers cleanup indefinitely. The inputs continue to drag for an unknown duration.
• Keep them forever as a permanent alias. Two ways to do the same thing in a workflow signature is a steady source of confusion for new callers. The carrying cost compounds with every additional input or step that has to know about both paths.
• Emit deprecation warnings for a minor release first, then remove the release after. Defensible but adds complexity. The deprecation comments have already been in deploy.yml since v3.3.0; anyone reading the workflow has been warned. A second deprecation-warning step is belt-and-suspenders without much added safety, since callers must opt into the new ref to encounter either signal.

Work breakdown

• Remove workload-identity-provider and service-account from inputs block in .github/workflows/deploy.yml
• Remove the two DEPRECATED comment blocks preceding those inputs
• Simplify auth step expressions: drop the || fallback, derive directly from project-id / project-number
• Update the top-of-file doc comment example if it references the old inputs (verify it currently uses the new shape)
• Update README.md example workflows
• Document the policy in CONTRIBUTING.md: "Workflow input renames are minor-version changes. Persistent-state contract changes (label format, bucket/secret naming, tfstate layout, service name format) are major-version changes."
• Bump version to the next minor and tag
• Marketplace ref bump
• Release note highlighting the input removal and pointing at project-id / project-number as the replacement