Git Publish

Push the current project to a GitHub remote repository with a single workflow.

intent

publish code to github by resolving the remote url, initializing git if needed, committing uncommitted changes with auto-generated conventional commit messages, and pushing to the correct branch. use this skill whenever the user wants to push code to github, publish to a remote, upload a project to github, set up remote tracking, or says things like "push to github", "publish this repo", "上传到GitHub", "推送到GitHub". the skill handles git initialization, remote setup, auto-commit of uncommitted changes, and pushing with automatic fallback from https to ssh on connection failures.

inputs

environment variables or secrets:

• GITHUB_TOKEN (optional): personal access token for HTTPS authentication. if not set, the skill falls back to SSH key authentication or prompts for credentials.
• SSH key in ~/.ssh/id_rsa or equivalent: required for SSH protocol fallback and authentication.

external connections:

• GitHub API: accessed via git over HTTPS or SSH. requires network connectivity and valid authentication.

files and context:

• references/repo-map.json (relative to skill directory): local path to github url mappings. format is a json object where keys are absolute project paths and values are github urls.
• current working directory: the project to be published. must be readable and writable.

user input:

• github repository url (if not found in repo-map.json). accepted formats: https://github.com/user/repo.git, git@github.com:user/repo.git, https://github.com/user/repo.

procedure

step 1: resolve the remote url

1. read the file at references/repo-map.json. if the file does not exist, create an empty json object.
2. get the absolute path of the current working directory.
3. check if the current path exists as a key in the repo mapping.
   • input: absolute project path, repo-map.json contents.
   • output: github url or null.
4. if a mapping is found, use the stored url. inform the user: "detected repository for this project: , using it directly."
5. if no mapping is found, prompt the user: "provide github repository url (e.g., https://github.com/user/repo.git):". accept the provided url.
   • input: user response.
   • output: github url (https or ssh format).

step 2: check and initialize git if needed

1. run git status in the current directory.
   • input: current working directory.
   • output: exit code (0 if git repo, non-zero if not).
2. if exit code is non-zero (not a git repository):
   • run git init.
   • run git add . to stage all files.
   • run git commit -m "Initial commit".
   • run git remote add origin <url> where is the resolved github url.
   • detect the default branch name (usually main or master) and run git branch -M <branch-name> to rename the current branch.
   • input: project files, resolved github url, detected branch name.
   • output: initialized git repository with origin remote configured.
3. if exit code is zero (already a git repository):
   • run git remote get-url origin to check if origin remote exists.
   • if origin remote exists:
     • compare the returned url against the resolved github url.
     • if urls differ, ask the user: "the existing remote url differs. update it to ? (y/n)". if user agrees, run git remote set-url origin <new-url>. if user declines, proceed with the existing url.
   • if origin remote does not exist (error returned), run git remote add origin <url>.
   • input: current git state, resolved github url, user confirmation (if needed).
   • output: git repository with origin remote matching the resolved github url.

step 3: handle uncommitted changes

1. run git status --porcelain to detect uncommitted changes.
   • input: current git state.
   • output: list of changed files (may be empty).
2. if the output is non-empty:
   • run git diff --cached to show staged changes.
   • run git diff to show unstaged changes.
   • input: git diffs.
   • output: diff content (used to generate commit message).
   • run git add . to stage all changes.
   • analyze the staged changes and generate a commit message following conventional commit format: type(scope): brief summary. use types: feat (new feature), fix (bug fix), chore (maintenance), docs, refactor, style, test. keep title under 50 characters. include a body listing affected files and what changed.
   • input: staged changes, diff content.
   • output: conventional commit message string.
   • run git commit -m "<generated message>".
   • input: commit message.
   • output: committed changes in git history.
3. if the output is empty (no uncommitted changes):
   • proceed directly to step 4 (push).

step 4: push to github

1. run git branch --show-current to detect the current branch name.
   • input: current git state.
   • output: branch name string (e.g., "main").
2. attempt normal push: git push -u origin <branch>.
   • input: branch name, git history, origin remote.
   • output: exit code (0 on success, non-zero on failure), error message if applicable.
