hermes-agent/skills/devops/gitea-workflow-automation/SKILL.md

name, title, description, trigger

name	title	description	trigger
gitea-workflow-automation	Gitea Workflow Automation	Automate Gitea issues, PRs, and repository workflows via the API for forge CI and backlog tracking.	When creating Gitea issues, pull requests, or automating forge repository workflows.

Gitea Workflow Automation

Trigger

Use this skill when automating Gitea operations: creating issues, opening PRs, checking repository state, or integrating Gitea into CI/backlog workflows.

Prerequisites

• GITEA_URL environment variable set (e.g., https://forge.alexanderwhitestone.com)
• GITEA_TOKEN environment variable with a valid API token
• GITEA_USER or explicit owner/org name
• curl and jq available in the environment

Step-by-Step Workflow

1. Verify Environment

: "${GITEA_URL?}" "${GITEA_TOKEN?}" "${GITEA_USER?}"
echo "Gitea env OK"

2. List Issues in a Repository

curl -s -H "Authorization: token ${GITEA_TOKEN}" \
  "${GITEA_URL}/api/v1/repos/${OWNER}/${REPO}/issues?state=open&limit=50" | jq '.[] | {number, title, state}'

3. Create an Issue

curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  "${GITEA_URL}/api/v1/repos/${OWNER}/${REPO}/issues" \
  -d "{\"title\":\"${TITLE}\",\"body\":\"${BODY}\",\"assignees\":[\"${ASSIGNEE}\"]}

• Escape newlines in BODY if passing inline; prefer a JSON file for multi-line bodies.

4. Create a Pull Request

curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  "${GITEA_URL}/api/v1/repos/${OWNER}/${REPO}/pulls" \
  -d "{\"title\":\"${TITLE}\",\"body\":\"${BODY}\",\"head\":\"${BRANCH}\",\"base\":\"${BASE_BRANCH}\"}"

5. Check PR Status / Diff

curl -s -H "Authorization: token ${GITEA_TOKEN}" \
  "${GITEA_URL}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}" | jq '{number, title, state, mergeable}'

6. Push Code Before Opening PR

git checkout -b "${BRANCH}"
git add .
git commit -m "${COMMIT_MSG}"
git push origin "${BRANCH}"

7. Add Comments to Issues/PRs

curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  "${GITEA_URL}/api/v1/repos/${OWNER}/${REPO}/issues/${NUMBER}/comments" \
  -d "{\"body\":\"${COMMENT_BODY}\"}"

Verification Checklist

• Environment variables are exported and non-empty
• API responses are parsed with jq to confirm success
• Issue/PR numbers are captured from the JSON response for cross-linking
• Branch exists on remote before creating a PR
• Multi-line bodies are written to a temp JSON file to avoid escaping hell

Pitfalls

• Trailing slashes in GITEA_URL: Ensure GITEA_URL does not end with / or double slashes break URLs.
• Branch not pushed: Creating a PR for a local-only branch returns 422.
• Escape hell: For multi-line issue/PR bodies, write JSON to a file with cat <<EOF > /tmp/payload.json and pass @/tmp/payload.json to curl instead of inline strings.
• Token scope: If operations fail with 403, verify the token has repo or write:issue scope.
• Pagination: Default limit is 30 issues; use ?limit=100 or paginate with page= for large backlogs.

Example: Full Issue Creation with File Body

cat <<'EOF' > /tmp/issue.json
{
  "title": "[Bezalel] Forge Health Check",
  "body": "Build a diagnostic scanner for artifact integrity and permissions.\n\n- Detect .pyc without .py source\n- Detect world-readable sensitive files\n- Output JSON for CI consumption",
  "assignees": ["bezalel"],
  "labels": ["enhancement", "security"]
}
EOF
curl -s -X POST -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  "${GITEA_URL}/api/v1/repos/Timmy_Foundation/hermes-agent/issues" \
  -d @/tmp/issue.json | jq '.number'