> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleetshift Guides

> Step-by-step guides for common Fleetshift workflows, from running your first agent shift to bulk-fixing Soundcheck failures.

These guides walk through common Fleetshift workflows end to end. Each one covers a
specific use case and can serve as a starting point for your own shifts.

## Create and run an agent shift

Use this guide to walk through the core shift lifecycle — creating a shift, running it
against target repositories, and merging the resulting pull requests.

1. Navigate to `Fleetshift` in the sidebar.
2. Click `New Shift` and select `Agent`.
3. Fill in:
   * Name: `add-codeowners`
   * Prompt: `Add a CODEOWNERS file to the root of the repository based on the existing contributors.`
   * PR title: `Add CODEOWNERS file`
4. Select two or three target repositories and click `Create`.
5. On the shift details page, select all targets and click `Run`.
6. Watch the target status transition from `pending` to `jobRunning` to
   `jobComplete`.
7. Open the `Logs` tab to follow the agent's progress in real time.
8. Once complete, open the `Diff` tab to review the generated changes.
9. Click `Create PR` on a completed target.
10. The status transitions to `prCreating` and then `prOpen`. Click the PR link to
    open it in GitHub.
11. After you merge the PR in GitHub, the status automatically updates to `prMerged`
    through the webhook you configured during
    [setup](/docs/portal/core-features-and-plugins/fleetshift/getting-started#connect-events).

## Fix a failing Soundcheck check

If a component is failing a Soundcheck check, you can launch a Fleetshift shift
directly from the Soundcheck UI to generate a fix.

1. Navigate to `Soundcheck` and open a check that has failing components.
2. On the Check Insights page, find a failing component.
3. Click `Fix with Fleetshift`.
4. You are taken to the Fleetshift new shift wizard with the Soundcheck check
   pre-filled as the target source.
5. Write a prompt that describes the fix, such as:
   `Fix the failing check by adding the required configuration file.`
6. Click `Create`, then trigger the shift and wait for it to complete.
7. Create a PR from the completed target.
8. Back in Soundcheck, the check details page shows the Fleetshift PR with its
   current status. Click `View Progress` to jump to the shift details.
9. After the PR is merged, the Soundcheck check transitions from `Fail` to `Pass`
   and the `Fix with Fleetshift` button is hidden.

## Fix a failing check with AiKA

You can also remediate failing Soundcheck checks conversationally through AiKA.

1. Navigate to `Soundcheck` and open a check with failing components.
2. On a failing component, click `Fix with AiKA`.
3. The AiKA chat panel opens with the check context preloaded — including the check
   name, entity ref, and failure details.
4. AiKA analyzes the failure and proposes a fix. Follow its guidance to remediate
   the issue.

<Note>
  `Fix with AiKA` is only available when AiKA is configured on your Portal
  instance.
</Note>

## Run a campaign-level bulk fix

When a Soundcheck campaign has many failing components, you can use Fleetshift to fix
them all at once instead of one at a time.

1. Navigate to `Soundcheck` and open a campaign with multiple failing components.
2. On the Campaign Insights page, click `Fix with Fleetshift`.
3. The Fleetshift wizard opens with the campaign as the target source, showing all
   failing components.
4. Create and trigger the shift. Jobs run against all failing components in parallel.
5. Back on the Campaign Insights page, a `Shift in progress` label indicates the
   shift is running.
6. The Pull Requests table shows all created PRs with their status, component name,
   and links. You can sort and filter by component name or status.
7. As you merge PRs in GitHub, the campaign pass rate increases automatically as
   checks transition from `Fail` to `Pass`.

## Use MCP actions for an AI-assisted workflow

If you use AiKA or another MCP-compatible AI agent, you can drive the entire shift
workflow through conversation. See the
[MCP actions reference](/docs/portal/core-features-and-plugins/fleetshift/mcp-actions)
for the full list of available actions.

Here is an example conversation flow:

1. Ask your agent: `What Soundcheck checks are failing on <component name>?`
   The agent calls `find-shift-for-soundcheck` and returns matching shifts or
   suggests creating one.
2. Ask: `Fix the failing <check name> check on <component name>.`
   The agent calls `trigger-honk-planning` and presents a remediation plan for your
   approval.
3. After you approve, the agent calls `trigger-honk-job` and polls `get-job-status`
   to report progress.
4. When the job completes, the agent calls `create-prs` and shares the PR link.
5. At any point, ask `How is my shift doing?` and the agent calls `get-shift-stats`
   to report completion percentage, merge rate, and failure rate.