smaqit-release-git-local

name	smaqit.release-git-local
description	Execute git operations (commit, tag, push) for local releases
metadata	{"version":"0.3.0"}

Release Git Local

Execute all git operations required for a local release: stage changes, commit, create annotated tag, and push to remote.

When to use this skill

Use this skill for local releases (running on a developer's machine) after all files have been prepared. This skill:

• Commits release changes to main branch
• Creates annotated git tag
• Pushes commit and tag to remote repository

Do NOT use this skill for PR-based releases - use release-git-pr instead.

How to execute

Step 1: Check for Uncommitted Work

Check if there are uncommitted changes beyond release preparation files:

git status --porcelain

If working tree has changes:

1. Analyze changes and group by logical purpose
2. Commit each group separately (see Step 1a)
3. Then continue with release commit (Step 2)

If only CHANGELOG.md and version files changed:

• Skip to Step 2 directly

Step 1a: Commit Unreleased Work (If Needed)

CRITICAL: Group changes by purpose, not by file type. Each commit should represent one logical change.

Analyze all changed files:

git --no-pager diff --name-status
git status --short

Common grouping patterns:

Pattern 1: Feature + Documentation

# New feature with related docs
git add src/new_feature.js docs/api.md
git commit -m "Add new feature X"

Pattern 2: Bug Fix

# Bug fix with tests
git add src/buggy_module.js tests/buggy_module.test.js
git commit -m "Fix issue with Y"

Pattern 3: Refactoring/Reorganization

# Moved files or restructured
git add -u old_location/  # stages deletions
git add new_location/
git commit -m "Refactor: move Z to new location"

Pattern 4: Build/Infrastructure

# Build, CI/CD, or tooling changes
git add .github/workflows/ Makefile
git commit -m "Update build workflow"

Guidelines for grouping:

• Each commit should be independently understandable
• Related changes belong together (implementation + tests + docs)
• Separate different logical changes into different commits
• Use descriptive commit messages explaining "why", not just "what"
• Prefix with type if helpful: feat:, fix:, refactor:, docs:, chore:

Example workflow with multiple commit groups:

# Group 1: Infrastructure changes
git add Makefile .github/workflows/
git commit -m "chore: update sync workflow for new structure"

# Group 2: Feature implementation
git add skills/ installer/Makefile
git add -u session-*/ task-*/ test-*/ release-*/  # stages deletions
git commit -m "refactor: consolidate skills into skills/ directory"

# Group 3: Bug fix
git add .github/workflows/post-merge-release.yml
git add -u .github/workflows/post-merge-tag.yml .github/workflows/release.yml
git add agents/smaqit.release.pr.agent.md .github/agents/ README.md
git commit -m "fix: merge workflows to resolve GITHUB_TOKEN trigger issue"

# Group 4: Documentation/support
git add .smaqit/
git commit -m "feat: add task tracking system"

# Now ready for Step 2 (release commit)

After committing work, verify clean state:

git status --porcelain  # Should be empty or only show CHANGELOG/version files

Step 2: Stage Release Preparation Files

Stage ONLY the release preparation changes:

git add CHANGELOG.md

If version files were updated:

git add package.json pyproject.toml installer/main.go

Verify staged changes contain ONLY release preparation:

git --no-pager diff --cached --name-status

Expected output should be minimal (2-3 files max).

Step 3: Commit Release Preparation

Create commit with release message:

git commit -m "Release vX.Y.Z"

Verify commit was created:

git --no-pager log -1 --oneline

Step 4: Create Annotated Tag

Create an annotated tag (not lightweight):

git tag -a vX.Y.Z -m "Release vX.Y.Z"

Why annotated tags?

• Contain metadata (tagger, date, message)
• Recommended for releases by git best practices
• Required by many CI/CD systems for release triggers

Verify tag was created:

git --no-pager tag -l vX.Y.Z

Step 5: Push Commits to Remote

Push the commit to the remote repository:

git push origin main

Replace main with current branch if different.

Step 6: Push Tag to Remote

Push the tag to trigger release workflows:

git push origin vX.Y.Z

Important: Tag push must be separate from commit push for most CI/CD systems to detect release events.

Step 7: Verify Success

Confirm both commit and tag are on remote:

git ls-remote --tags origin vX.Y.Z
git ls-remote origin main

Desktop Linux SSH Agent Recovery

If an explicitly authorized fetch, push, or ls-remote command fails with Permission denied (publickey), sign_and_send_pubkey, or a missing ssh-askpass, use this recovery on an interactive WSL2/WSLg, native Ubuntu/GNOME, or XFCE session. Do not use it in CI or another headless environment.

1. Confirm that origin uses SSH.
2. Discover an already-running agent without changing persistent shell configuration:

   runtime_dir="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
   runtime_dir="${runtime_dir%/}"
   agent_candidates=(
     "$runtime_dir/gcr/ssh"
     "$runtime_dir/keyring/ssh"
   )
   if command -v gpgconf >/dev/null 2>&1; then
     agent_candidates+=("$(gpgconf --list-dirs agent-ssh-socket 2>/dev/null)")
   fi
   agent_candidates+=("${SSH_AUTH_SOCK:-}")
   if command -v systemctl >/dev/null 2>&1; then
     session_socket="$(systemctl --user show-environment 2>/dev/null | sed -n 's/^SSH_AUTH_SOCK=//p')"
     agent_candidates+=("$session_socket")
   fi
   
   agent_socket=""
   for candidate_socket in "${agent_candidates[@]}"; do
     if [[ -n "$candidate_socket" && -S "$candidate_socket" ]] && \
        SSH_AUTH_SOCK="$candidate_socket" ssh-add -l >/dev/null 2>&1; then
       agent_socket="$candidate_socket"
       break
     fi
   done
   test -n "$agent_socket"
   

3. Retry only the exact failed Git command, once:

   SSH_AUTH_SOCK="$agent_socket" git push origin main
   

   GCR or GNOME Keyring may display a WSLg/GNOME unlock dialog; GnuPG or a confirmation-constrained OpenSSH agent may display its configured pinentry or askpass prompt.
4. If no usable socket is found, signing still fails, the command times out, or the prompt was closed, stop and ask the user to reopen/unlock their desktop key store or SSH agent. After confirmation, retry only the failed step.

Do not start or replace agents, persist SSH_AUTH_SOCK, edit shell startup files, load or remove identities, switch the remote to HTTPS, or broaden the Git operation without explicit user direction.

Output

Provide a summary of git operations:

success: true
commit_sha: abc123def456
tag: vX.Y.Z
branch: main
remote_url: https://github.com/owner/repo.git

Output fields:

• success: Boolean indicating all operations completed
• commit_sha: SHA of the release commit
• tag: The git tag created and pushed
• branch: Branch that was pushed to
• remote_url: Remote repository URL

Error Handling

Error	Likely Cause	Suggested Action
nothing to commit	Files unchanged or not staged	Verify changes were made and staged correctly
tag 'vX.Y.Z' already exists	Tag created in previous attempt	Delete local tag: git tag -d vX.Y.Z, then retry
rejected - non-fast-forward	Remote has commits not in local	Pull latest: git pull origin main, then retry
Permission denied (publickey)	SSH key unavailable or its desktop store is locked	On interactive desktop Linux, try the single command-scoped agent recovery above; otherwise ask the user to configure or unlock credentials
sign_and_send_pubkey failed	Agent can list the key but cannot sign with it	Ask the user to reopen/unlock the desktop key store or SSH agent, then retry only the failed step
remote: Permission to repo denied	No push access to repository	Verify repository permissions
fatal: tag 'vX.Y.Z' already exists on remote	Tag already pushed previously	Version conflict - check CHANGELOG.md

Recovery steps:

If commit succeeded but tag creation failed:

# Fix the issue, then resume from Step 3
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

If commit and tag succeeded but push failed:

# Fix the issue, then resume from Step 4
git pull origin main  # if non-fast-forward
git push origin main
git push origin vX.Y.Z

If tag already exists locally:

git tag -d vX.Y.Z  # Delete local tag
# Then retry from Step 3

Notes

• This skill is for local development releases only
• For PR-based workflows, use release-git-pr skill instead
• All operations happen on the local machine with standard git credentials
• Commits should be grouped logically, not dumped together - each commit tells a story
• Release preparation (CHANGELOG + version) should be its own separate commit
• Both commit and tag must be pushed for release to be complete
• Tag push typically triggers CI/CD release workflows (GitHub Actions, etc.)
• Never force push (-f) release commits or tags
• If any step fails, stop immediately and report the error - do not continue beyond the single scoped desktop Linux SSH retry described above
• Good commit hygiene makes git history useful for understanding project evolution