feat: invoke customActions from deploy hooks and verify (skaffold/v4beta15)

[bogdannazarenko]

Invoke customActions from deploy hooks and verify

A customAction is a reusable, containerized task. Today it can only be run standalone via skaffold exec. This PR lets the same action definition be invoked from two more places, so users don't have to re-implement the task in each shape:

1. Deploy lifecycle hooks — deploy.*.hooks.before/after: [action: {name: ...}]
2. Verify test cases — verify[].action: {name: ...} instead of an inline container

Both reuse the existing customActions runtime (the same one skaffold exec drives), so an action runs identically — including its own executionMode, timeout, failFast, and (once #10066 lands) runArgs — regardless of where it's triggered from.

customActions:
  - name: db-migrate
    containers: [{ name: migrator, image: myorg/migrator, command: ["./migrate"] }]
  - name: smoke-test
    containers: [{ name: smoke, image: myorg/smoke, command: ["./smoke"] }]

deploy:
  kubectl:
    hooks:
      before: [ { action: { name: db-migrate } } ]   # (1) deploy hook

verify:
  - name: smoke
    action: { name: smoke-test }                     # (2) verify test case
  - name: health                                     # inline container still works
    container: { name: health, image: alpine:3.20, command: ["/bin/sh","-c","wget -qO- http://svc/healthz"] }

Hooks (action: deploy hook)

• New action: union member on DeployHookItem, alongside host:/container:.
• hooks.ActionInvoker interface + SetDefaultActionInvoker, wired once in runner.New after GetActionsRunner. The hooks package stays free of any pkg/skaffold/actions import (no new cycle); a small actionsRunnerInvoker adapter in pkg/skaffold/runner bridges the two.
• validateActionHookRefs: unknown / empty action references fail at load time across kubectl, helm, and kpt deployers.

Verify (verify[].action)

• New optional action field on VerifyTestCase; container is now conditionally required (validation enforces exactly one of container / action).
• GetVerifier skips action-referencing test cases (they aren't container verifiers); SkaffoldRunner.Verify dispatches them to r.actionsRunner.Exec after the container verifier completes.
• Validation reuses a shared knownActionNames helper (also used by the hook validator) to reject unknown references.
• Docs section in verify.md; integration fixture integration/testdata/verify-custom-action mixes an inline container test case with an action-referencing one.

Design note — runArgs compose for free. Because both entry points delegate to the actions runner rather than copying the action's containers into the hook/verify container path, the action's declared runArgs (PR #10066) are applied automatically. The two PRs are orthogonal — only a trivial rebase ties them together (both sit on skaffold/v4beta15).

Schema: skaffold/v4beta15 (final commit)

v4beta14 is released, so the new fields required cutting v4beta15 (frozen v4beta14 package + upgrade path). Per the schema-last convention, the whole generated cut — v4beta15.json, CLI reference, docs version, and the apiVersion bump of the unreleased integration/{examples,testdata} — is isolated in the last commit, keeping the hand-written feature diff reviewable. The cut also corrects v4beta14.json (an earlier WIP had captured a stray ActionHook into the released schema).

Notes

• examples/hooks-action/ was removed; an example using the unreleased action: field can't satisfy the released-version constraint on examples/, so it lives only under integration/examples/ until v4beta15 ships.
• Per-commit note: the feature commits reference the new schema fields, which are defined in the final (schema) commit — so they don't build in isolation, but the PR HEAD does and CI runs on HEAD. Say the word if you'd prefer schema-first ordering.

Out of scope

• CloudRun deploy hooks (still []HostHook only), pre/post-delete hooks, render/build action hooks.

Tests

• go build ./..., go test ./pkg/skaffold/hooks/... ./pkg/skaffold/schema/... ./pkg/skaffold/runner/... ./pkg/skaffold/verify/... ./cmd/..., hack/schemas, ./hack/check-samples.sh — all green locally.
• Docker-gated integration (TestLocalVerifyWithCustomActionRef, hook examples) defer to CI.

[gemini-code-assist]

Code Review

This pull request introduces 'Action hooks,' allowing users to reference custom actions as deployment lifecycle hooks. The implementation includes the ActionInvoker interface to prevent package cycles, updated validation to ensure action names exist, and new documentation and examples. A review comment points out that adding fields to the v4beta14 schema might violate versioning policies if that version is already frozen, suggesting a move to a new schema version.

[bogdannazarenko]

Waiting on maintainers to cut new schema version on main branch

[bogdannazarenko]

Hi @Darien-Lin @menahyouyeah could you take a look please when you get a chance? Thank you