3. if push succeeds, proceed to step 5.
4. if push fails:
   • check the error message for connection errors: "could not connect to server", "failed to connect", timeout, network unreachable, etc.
   • if a connection error is detected:
     • run git remote get-url origin to inspect the current remote url.
     • if the url starts with https://:
       • retry push up to 3 times with a 2-second pause between retries: git push -u origin <branch>.
       • if all 3 retries fail, convert the url to ssh format: https://github.com/user/repo.git becomes git@github.com:user/repo.git.
       • run git remote set-url origin git@github.com:user/repo.git.
       • attempt push again: git push -u origin <branch>.
       • input: branch name, remote url, connection status.
       • output: push success or final connection error.
     • if the url starts with git@ (already ssh):
       • retry push up to 3 times with a 2-second pause between retries: git push -u origin <branch>.
       • if all 3 retries fail, report the connection error to the user.
       • input: branch name, ssh connection status.
       • output: error message for user.
   • if the error is not a connection error (e.g., divergent histories, non-fast-forward):
     • present the error to the user.
     • ask: "normal push failed. use force push? this may overwrite remote history. (y/n)"
     • input: user confirmation.
     • output: force push attempt or abort.
     • if user agrees (y):
       • run git push -u origin <branch> --force.
       • input: branch name, force flag.
       • output: force push result.
     • if user declines (n):
       • stop and report the situation to the user.
       • input: user decline.
       • output: abort message.

step 5: save the mapping and confirm success

1. after a successful push:
   • read the file at references/repo-map.json. if the file does not exist, start with an empty json object.
   • add or update the entry: key is the absolute path of the project directory, value is the resolved github url.
   • write the updated json back to the file.
   • input: project path, github url, existing repo-map.json contents.
   • output: updated repo-map.json file.
2. confirm success to the user:
   • report the remote url used.
   • report the branch that was pushed.
   • report the commit message(s) that were pushed (use git log -1 --pretty=format:"%H %s" to get the latest commit hash and message).
   • input: push result, git history.
   • output: confirmation message to user.

decision points

if no mapping is found in repo-map.json: ask the user to provide the github repository url. accept https or ssh formats.

if a git repository does not exist: initialize git, stage all files, create an initial commit, and add the origin remote.

if a git repository exists but has no origin remote: add the origin remote with the resolved github url.

if a git repository exists and has an origin remote that differs from the resolved url: ask the user to confirm before updating the remote url.

if uncommitted changes exist: stage all changes, auto-generate a conventional commit message based on the diff, and commit before pushing.

if the push fails with a connection error and the remote is https: retry up to 3 times, then automatically switch to ssh protocol and retry.

if the push fails with a connection error and the remote is already ssh: retry up to 3 times, then report the error.

if the push fails for non-connection reasons (divergent histories, non-fast-forward): ask the user whether to force push. only force push if the user explicitly agrees.

output contract

success state:

• github repository receives the pushed commits on the specified branch.
• references/repo-map.json is updated with the project path and github url mapping.
• user receives confirmation message containing:
  • the remote url used.
  • the branch name that was pushed.
  • the latest commit hash and message(s) that were pushed.
• no uncommitted changes remain in the local repository.

file locations:

• references/repo-map.json: updated to include the current project path and github url.
• git history in the current working directory: includes new commits (if changes were staged) and remote tracking reference updated to track the pushed branch.

data format:

• repo-map.json: json object with absolute paths as keys and github urls as values. example:

  {
    "/home/user/project1": "https://github.com/user/project1.git",
    "/home/user/project2": "git@github.com:user/project2.git"
  }
  

outcome signal

the user knows the skill worked when:

1. the terminal shows [new branch] <branch-name> -> origin/<branch-name> or branch '<branch-name>' set up to track 'origin/<branch-name>' (or similar git push confirmation for subsequent pushes).
2. the user receives a confirmation message listing the remote url, branch name, and commit message(s) that were pushed.
3. navigating to the github repository in a browser shows the pushed commits on the specified branch with the correct commit messages.
4. running git log --oneline locally shows the new commits in the history.
5. running git remote -v shows the correct origin url pointing to github.
6. references/repo-map.json now contains an entry mapping the current project path to the github url.