fleetshift-run-shift

Files (1)

• SKILL.md

SKILL.md (first lines)

# Run a Fleetshift shift

Running a shift triggers an agent job per target repository, then monitors
each triggered job until it finishes (or until a bounded wait expires).

> **Mutating action — explicit confirmation required.** Do **not** call
> `fleetshift:trigger-shift` until the user has explicitly confirmed which
> shift and which targets to run. Ask for a clear "yes" first.

## Kill switch: stop a shift

If the user says stop, cancel, abort, "wait", "never mind", or otherwise
changes their mind at **any** point, do this right away. Stopping doesn't
need the confirmation step that triggering does:

1. **Stop triggering.** Don't call `fleetshift:trigger-shift` for any target
   that hasn't been triggered yet, and drop the rest of the batch.
2. **Stop polling.** End the monitor loop.
3. **Stop the running jobs.** Call `fleetshift:stop-jobs` right away, once,
   with every triggered `jobIdentifier` that hasn't reached a terminal
   state. Portal marks it as destructive, so the CLI needs `--yes`. The
   user's request to stop is the authorization: don't ask again, and skip
   `--dry-run` here because stopping must be immediate.

   ```bash
   npx @spotify/portal-cli actions fleetshift:stop-jobs --input '{"shiftName":"<shift-name>","jobIdentifiers":["<job-identifier-1>","<job-identifier-2>"]}' --yes --json
   ```

   If you no longer have the identifiers (new session, the monitor ended),
   list the running targets: each one includes its `jobIdentifier`. Always
   query with `offset: 0`, stop what it returns, and query again until it
   returns nothing. Don't page with `offset`, because stopped jobs drop out
   of the filtered list and later pages would skip running ones. If it
   returns only jobs that `stop-jobs` already rejected, stop looping.

   `stop-jobs` reports a job it couldn't stop as `rejected` instead of
   failing the call. Report every `rejected` job to the user and send them
   to the Fleetshift UI fallback below for those jobs.

   ```bash
   npx @spotify/portal-cli actions fleetshift:get-shift-targets --input '{"shiftName":"<shift-name>","status":"jobRunning","limit":250,"offset":0}' --json
   ```

   If `stop-jobs` isn't available (older Portal versions) or the call
   fails, send the user to the Fleetshift UI, where stopping takes one
   click:
   - **All running jobs in a shift:** open
     `<portal-base-url>/fleetshift/shifts/<shift-name>`, select the running
     targets, and press **Stop (N)**.
   - **A single job:** open its `portalJobUrl` (from the `trigger-shift`
     response) and press **Stop**.

   List every triggered job that wasn't in a terminal state as a markdown
   link to its `portalJobUrl`, so the user has them all in one place.
4. **Confirm it worked.** Call `fleetshift:get-job-status` once for each
   job (after the user says they've stopped them, if you used the UI) and
   check that it reports `stopped` or another terminal state. Report
   anything still running.

Stopping doesn't delete the shift, and it doesn't touch PRs that were
already opened. Closing PRs (`fleetshift:close-prs`) or deleting the shift
(`fleetshift:delete-shift`) are separate, destructive steps. Do them only if
the user explicitly asks, and get a clear "yes" first.

## Prerequisites

- The Portal CLI is authenticated: `npx @spotify/portal-cli auth show`.
  If it isn't, ask the user to run `npx @spotify/portal-cli auth login`.
  If `auth list` shows more than one Portal instance, confirm which one
  with the user and pass `--instance <name>` on every call.
- If a Portal MCP server is connected instead, the same actions are
  available as `fleetshift_<action>` tools (for example
  `fleetshift_list-shifts`). They take the same input, but have no
  `--dry-run`, so the confirmation steps below matter even more.
- Pass `--yes` only to `stop-jobs` in the kill switch. Never pass it to
  `close-prs` or `delete-shift`; these skills don't call them.
- A shift definition already exists (see the `fleetshift-create-shift` skill).

## 1. Locate the shift and its targets (read-only)

```bash
# Find the shift (list if unsure of the exact name)
npx @spotify/portal-cli actions fleetshift:list-shifts --input '{}' --json

# Its definition and status breakdown
npx @spotify/portal-cli actions fleetshift:get-shift --input '{"shiftName":"<shift-name>"}' --json

# Its targets and their current status. Targets that were never triggered
# are included as `pending`, with no job fields.
npx @spotify/portal-cli actions fleetshift:get-shift-targets --input '{"shiftName":"<shift-name>"}' --json

# Only the targets still waiting to run
npx @spotify/portal-cli actions fleetshift:get-shift-targets --input '{"shiftName":"<shift-name>","status":"pending","limit":250,"offset":0}' --json
```

- Prefer running only targets that are `pending` (or re-running ones you
  agree to re-run). Surface any targets that are already `jobRunning`,
  `jobComplete`, or `jobFailed` and confirm the intended scope.
- **Re-running a completed target replaces its result.** A target only
  keeps its latest run. If you re-run a `jobComplete` target and the new run
  fails or is stopped, the earlier result can no longer be used to open a
  PR. Before re-running a `jobComplete` target, say so, and suggest
  `fleetshift-create-prs` first if the user wants that change as a PR.
- If the shift backs a failing soundcheck check, route through
  `fleetshift:find-shift-for-soundcheck` first and confirm the matched shift
  with the user before running.

## 2. Confirm explicitly, then trigger (mutating)

`trigger-shift` runs **one target per call**. Validate the first call with
`--dry-run`, which checks the input locally and triggers nothing:

```bash
npx @spotify/portal-cli actions fleetshift:trigger-shift --input '{"shiftName":"<shift-name>","targetId":"component:default/my-service","repo":"my-org/my-service"}' --dry-run --json
```

Present the shift name and the exact list of targets to run, and get explicit
confirmation. List them every time, even if the user already said "run it" or
approved the shift earlier: a "yes" counts only after they've seen the exact

From spotify/portal-ai-plugins, Apache-2.0.

More from spotify/portal-ai-plugins