From design-skills
Configure or audit a GitHub Actions workflow that turns non-owner pushes into an owner-authored empty commit and optionally triggers a Vercel deploy hook. Use when Codex needs to set up this pattern in any repository, port the workflow between repos, verify that owner empty-commit automation is working, or explain/fix failures involving OWNER_GIT_PAT, VERCEL_DEPLOY_HOOK_URL, skipped owner-triggered runs, GitHub Actions push loops, branch protection, or Vercel deployments that only deploy from owner commits.
How this skill is triggered — by the user, by Claude, or both
Slash command
/design-skills:setup-owner-deploy-triggerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Set up a GitHub Actions workflow that runs when someone other than the repository owner pushes to the deploy branch, then uses the owner's PAT to push an empty commit as the owner and optionally calls a Vercel deploy hook.
Set up a GitHub Actions workflow that runs when someone other than the repository owner pushes to the deploy branch, then uses the owner's PAT to push an empty commit as the owner and optionally calls a Vercel deploy hook.
Use this pattern only when a downstream service needs an owner-originated push or when the repo intentionally wants owner-attributed empty deploy trigger commits. Prefer direct deploy hooks or GitHub App permissions when owner attribution is not required.
github.actor; for org-owned repos, this is usually not the organization slug.OWNER_GIT_PAT containing a PAT owned by that exact PAT owner login. If the PAT is missing, expired, or returning 403, prompt the user with the detailed PAT creation steps in this skill.VERCEL_DEPLOY_HOOK_URL will be added as a repository secret.python /path/to/setup-owner-deploy-trigger/scripts/install_owner_deploy_trigger.py --repo . --owner PAT_OWNER_LOGIN --branch main
.github/workflows/trigger-owner-deploy.yml.Create repository or organization secrets before expecting the workflow to pass.
OWNER_GIT_PAT:
Personal access token generated by the GitHub user used in the workflow guard. A fine-grained token should have access to the target repo and Contents: Read and write. For org-owned repos, the token is still generated by a user account; the token's Resource owner can be the organization that owns the repo. A classic token generally needs repo for private repos. Do not use GITHUB_TOKEN for this pattern because pushes made with GITHUB_TOKEN do not reliably trigger follow-up workflow runs and will not represent the owner PAT identity.
VERCEL_DEPLOY_HOOK_URL:
Vercel deploy hook URL. Required only when the workflow includes the deploy hook step. Store the full URL as a secret; never commit it.
Useful gh commands:
gh secret set OWNER_GIT_PAT --repo OWNER/REPO
gh secret set VERCEL_DEPLOY_HOOK_URL --repo OWNER/REPO
Paste values interactively when prompted. Avoid putting secret values directly in shell history.
OWNER_GIT_PATWhen OWNER_GIT_PAT is missing, failing, or the user asks what token to create, give concrete GitHub UI instructions. Do not ask the user to paste the token into chat. Tell them to create the token in GitHub, copy it once, and add it directly as a repository Actions secret named OWNER_GIT_PAT.
Use this prompt shape:
Create a fine-grained GitHub PAT from the GitHub user account that should act as the owner deploy user. The workflow guard must use this user's login, because GitHub records the PAT user's login as github.actor.
GitHub path:
1. Log in as PAT_OWNER_LOGIN.
2. Click your profile photo in the top-right.
3. Go to Settings.
4. In the left sidebar, open Developer settings.
5. Open Personal access tokens > Fine-grained tokens.
6. Click Generate new token.
Token settings:
- Token name: owner-deploy-REPO_NAME
- Expiration: choose a real expiry, usually 90 days or 1 year.
- Resource owner: select the account or organization that owns OWNER/REPO.
- Repository access: Only select repositories.
- Selected repositories: choose OWNER/REPO.
Repository permissions:
- Contents: Read and write. Required for checkout and pushing the empty commit.
- Metadata: Read-only. GitHub adds this automatically.
- Workflows: Write only if this same PAT will ever push changes to files under .github/workflows. It is not required for the empty commit trigger itself.
- Leave all other repository, organization, and account permissions as No access unless there is a separate reason.
After Generate token:
1. Copy the token immediately; GitHub will not show it again.
2. Go to OWNER/REPO on GitHub.
3. Open Settings > Secrets and variables > Actions.
4. Under Repository secrets, click New repository secret.
5. Name: OWNER_GIT_PAT
6. Secret: paste the token.
7. Click Add secret.
If the repo belongs to an organization and the token shows pending, explain that the organization requires PAT approval. The owner or org admin must approve the token before the workflow can push. If the organization does not appear in the Resource owner dropdown, the org policy may block fine-grained PATs or the logged-in account may not have access.
Generate or maintain a workflow with these properties:
push to the deploy branch and workflow_dispatch.if: github.actor != 'PAT_OWNER_LOGIN'.actions/checkout@v4 with token: ${{ secrets.OWNER_GIT_PAT }}.git user.name and git user.email as the PAT owner login and noreply address.git pull --ff-only before creating the empty commit.git commit --allow-empty -m "chore: trigger deploy" to the same branch.The guard is essential. The owner-created empty commit triggers the workflow again, but the second run must be skipped because the actor is the owner. Without that guard, the workflow can loop.
Use scripts/install_owner_deploy_trigger.py for repeatable setup.
Common commands:
# Infer repo root from current directory, owner from origin URL when possible.
python scripts/install_owner_deploy_trigger.py --repo .
# Explicit owner and branch.
python scripts/install_owner_deploy_trigger.py --repo . --owner creativeaihack --branch main
# Preview without writing.
python scripts/install_owner_deploy_trigger.py --repo . --owner creativeaihack --dry-run
# Omit the Vercel hook step.
python scripts/install_owner_deploy_trigger.py --repo . --owner creativeaihack --skip-vercel-hook
# Overwrite an existing workflow file after review.
python scripts/install_owner_deploy_trigger.py --repo . --owner creativeaihack --force
Prefer explicit --owner when there is any ambiguity around remotes, forks, or mirrors. The installer's --owner value is the PAT owner login used for the workflow guard, not necessarily the repository namespace before /REPO.
After pushing the workflow to GitHub:
gh workflow list --repo OWNER/REPO
gh run list --repo OWNER/REPO --workflow "Owner empty-commit + Vercel deploy" --limit 10
git log --oneline --author PAT_OWNER_LOGIN --grep "chore: trigger deploy" -n 10
Expected behavior:
chore: trigger deploy commit authored and committed as the owner.skipped.If the empty commit does not appear, inspect the failed run logs first, then verify PAT scope, secret name, branch protection, and whether the owner login exactly matches github.actor.
Resource not accessible by integration or checkout/push permission errors:
The PAT is missing, invalid, lacks contents write permission, lacks repo access, or branch protection blocks the token owner.
Workflow loops:
The if: github.actor != 'PAT_OWNER_LOGIN' guard is missing, misspelled, or using a login that does not match the PAT owner.
Vercel hook fails:
The VERCEL_DEPLOY_HOOK_URL secret is missing or invalid, or Vercel has disabled/regenerated the hook.
Push rejected: The branch advanced during the run, branch protection requires checks, signed commits, linear history constraints, or direct pushes by the PAT owner are blocked.
No follow-up workflow after empty commit:
The workflow used GITHUB_TOKEN instead of a PAT, Actions are disabled, or repository workflow permissions block the event.
Before implementing in a repo:
chore: trigger deploy.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub githubanant/skills --plugin design-skills