---
title: Publishing and Pull Requests
description: Publishing local changes, pull request handoff, issue completion target, PR review policy, PR merge policy, and publish safety.
relatedCommands:
  - alpaca publish --help
relatedDocs:
  - config
  - workflow-options
  - workflow-state
  - hierarchical-workflows
  - service-runtime
  - event-hooks
---

# Publishing and Pull Requests

Use this guide when local repository changes must be finalized into the tracked base branch, or when explaining pull request handoff behavior.

## When to Use

- Use `alpaca publish` to finalize local changes. For engineers, it commits selected local changes, opens a pull request, and merges it into the base branch unless reviewers or `--no-merge` are requested.
- Use `--path` when only a subset of local changes should be included in the publish.
- Use `--reviewer` when the pull request should be left open for review instead of merged immediately.
- Use `--no-merge` when the pull request should be left open without assigning reviewers.
- `publish` assigns the pull request to the authenticated tracker user while preserving existing assignees.
- When creating a pull request, `publish` asks a configured worker to draft the pull request body from the changes and falls back to a fixed publish note when no worker can do so.
- GitHub-compatible pull request templates are discovered from `pull_request_template.md`, `docs/pull_request_template.md`, `.github/pull_request_template.md`, and `PULL_REQUEST_TEMPLATE/` directories in those locations.
- `--restart-service` is usually unnecessary; use it only when the running service must reload an AlpacaLoop package update after publishing.
- Use this doc with `alpaca docs show config` for issue completion target, PR policy, and default reviewer behavior.

## Key Commands

```bash
alpaca publish -h
alpaca docs show config
alpaca docs show event-hooks
```

## Core Behavior

`alpaca publish` is explicit. The background service does not run it automatically. It finalizes selected local changes by committing them, opening a pull request, and merging the pull request into the configured base branch unless reviewers or `--no-merge` are requested.

`--path <path>` scopes the working tree changes added to the publish commit. Repeat it for multiple paths. Existing unpublished commits on the branch are still pushed and included in the pull request.

`-m` or `--message <text>` sets the commit message and pull request title. Without either option, publish uses the default commit and PR title while still allowing the worker to draft the PR body. `--reviewer <name[,name...]>` requests pull request review from one or more users and leaves the pull request unmerged. Repeat `--reviewer` or use comma-separated names for multiple reviewers. `--no-merge` leaves the pull request unmerged after committing, pushing, and opening or reusing it. `-y` or `--yes` skips the confirmation prompt. `--restart-service` restarts the service safely after publishing when the running service must reload an AlpacaLoop package update; it cannot be combined with `--reviewer` or `--no-merge` because those publishes do not merge into the base branch.

After opening or reusing the pull request, `publish` assigns it to the authenticated tracker user. Existing pull request assignees are preserved.

When `publish` needs to create a new pull request, it builds context from the branch's commit log, changed file list, diff stat, and diff against the base branch, then asks the configured worker to draft the pull request body. The pull request title always comes from `-m` or the default publish message; any title returned by the worker is ignored. If there are no configured workers, context collection fails, the worker defers or fails, or the worker returns an empty body, `publish` uses a fixed fallback body instead. Existing open pull requests for the branch are reused and their body is not regenerated.

Pull request template discovery is automatic for GitHub and Gitea repository hosts. AlpacaLoop loads Markdown templates from default PR template files such as `pull_request_template.md`, `PULL_REQUEST_TEMPLATE.md`, `docs/pull_request_template.md`, `docs/PULL_REQUEST_TEMPLATE.md`, `.github/pull_request_template.md`, and `.github/PULL_REQUEST_TEMPLATE.md`, plus Markdown files under `PULL_REQUEST_TEMPLATE/`, `docs/PULL_REQUEST_TEMPLATE/`, and `.github/PULL_REQUEST_TEMPLATE/`. Non-Markdown files and empty templates are ignored. The discovered templates are passed to the worker as pull request body shape candidates, and a selected template should have its questions, headings, and order preserved in the generated PR body. There is no `publish` CLI option to force a particular pull request template; adjust repository templates or the generated body if exact wording is required.

Issue work can move to a pull request handoff state, represented by `AI: Working in PR`. After `workflow_closing` confirms source issue completion, `issueCompletion.target` controls whether AlpacaLoop pauses on the issue or moves to pull request handling. `issueCompletion.pullRequest.reviewPolicy` controls whether PR-local review runs (`never`, `if_needed`, or `always`), and `issueCompletion.pullRequest.mergePolicy` controls whether merge remains manual or can be automatic. Issue-level `/alpaca pr` sets the target to pull request while preserving effective PR policy defaults; `--issue-completion-target`, `--pr-review`, and `--pr-merge` can override individual parts.

With `target=pause_on_issue`, AlpacaLoop stops on the issue for human review before moving service cycles to the pull request; fresh issue comments replan on the issue. Users can later comment `/alpaca pr` to create or reuse a PR. With `target=pull_request`, it moves to the pull request. `reviewPolicy=if_needed` skips review only for low-risk, narrow, sufficiently proven changes and runs review for security, data, dependency, workflow, production, broad-scope, unresolved-comment, or test-risk signals. `mergePolicy=auto` can continue after PR readiness and attempt merge when merge conditions pass. These modes do not bypass branch protection or required host reviews; if the host rejects a merge, AlpacaLoop follows the existing merge failure and human handoff path. Inspect retry and failure details from the PR thread, issue status, and logs.

`repositoryHost.pullRequest.defaultReviewers` provides default reviewer names. Issue-level `--default-reviewers` can override or reset that list.

For publish-time integrations, use `alpaca docs show event-hooks`; this guide only covers how local changes reach the tracker and base branch.

## Watch Outs

- Review selected files before confirming `alpaca publish`, especially when using `--path` with unpublished commits already present on the branch.
- Use targeted publishes for workflow, system prompt, or catalog changes when unrelated working tree changes exist.
- Restarting the service is usually unnecessary for ordinary repository changes.

## Related Docs

- `alpaca docs show config`
- `alpaca docs show workflow-options`
- `alpaca docs show workflow-state`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show service-runtime`
- `alpaca docs show event-hooks`
