GitHub Repo Management with Hermes Agent: Clone, Create, Fork, Release

This skill is the operational core for anyone who lives on GitHub through Hermes Agent. It covers the full lifecycle of a repository: cloning, creating, forking, configuring, protecting branches, managing secrets, cutting releases, and driving Actions workflows. You will reach for this whenever a task starts with "get that repo", "make a new project", or "ship a release", and you want it done without leaving the agent's environment. It is bundled with Hermes Agent, so it is available out of the box, and it pairs with the github-auth skill to handle credentials.

What it does

In practice, this skill gives you two parallel ways to do the same thing. The first uses the gh CLI, which is concise and handles authentication for you. The second uses raw git and curl against the GitHub REST API, which works in environments where gh is not installed but a token is available. Every section shows both, so you can pick whichever fits your current shell.

The skill is not just about cloning. It walks through creating repositories under your user or an organization, forking with an upstream remote, inspecting repo metadata, editing settings like descriptions and topics, enforcing branch protection, storing Actions secrets, publishing releases with assets, monitoring and re-running workflows, and even creating gists. The quick reference table at the end condenses all of that into a cheat sheet.

Before you start

The only stated prerequisite is that you are authenticated with GitHub. The github-auth skill handles that, and this skill's setup script detects which authentication path is available.

Setup

The setup block below is meant to be run once at the start of a session. It decides whether to use gh or fall back to git plus curl. If gh is installed and authenticated, it sets AUTH="gh". Otherwise it looks for a GITHUB_TOKEN in the environment, then in $HERMES_HOME/.env, then in ~/.git-credentials. It also resolves your GitHub username, which several later operations need.

if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
  if [ -z "$GITHUB_TOKEN" ]; then
    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(uv run python "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py")
    fi
  fi
fi

# Get your GitHub username (needed for several operations)
if [ "$AUTH" = "gh" ]; then
  GH_USER=$(gh api user --jq '.login')
else
  GH_USER=$(curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user | python -c "import sys,json; print(json.load(sys.stdin)['login'])")
fi

If you are already inside a repository, the next block extracts the owner and repo name from the origin remote. That saves you from typing them repeatedly in the curl examples that follow.

REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)

1. Cloning Repositories

Cloning is pure git, so it works identically whether you have gh or not. The examples cover the common variants: HTTPS with a credential helper, cloning into a specific directory, shallow clones for large repos, cloning a specific branch, and SSH when you have keys configured.

# Clone via HTTPS (works with credential helper or token-embedded URL)
git clone https://github.com/owner/repo-name.git

# Clone into a specific directory
git clone https://github.com/owner/repo-name.git ./my-local-dir

# Shallow clone (faster for large repos)
git clone --depth 1 https://github.com/owner/repo-name.git

# Clone a specific branch
git clone --branch develop https://github.com/owner/repo-name.git

# Clone via SSH (if SSH is configured)
git clone git@github.com:owner/repo-name.git

With gh (shorthand):

gh repo clone owner/repo-name
gh repo clone owner/repo-name -- --depth 1

The gh form is shorter and automatically uses your authenticated identity. The -- after the repo name passes flags through to git, so you can combine it with any git clone option.

2. Creating Repositories

Creating a repo is where the two paths diverge most. With gh, one command creates and optionally clones. The --clone flag clones immediately, and --source . --push turns an existing local directory into a new remote repo.

With gh:

# Create a public repo and clone it
gh repo create my-new-project --public --clone

# Private, with description and license
gh repo create my-new-project --private --description "A useful tool" --license MIT --clone

# Under an organization
gh repo create my-org/my-new-project --public --clone

# From existing local directory
cd /path/to/existing/project
gh repo create my-project --source . --public --push

With git + curl:

The curl path posts to the API, then either clones the empty repo or pushes an existing directory. Note the auto_init: true in the payload, which creates an initial commit so the repo is not empty.

# Create the remote repo via API
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user/repos \
  -d '{
    "name": "my-new-project",
    "description": "A useful tool",
    "private": false,
    "auto_init": true,
    "license_template": "mit"
  }'

