stack/packages/mosaic/framework/skills/mosaic-deploy/SKILL.md

name, description

name	description
mosaic-deploy	Full end-to-end deployment flow: push branch → open PR → wait for CI → merge → deploy using the path documented by the stack. Use when deploying a feature branch to production or staging, or when asked to ship a completed feature.

mosaic-deploy

End-to-end deployment flow.

Full Deploy Sequence

push branch → open PR → CI passes → merge → documented deploy path

Step 1: Push branch and open PR

cd ~/src/<repo>-worktrees/<task-slug>
git push -u origin <branch>
~/.config/mosaic/tools/git/pr-create.sh -t "feat: ..." -b "..." -i <issue#>
# Note the PR number from output

Step 2: Wait for CI

~/.config/mosaic/tools/git/pr-ci-wait.sh -n <pr#>

If CI fails, check:

source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials woodpecker
~/.config/mosaic/tools/woodpecker/pipeline-status.sh -r <org>/<repo>

Step 3: Merge

cd ~/src/<repo>
~/.config/mosaic/tools/git/pr-merge.sh -n <pr#> -d

Always merge through pr-merge.sh: it runs the CI queue guard first and pins the merge to the reviewed head. If branch protection blocks the merge, that is a gate telling you something — a failing check, a moved head, or a missing review. Fix the cause; never route around it with a raw API call, a shared credential, or force_merge. Exceptional cases go to the operator or the coordinating seat, still merged through the wrapper.

Step 4: Deploy Through the Documented Path

Read the stack README before deploying:

• If it documents docker stack deploy on the manager, use that deploy path and its verification procedure.
• Use Portainer only when the estate holds a Portainer credential. Do not propose Portainer otherwise.

For an authorized Portainer deployment:

source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name> -p

Check a Portainer deployment:

~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
~/.config/mosaic/tools/portainer/stack-logs.sh -n <stack-name> -l 50

Optional Portainer Stack Map

For deployments that use Portainer, maintain a project → stack-name mapping in a skills-local override of this skill (local copies take precedence over the shipped canonical one). Example shape:

Project	Stack Name
sample-app	sample-app
sample-api	sample-api-prod

Notes

• Workers open PRs but never merge — orchestrator or Merge Guard handles step 3+
• Docker Swarm image pinning: -p does not change a digest-pinned image. Follow the stack README's documented deployment procedure.
• Worktrees: all coding work in ~/src/<repo>-worktrees/<task-slug>, never in main checkout
• Always clean up worktree after push: git worktree remove ~/src/<repo>-worktrees/<task-slug>