Index of every page on this site: llms.txt
All skills
akdevsaha-dev avatar

/smart-push

@ce26f0a
Run it yourself

Turn local Git changes into clean atomic commits, verify them, push the branch to the user's fork, and open or update a GitHub pull request. Explicit invocation only; supports --dry-run, --draft, --no-pr, --no-push, and --skip-checks.

Use this Skill: https://skilld.dev/gh/akdevsaha-dev/factory-skills/smart-push

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesgithub.md

≈1.6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Remotes, pushing, and pull requests

Topology

Classify each remote using the facts repo-context.sh reports for it: owner, fork_of, permission, and the authenticated viewer. Never trust remote names alone.

Situation Push remote PR target
One remote is the viewer's fork, and another remote points at that fork's parent the fork the parent
The viewer's fork exists, but no remote points at its parent the fork fork_of. Mention that the parent remote is missing.
The only remote is a repo the viewer owns, not a fork that remote the same repo, as a branch PR
The only remote is owned by someone else (org or company), and the viewer has no fork remote stop Explain the situation. Offer to fork with gh repo fork --remote --remote-name fork (needs approval), or to push to that repo directly, but only if the user explicitly asks.
Names are swapped (for example origin is the company repo and upstream is the fork) the fork, whatever it is named its parent. State the mismatch in the approval gate.
Several remotes look like the viewer's fork, the fork's parent doesn't match the target, or ownership can't be determined (for example gh is unavailable) stop Describe what you found and ask which remote is theirs.

An org fork the viewer controls counts as theirs only if the user confirms it.

When the branch already tracks a remote (upstream: in the context output) and that remote passes these rules, keep using it.

Base branch

Pick the first of these that applies:

  1. The user named a base.
  2. The base of an open PR for this branch.
  3. A base that the contribution guide names (for example "target develop").
  4. The target repository's default branch.

Before pushing, compare the branch against the target base:

git fetch <target-remote> <base>
git rev-list --left-right --count <target-remote>/<base>...HEAD   # behind, ahead
git merge-tree --write-tree --name-only <target-remote>/<base> HEAD   # non-zero exit means conflicts; nothing is written

If no remote points at the target, fetch the base by URL into a temporary ref, such as refs/smart-push/base, and delete that ref afterwards.

Being behind the base isn't a blocker. Report it. If conflicts are predicted, list the files and offer to merge the base in, rebase (only if the commits are still unpublished), or open the PR anyway. Don't pick for the user, and never resolve a conflict by choosing a side on your own.

git log <target-remote>/<base>..HEAD must show only the intended commits. If unrelated commits show up, for example from a stale fork main, stop and explain.

Push

git push -u <push-remote> HEAD:refs/heads/<branch>

When the push is rejected:

  • Non-fast-forward: Fetch and compare. If the remote branch has commits you don't have, show them and ask. The options are merging them, rebasing the local unpublished commits, or pushing under a new branch name. Use --force-with-lease only on the user's explicit instruction.
  • Protected branch or ruleset: Report the message as-is. Don't look for a way around it.
  • A pre-push hook failed: Treat it as a failed check (SKILL.md, step 4).
  • 403, or authentication failed: Report which credential failed, and suggest gh auth login, gh auth refresh -s repo, or checking SSH keys. Don't edit the git configuration.

Existing pull requests

Look for open PRs from this head on the target:

gh pr list --repo <target> --head <branch> --state all \
  --json number,state,isDraft,url,title,baseRefName,headRefName,headRepositoryOwner

Count only PRs whose headRepositoryOwner.login is the push remote's owner.

  • Open PR: Pushing updates it, so never open a second one. Edit the title or body only when the new commits change the scope, and show the edit in the approval gate. Keep anything a human added, and prefer appending an "Update" section to rewriting the whole description.
  • The branch's PR was merged or closed: Don't add commits to it. Suggest a new branch from the updated base.

Creating the pull request

gh pr create --repo <target> --base <base> --head <push-owner>:<branch> \
  --title "<title>" --body-file <tmpfile> [--draft]
  • Title: Follow the repository's PR title convention. Otherwise use the main commit's subject, or summarize several commits in the same style.
  • Body: Read the template from the target's base branch, not your working tree (git show <target-remote>/<base>:<path>). Look in .github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md, docs/pull_request_template.md, and .github/PULL_REQUEST_TEMPLATE/*.md (pick the template that fits the change). Fill the template honestly: tick only the boxes that are true, and keep its headings. When there's no template, use only the sections that have something real to say:
## Summary
## Why
## Implementation notes
## Testing
## Breaking changes / migration
## Risks / follow-ups

Under Testing, list the exact commands you ran and their results, plus what you didn't run and why. Don't add a "Generated with" footer or any other AI attribution.

Write the body to a temporary file and pass it with --body-file. Don't use --body with shell-quoted text, because the quoting can mangle it.

If PR creation fails after the push succeeded, the branch is still published. Report that, fix the cause if you can (auth, base name), and retry. Before retrying, check for an existing PR first, so you don't create a duplicate.

gh is missing or unauthenticated

  • git push can still work through the existing git credentials, but you can't confirm ownership without gh. Ask the user to confirm which remote is their fork before pushing.
  • Skip PR creation. Instead, give the compare URL: https://github.com/<target>/compare/<base>...<push-owner>:<branch>?expand=1, along with the drafted title and body, and the command gh auth login.

Non-GitHub hosts

Committing and pushing work the same way. For GitLab, Bitbucket, and other hosts, use their CLI (glab mr create) only if it is installed and authenticated. Otherwise give the merge request URL and the drafted description.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2d3 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    The 'smart-push' skill is a robust, security-conscious development tool designed to automate atomic Git commits and GitHub pull requests. It implements strict 'assume-malicious' safeguards, including automated secret scanning, hygiene checks, and mandatory approval gates before any network operation. The tool explicitly prevents credential leaks, AI attribution, and accidental modification of protected branches.

  • Socket2d

    No alerts

  • Snyk2d

    Risk: MEDIUM · 1 issue

Signed by skilld at ce26f0a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 3 days ago
disable-model-invocation
true

README badge

README badge for akdevsaha-dev/factory-skills/smart-push