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.

Deploy changes that are already merged#

1. Open Ship and choose the repository you intend to release.
2. Select Staging, then choose Deploy main to staging in the Deploy latest main card. This includes all merged changes at that commit; you do not need to deploy each PR separately.
3. Wait for the staging release to succeed, open its application link, and check the changes.
4. In Promote a verified staging release, choose Promote to production for that release and confirm. Production deploys the same verified commit, even if newer changes have since merged.
5. Follow the release status and logs in Ship. A successful workflow and the live application’s matching commit provide the deployment evidence.

Deployment setup is a one-time administrator task. Pencil dispatches the repository’s GitHub Actions workflows; those workflows use their configured runners and deployment credentials. Routine deployments do not require signing into Google Cloud. Cloud access is a separate administration step when a runner, server, credential, or other prerequisite needs repair.

If Ship says Setup required, open Release workflow. Configure staging, production, and PR previews separately. Choose only workflows compatible with that environment; ordinary tests belong in required CI checks. When exactly one workflow is compatible, Use [workflow name] selects it with the standard inputs. Review the selection and save. Advanced workflow inputs are available only when you need to inspect or repair them.

An offline runner needs administrator attention. Selecting a workflow does not start or provision its runner. A production deployment started outside Pencil may also be absent from Pencil’s release history; inspect its GitHub run before starting another release.

Set up a repository#

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

1. Select required CI checks from the names GitHub reports on the default branch. At least one is required. Both check runs and commit status contexts are checked. Saved names that no longer report are shown for explicit repair; Pencil never silently replaces them.
2. Human preview approval happens in Pencil, even for a PR opened under your GitHub account. Optionally require independent GitHub reviews as well and enter those reviewer logins, including the [bot] suffix for bots. A PR author cannot approve their own PR on GitHub. Existing reviewer requirements stay enforced until an administrator explicitly changes the policy. Install and authorize each review provider in GitHub; enter its documented comment command when needed.
3. Pencil QA or security reviewers on the task’s board or product. Direct product tasks inherit the product reviewers; board tasks honor their board override or inherited product policy. 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. Optionally enable automatic preparation when tasks enter Review. This starts a preview and requests required reviews once per PR revision, using the policy administrator’s current permissions. It can consume runner capacity and AI credits. It never approves, merges or deploys to production. Failures remain visible with manual build/review recovery.
6. 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 the task and use Review and preview near the top, or choose Review & preview on its board card. The card opens the review panel before attempting any merge. Ship’s Review and ship and the Build inspector use the same release panel.

• Build preview starts an isolated application and backend for the current PR revision. Preview state is always shown: setup required, not built, queued, building, ready, failed or expired. Follow Preview logs for progress, then Open preview when health verification succeeds. Configure PR previews opens this repository’s preview setup; Release settings and recovery links its release history and repair controls. Deployment setup only offers workflows with the selected environment’s release contract. Ordinary test workflows belong in required CI checks, not deployment dispatch. Workflow compatibility does not prove that its host, runner, DNS or certificates have been provisioned.
• Run required 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.
• Check the required specialist review summary for each reviewer’s state and a direct configuration link. 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.