Shipping Changes

When the agent finishes work in an orb, the changed files appear in the Changes pane of the thread. The main button in that pane, labeled Ship by default, sends a prompt to the agent that tells it how to get those changes into your repository. You can review the files first, then press the button when you are ready.

By default, Amp uses trunk-based development. This means there is one shared branch and every change lands on it directly. The agent commits any uncommitted changes, rebases onto the latest base branch, runs the tests, and pushes straight to the base branch. If another change landed first, the agent resolves the conflicts in the orb and pushes again.

Teams with other requirements can change what the Ship button does. The project setting is called Ship Behavior. It has three options, and the third one lets you write the prompt yourself.

The Default Ship Flow

With the default Ship behavior, pressing the button sends a prompt that asks the agent to:

  1. Commit any uncommitted changes.
  2. Fetch origin and rebase onto the latest base branch, usually origin/main.
  3. Run the full test suite.
  4. Push to the base branch.
  5. If the push fails because the base branch moved, rebase again, resolve conflicts, and push.
  6. Archive the thread, along with any threads it created that are no longer needed or running.

When a rebase produces a substantive conflict, the agent resolves it and checks with you before continuing. It ignores a failing test only after confirming that the same test also fails on the base branch without the thread’s changes.

The base branch is usually the repository’s default branch, such as main. The confirmation dialog shows the exact target before the prompt is sent.

Ship Behaviors

Open the project, go to Settings, and find Ship Behavior on the Overview tab. Choose one of these:

  • Ship is the default described above. The agent commits and pushes to the base branch.
  • Push to Branch asks the agent to commit and push a feature branch instead. If the thread is on the base branch, the agent first creates a branch with a short descriptive name. For GitHub repositories, the agent also gets a pull request URL after pushing and reports it to you. The button label changes to Push.
  • Custom Ship sends a prompt you write. Use it when your team has its own flow, such as a pull request template, a merge queue, a release script, or a Git host other than GitHub.

The setting applies to every thread in the project. In a workspace project, the project’s creator or a workspace admin can change it. In a private project, only the owner can. See Projects.

Write a Custom Ship Prompt

A custom Ship prompt is a plain text message. When someone presses Ship, Amp sends that text to the agent as if you had typed it into the thread. The agent then follows it with the tools it has in the orb, such as git, gh, and anything installed by .agents/setup.

Amp sends the text exactly as you saved it. There are no template variables, so write the branch names and commands you want the agent to use. The prompt must not be blank and can be up to 10,000 characters. The button label stays Ship, and the confirmation dialog says that the project’s custom prompt will be sent.

From Project Settings

  1. Open the project and go to Settings.
  2. On the Overview tab, set Ship Behavior to Custom Ship.
  3. A Customize Ship Prompt dialog opens. The text area starts with the default Ship prompt, or with your current custom prompt if you already saved one. Edit it and click Use Custom Ship.
  4. Click Save at the bottom of the settings section. The dialog only updates the form, and nothing is stored until you save.

Starting from the default text is the easiest way to make a small change, such as pushing to a different branch or skipping the archive step.

The new prompt applies to new threads and existing threads. Reload any thread page that was already open so it picks up the change. To edit the prompt later, choose Custom Ship again and the dialog opens with the saved text.

To set a default for every new project you or your workspace creates, open Settings, go to Projects, change Ship Behavior under Default Project Settings, and click Save Defaults For New Projects. Existing projects keep their own setting.

From the CLI

Write the prompt to a file and pass it with --custom-ship-prompt-file:

amp projects update acme/widgets \
  --ship-behavior custom \
  --custom-ship-prompt-file ./ship.md

Use - to read the prompt from standard input:

cat ./ship.md | amp projects update acme/widgets --ship-behavior custom --custom-ship-prompt-file -

The same flags work with amp projects create. The --custom-ship-prompt-file flag requires --ship-behavior custom, and --ship-behavior custom requires a prompt file.

Keeping the prompt in a file in your repository, such as .agents/ship.md, lets you review changes to it like any other code. Run the amp projects update command again after you change the file, because Amp stores a copy in the project settings and does not read the file on its own.

What to Put in the Prompt

State the steps in order and name the commands to run. Say what the agent should report back when it is done, and say when it should stop and ask you instead of guessing.

Put repository conventions that apply to all work, such as commit message format or which tests to run, in AGENTS.md instead. The agent reads AGENTS.md on every task, so the Ship prompt only needs to describe the delivery steps.

Here is an example for a team that requires a pull request with a template and a linked issue:

Commit any uncommitted changes. Create a feature branch named after the work in this thread if we are still on main. Fetch origin and rebase onto origin/main, then run pnpm test. Push the branch and open a pull request with `gh pr create --fill --template .github/pull_request_template.md`. Fill in every section of the template. If this thread references an issue, add "Closes #N" to the description. Report the pull request URL. Do not merge.

Here is an example for a team on GitLab:

Commit any uncommitted changes on a new feature branch and push it to origin. Then run `glab mr create --fill --remove-source-branch --target-branch develop` and report the merge request URL. Do not push to develop directly.

Here is an example for a team that ships to main but wants a release script to run first:

Commit any uncommitted changes. Fetch origin and rebase onto origin/main. Run `./scripts/release-check` and fix anything it reports. Run the full test suite. Push to origin/main. If the push is rejected because main moved, rebase and push again. Stop and ask me before resolving any conflict that changes behavior. When done, archive this thread.

Tools such as glab are not installed in orbs by default. Install them from .agents/setup so they are ready in every orb. See Customizing Orbs. gh is preinstalled and signed in.

Ship from Puck or Another Thread

When you ask Puck to ship or merge a thread, or when one thread ships another, Amp uses the project’s configured Ship Behavior, including a custom prompt. You do not need to repeat the instructions.

Puck can switch a project between Ship and Push to Branch when you ask. Setting or editing a custom prompt requires the project settings page or the CLI.

Switch Back

To return to the default, set Ship Behavior back to Ship in project settings, or run:

amp projects update acme/widgets --ship-behavior ship

Amp keeps the text of your custom prompt, so you can switch to Custom Ship again later without entering it a second time.