--- lastModified: 2026-10-07 --- # 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. ## Restack Changes Before shipping, use restack to organize a large diff or an agent's intermediate commits into a cleaner set of commits. You can use it in orb threads or threads connected to a [runner](/docs/cli/runners). 1. Open the thread's Changes pane. 2. Click Restack and wait for the agent to finish reorganizing the commits. 3. Open the commit picker at the bottom of the pane and select a commit to review its diff. The agent includes committed and uncommitted changes since the merge base, where your branch split from its base branch. Restacking rewrites local commit history while keeping the final file contents the same. It does not push your changes. ## 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. If the thread runs in a worktree that a [runner](/docs/cli/runners#archive-a-thread-and-remove-its-worktree) created, the agent also removes that worktree as its last step. 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](/docs/projects#permissions). ## 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 **Project Defaults**, change **Ship Behavior**, and click **Save Defaults**. Existing projects keep their own setting. ### From the CLI Write the prompt to a file and pass it with `--custom-ship-prompt-file`: ```bash amp projects update acme/widgets \ --ship-behavior custom \ --custom-ship-prompt-file ./ship.md ``` Use `-` to read the prompt from standard input: ```bash 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`](/docs/customize/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: ```prompt 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: ```prompt 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: ```prompt 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](/docs/orbs/customizing#installing-software). `gh` is preinstalled and signed in. ## Ship from Puck or Another Thread When you ask [Puck](/docs/puck) to ship a thread, or when one thread ships another, Amp sends that thread the same prompt as its Ship button, built from the project's configured Ship Behavior, including a custom prompt. You do not need to repeat the instructions. Agents use a prompt only when you name it. "Commit, merge, and push" is followed as written; say "ship" to use the Ship prompt. To change the default Ship text everywhere, not per project, edit the built-in `ship` prompt on the **Prompts** page of your personal or workspace settings. A project's **Custom Ship** or **Push to Branch** setting still takes precedence for that project. Puck can switch a project between **Ship**, **Push to Branch**, and **Custom Ship** when you ask, and can set or edit the custom prompt. ## Switch Back To return to the default, set **Ship Behavior** back to **Ship** in project settings, or run: ```bash 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.