# Clone it
git clone https://github.com/$GH_USER/my-new-project.git
cd my-new-project

# -- OR -- push an existing local directory to the new repo
cd /path/to/existing/project
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/$GH_USER/my-new-project.git
git push -u origin main

To create under an organization, the endpoint changes from /user/repos to /orgs/{org}/repos.

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/orgs/my-org/repos \
  -d '{"name": "my-new-project", "private": false}'

From a Template

Starting from a template repo is a one-liner with gh. The curl version hits the generate endpoint and needs your username in the payload.

With gh:

gh repo create my-new-app --template owner/template-repo --public --clone

With curl:

curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/owner/template-repo/generate \
  -d '{"owner": "'"$GH_USER"'", "name": "my-new-app", "private": false}'

3. Forking Repositories

Forking with gh is a single command that clones the fork for you. The curl path creates the fork via API, waits a few seconds for GitHub to provision it, then clones and adds the original as upstream.

With gh:

gh repo fork owner/repo-name --clone

With git + curl:

# Create the fork via API
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/owner/repo-name/forks

# Wait a moment for GitHub to create it, then clone
sleep 3
git clone https://github.com/$GH_USER/repo-name.git
cd repo-name

# Add the original repo as "upstream" remote
git remote add upstream https://github.com/owner/repo-name.git

Keeping a Fork in Sync

The pure git sequence fetches from upstream, merges into your local main, and pushes to your fork. The gh shortcut does the same in one command.

# Pure git — works everywhere
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

With gh (shortcut):

gh repo sync $GH_USER/repo-name

4. Repository Information

You often need to know what a repo is before you clone it. The gh commands give you a view, a list, and a search. The curl versions parse the JSON with Python and print a readable summary.

With gh:

gh repo view owner/repo-name
gh repo list --limit 20
gh search repos "machine learning" --language python --sort stars

With curl:

# View repo details
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO \
  | python -c "
