setup-owner-deploy-trigger

Setup Owner Deploy Trigger

Purpose

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.

Fast Path

1. Confirm the desired PAT owner login, target branch, workflow filename, and whether Vercel deploy hook triggering is required. The PAT owner login is the GitHub user that generated the token and will appear as github.actor; for org-owned repos, this is usually not the organization slug.
2. Confirm the repo can use a secret named 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.
3. If Vercel deploy hooks are used, confirm VERCEL_DEPLOY_HOOK_URL will be added as a repository secret.
4. Run the bundled installer from the target repo:

python /path/to/setup-owner-deploy-trigger/scripts/install_owner_deploy_trigger.py --repo . --owner PAT_OWNER_LOGIN --branch main

5. Review the generated .github/workflows/trigger-owner-deploy.yml.
6. Add the secrets in GitHub, commit the workflow, push it, then verify recent Actions runs.

Required Secrets

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.

Prompting the User for OWNER_GIT_PAT

When 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.

Workflow Rules

Generate or maintain a workflow with these properties:

• Trigger on push to the deploy branch and workflow_dispatch.
• Add a job-level guard: if: github.actor != 'PAT_OWNER_LOGIN'.
• Use actions/checkout@v4 with token: ${{ secrets.OWNER_GIT_PAT }}.
• Configure git user.name and git user.email as the PAT owner login and noreply address.
• Pull the latest deploy branch with git pull --ff-only before creating the empty commit.
• Push git commit --allow-empty -m "chore: trigger deploy" to the same branch.
• Optionally call the Vercel deploy hook after the empty commit push.

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.

Installer Script

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.

Verification

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:

• A non-owner push to the deploy branch creates a successful workflow run.
• That run pushes an empty chore: trigger deploy commit authored and committed as the owner.
• The owner empty commit creates a second workflow run that is skipped.
• Owner-originated normal commits are also skipped by the guarded job.

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.

Failure Modes

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.

Safety Checks

Before implementing in a repo:

• Do not commit PATs or deploy hook URLs.
• Do not bypass branch protection unless the owner explicitly accepts that policy.
• Do not use this pattern to hide authorship; explain that git author/committer and GitHub pusher identity/audit logs are related but not identical.
• Keep the commit message boring and searchable, usually chore: trigger deploy.
• Document the reason for the workflow in the workflow name or a nearby comment if the repo has multiple deploy paths.