Fix, review, and ship

Start on the bug’s task and choose Fix with Pencil. Choose its board or product, repository, and coding agent. The resulting Build chat keeps the task attached and assigns it to the chosen coding agent. Automatic task pickup stays off so a second agent run does not start the same fix. Discuss the reproduction and acceptance criteria, approve the implementation plan, then approve pushes and draft PR creation when prompted.

The release sequence is PR preview → approve → merge to main → staging → production. Review and preview builds can run at the same time. A preview can be built while the PR is draft.

Set up a repository#

An administrator connects GitHub and the repository, then opens Ship → Release workflow. Configure:

1. Required CI check names exactly as GitHub reports them. At least one is required. Both check runs and commit status contexts are checked.
2. Required GitHub reviewer login names, including the [bot] suffix for bots. Install and authorize each review provider in GitHub. If it supports a comment command for requesting review, enter that command here.
3. Pencil QA or security reviewers on the task’s board or product. A linked task and an approved specialist review for the current PR revision are required.
4. Separate PR previews, staging, and production deployment workflows. Each must run its reviewed workflow from the repository’s default branch, declare the Pencil release contract, and accept an exact sha and pencil_operation. The SHA input selects the change to deploy, including an unmerged PR; the workflow ref stays on the trusted default branch. An environment label alone does not change a workflow’s deployment destination.
5. Enable the release workflow. Saved policies that are disabled cannot dispatch releases until enabled again. Existing repositories with no release policy retain their older deployment configuration until an administrator adopts this workflow; merging through Pencil requires an enabled policy.

Provider installation, runner availability, DNS, certificates, and environment permissions are setup prerequisites. A failed provider or missing check leaves a specific blocker; it does not count as a clean review. GitHub environment approvals can still require an authorized person to approve in GitHub. Pencil reports that waiting state and links to the run.

The administrator maintains deployment credentials. Members can inspect evidence, request reviews, and send findings to their assigned coding agent. Administrators approve previews, mark PRs ready, resolve GitHub discussions, merge, deploy, cancel, retry, and restore releases. Task privacy and customer access also apply to specialist findings.

Review and preview a change#

Open Review and ship on the PR in Ship, the task’s proposal, or the Build inspector. These surfaces use the same release decision.

• Build preview starts an isolated application and backend for the current PR revision. Follow Preview logs for progress, then Open preview when health verification succeeds.
• Request / rerun AI reviews requests the configured GitHub reviewers and starts a new Pencil specialist round. Bots without a request command may run automatically on push or when the PR becomes ready; follow that provider’s setup instructions.
• Expand the combined findings to see provider, reviewer, state, file, line, and source link. Outdated findings remain visible. Select current findings and choose Ask agent to fix selected findings to send them to the originating Build chat and branch. For task-only work, they go to its assigned coding agent. Open implementation chat takes you back to that conversation; private chat permissions still apply.
• Resolve current GitHub discussions after verifying the fix. A review submission from a configured bot can establish review completion; ordinary bot comments cannot. Human GitHub reviewers must approve, and current unresolved discussions block merging.

Open the preview, exercise the bug and acceptance criteria, check the verification box, and choose Approve this preview. Approval belongs to that exact revision and preview build. A new push or another preview build requires a new inspection and approval. Previews expire after 24 hours; staging environments expire after 72 hours in Pencil’s self-hosted controller.

Choose Mark ready for review when the implementation is ready. Merge to main is available only after the required CI, GitHub reviews, Pencil reviews, discussions, preview health, and preview approval pass. Pencil checks the live head again and sends that expected revision to GitHub when merging. If the head changes, refresh and review it again.

Stage and promote#

After merge, wait for CI on the resulting main commit, then choose Deploy main to staging. A squash or merge commit differs from the reviewed PR head, so its CI and staging verification are separate gates.

Open the verified staging link and validate the release. In Promote a verified staging release, select that release and confirm promotion. Production receives the same source commit even if main has advanced. Pencil’s self-hosted workflows rebuild for each environment because their public configuration differs; they do not promote an identical binary image.

A successful workflow is shown as Succeeded. A protected release becomes verified only when its workflow reports an application URL and health proof for the selected revision. Review the recorded revision and verification time when assessing deployment history.

Recover a failed step#

Expand Preview and release attempts to open logs or the environment. Cancel run requests cancellation of identified running jobs. Retry failed steps starts a new attempt and retains already successful steps. If a dispatch timed out before its identity was acknowledged, choose Reconcile dispatch first; Pencil does not blindly send a duplicate deployment.

Restore a previous production release checks that the changes are limited to compatible web/content paths and that the target was previously verified in production. Confirm the current and target revisions before restoring. The server also checks its actual active and previous slots. Backend, dependency, deployment configuration changes, large diffs, or an unavailable previous slot require a reviewed forward fix. Restore never reverses backend migrations or production data.

For operator setup and the workflow proof format, see the repository’s deploy/nonproduction/README.md and docs/repo-deployment-setup.md.