import sys, json
r = json.load(sys.stdin)
print(f\"Name: {r['full_name']}\")
print(f\"Description: {r['description']}\")
print(f\"Stars: {r['stargazers_count']}  Forks: {r['forks_count']}\")
print(f\"Default branch: {r['default_branch']}\")
print(f\"Language: {r['language']}\")"

# List your repos
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/user/repos?per_page=20&sort=updated" \
  | python -c "
import sys, json
for r in json.load(sys.stdin):
    vis = 'private' if r['private'] else 'public'
    print(f\"  {r['full_name']:40}  {vis:8}  {r.get('language', ''):10}  ★{r['stargazers_count']}\")"

# Search repos
curl -s \
  "https://api.github.com/search/repositories?q=machine+learning+language:python&sort=stars&per_page=10" \
  | python -c "
import sys, json
for r in json.load(sys.stdin)['items']:
    print(f\"  {r['full_name']:40}  ★{r['stargazers_count']:6}  {r['description'][:60] if r['description'] else ''}\")"

Note that the search endpoint does not require authentication, so the curl example omits the auth header.

5. Repository Settings

Editing settings is where gh repo edit shines. You can change the description, visibility, wiki and issues toggles, default branch, topics, and auto-merge in one or two commands. The curl path uses PATCH for most fields and a separate PUT for topics.

With gh:

gh repo edit --description "Updated description" --visibility public
gh repo edit --enable-wiki=false --enable-issues=true
gh repo edit --default-branch main
gh repo edit --add-topic "machine-learning,python"
gh repo edit --enable-auto-merge

With curl:

curl -s -X PATCH \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO \
  -d '{
    "description": "Updated description",
    "has_wiki": false,
    "has_issues": true,
    "allow_auto_merge": true
  }'

# Update topics
curl -s -X PUT \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.mercy-preview+json" \
  https://api.github.com/repos/$OWNER/$REPO/topics \
  -d '{"names": ["machine-learning", "python", "automation"]}'

The topics endpoint needs a custom Accept header, which is included above.

6. Branch Protection

Branch protection is a curl-only section in this skill; there is no gh equivalent shown. The first command reads the current protection rules, the second applies a new set. The payload requires status checks, disables admin enforcement, and requires one approving review.

# View current protection
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/branches/main/protection

# Set up branch protection
curl -s -X PUT \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/branches/main/protection \
  -d '{
    "required_status_checks": {
      "strict": true,
      "contexts": ["ci/test", "ci/lint"]
    },
    "enforce_admins": false,
    "required_pull_request_reviews": {
      "required_approving_review_count": 1
    },
    "restrictions": null
  }'

7. Secrets Management (GitHub Actions)

Secrets are where the two paths differ most in effort. With gh, setting, listing, and deleting secrets is trivial. The curl path requires encrypting the value with the repo's public key using PyNaCl, which is why the skill itself notes that gh is dramatically simpler.

With gh:

gh secret set API_KEY --body "your-secret-value"
gh secret set SSH_KEY < ~/.ssh/id_rsa
gh secret list
gh secret delete API_KEY

With curl:

Secrets require encryption with the repo's public key, more involved via API:

# Get the repo's public key for encrypting secrets
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/secrets/public-key

# Encrypt and set (requires Python with PyNaCl)
python -c "
from base64 import b64encode
from nacl import encoding, public
import json, sys

# Get the public key
key_id = '<key_id_from_above>'
public_key = '<base64_key_from_above>'

# Encrypt
sealed = public.SealedBox(
    public.PublicKey(public_key.encode('utf-8'), encoding.Base64Encoder)
).encrypt('your-secret-value'.encode('utf-8'))
print(json.dumps({
    'encrypted_value': b64encode(sealed).decode('utf-8'),
    'key_id': key_id
}))"

# Then PUT the encrypted secret
curl -s -X PUT \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/secrets/API_KEY \
  -d '<output from python script above>'

# List secrets (names only, values hidden)
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/secrets \
  | python -c "
import sys, json
for s in json.load(sys.stdin)['secrets']:
    print(f\"  {s['name']:30}  updated: {s['updated_at']}\")"

Note: For secrets, gh secret set is dramatically simpler. If setting secrets is needed and gh isn't available, recommend installing it for just that operation.

8. Releases

Releases are a common end-of-task action. With gh, you can create a release with auto-generated notes, mark it as draft or prerelease, attach a binary, list releases, and download assets. The curl path posts to the releases endpoint, then uploads assets to a separate uploads URL.

With gh:

gh release create v1.0.0 --title "v1.0.0" --generate-notes
gh release create v2.0.0-rc1 --draft --prerelease --generate-notes
gh release create v1.0.0 ./dist/binary --title "v1.0.0" --notes "Release notes"
gh release list
gh release download v1.0.0 --dir ./downloads

With curl:

# Create a release
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/releases \
  -d '{
    "tag_name": "v1.0.0",
    "name": "v1.0.0",
    "body": "## Changelog\n- Feature A\n- Bug fix B",
    "draft": false,
    "prerelease": false,
    "generate_release_notes": true
  }'

# List releases
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/releases \
  | python -c "
import sys, json
for r in json.load(sys.stdin):
    tag = r.get('tag_name', 'no tag')
    print(f\"  {tag:15}  {r['name']:30}  {'draft' if r['draft'] else 'published'}\")"

# Upload a release asset (binary file)
RELEASE_ID=<id_from_create_response>
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  "https://uploads.github.com/repos/$OWNER/$REPO/releases/$RELEASE_ID/assets?name=binary-amd64" \
  --data-binary @./dist/binary-amd64

9. GitHub Actions Workflows

This section turns Hermes Agent into a CI operator. You can list workflows, inspect runs, view failed logs, re-run jobs, and trigger manual dispatches. The gh commands are concise; the curl versions give you the same control with more steps.

With gh:

gh workflow list
gh run list --limit 10
gh run view <RUN_ID>
gh run view <RUN_ID> --log-failed
gh run rerun <RUN_ID>
gh run rerun <RUN_ID> --failed
gh workflow run ci.yml --ref main
gh workflow run deploy.yml -f environment=staging

With curl:

# List workflows
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/workflows \
  | python -c "
import sys, json
for w in json.load(sys.stdin)['workflows']:
    print(f\"  {w['id']:10}  {w['name']:30}  {w['state']}\")"

# List recent runs
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/actions/runs?per_page=10" \
  | python -c "
import sys, json
for r in json.load(sys.stdin)['workflow_runs']:
    print(f\"  Run {r['id']}  {r['name']:30}  {r['conclusion'] or r['status']}\")"

# Download failed run logs
RUN_ID=<run_id>
curl -s -L \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/logs \
  -o /tmp/ci-logs.zip
cd /tmp && unzip -o ci-logs.zip -d ci-logs

# Re-run a failed workflow
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/rerun

# Re-run only failed jobs
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/runs/$RUN_ID/rerun-failed-jobs

# Trigger a workflow manually (workflow_dispatch)
WORKFLOW_ID=<workflow_id_or_filename>
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/workflows/$WORKFLOW_ID/dispatches \
  -d '{"ref": "main", "inputs": {"environment": "staging"}}'

10. Gists

Gists are a lightweight way to share snippets. The skill covers creating a public gist and listing your gists.

With gh:

gh gist create script.py --public --desc "Useful script"
gh gist list

With curl:

# Create a gist
curl -s -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/gists \
  -d '{
    "description": "Useful script",
    "public": true,
    "files": {
      "script.py": {"content": "print(\"hello\")"}
    }
  }'

# List your gists
curl -s \
  -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/gists \
  | python -c "
import sys, json
for g in json.load(sys.stdin):
    files = ', '.join(g['files'].keys())
    print(f\"  {g['id']}  {g['description'] or '(no desc)':40}  {files}\")"

Quick Reference Table

Action	gh	git + curl
Clone	gh repo clone o/r	git clone https://github.com/o/r.git
Create repo	gh repo create name --public	curl POST /user/repos
Fork	gh repo fork o/r --clone	curl POST /repos/o/r/forks + git clone
Repo info	gh repo view o/r	curl GET /repos/o/r
Edit settings	gh repo edit --...	curl PATCH /repos/o/r
Create release	gh release create v1.0	curl POST /repos/o/r/releases
List workflows	gh workflow list	curl GET /repos/o/r/actions/workflows
Rerun CI	gh run rerun ID	curl POST /repos/o/r/actions/runs/ID/rerun
Set secret	gh secret set KEY	curl PUT /repos/o/r/actions/secrets/KEY (+ encryption)

When not to use it

The source does not list explicit exclusions, but the pattern is clear: if you only need to clone a public repo and never touch settings, releases, or Actions, plain git clone is enough and this skill is overkill. Likewise, if you are not authenticated, the curl fallback will fail on any authenticated endpoint, so you should run github-auth first.

Limits and gotchas

• The setup script assumes python is available for parsing JSON in the curl examples. If your environment only has python3, you may need to adjust the commands.
• The fork sync sequence assumes your default branch is main. If the upstream uses master, change the checkout and merge lines accordingly.
• The secrets encryption path requires PyNaCl. The skill itself recommends installing gh just for that operation, which is a strong hint that the curl path is a last resort.
• The release asset upload uses a placeholder RELEASE_ID; you must capture the ID from the create response before uploading.
• The workflow dispatch endpoint expects a workflow ID or filename; the example uses a placeholder.
• The branch protection PUT replaces the entire protection rule set. If you already have rules, you may need to merge them into the payload.

What pairs with this

This skill is part of a family. The github-auth skill provides the authentication that this skill's setup script relies on. github-pr-workflow handles pull requests, which naturally follow forking and branch protection. github-issues covers issue management, useful when you are triaging a repo you just cloned. Together they cover the full GitHub workflow from authentication to merged PRs and releases.