Forgejo/Codeberg API Skill

Automates Forgejo repository operations using the REST API (v1). Compatible with Codeberg and self-hosted Forgejo instances.

When to Use

Activate when you need to:

• Read or write files in a Forgejo/Codeberg repository
• Create/update/close issues or pull requests
• List branches, tags, commits, or releases
• Search repositories or users
• Trigger CI/CD via repository dispatch
• Automate any git-forge operation

Prerequisites

pip install httpx python-dotenv

Authentication

Set FORGEJO_TOKEN (or CODEBERG_TOKEN) in your environment or .env file. Generate at: Forgejo/Codeberg → Settings → Applications → Generate Token.

Required scopes per operation:

export FORGEJO_TOKEN=your_token_here
# or place in .env at project root

Base URL Configuration

The skill defaults to Codeberg (https://codeberg.org/api/v1). For self-hosted Forgejo instances, set FORGEJO_BASE_URL:

export FORGEJO_BASE_URL=https://forgejo.example.com/api/v1

Base URL & Headers

Base URL : https://codeberg.org/api/v1 (default)
Auth     : Authorization: token <FORGEJO_TOKEN>
Content  : Content-Type: application/json

Commands

CLI Usage (from project root)

# List repos for a user
python .agents/skills/codeberg-api/scripts/forgejo_api.py repos --owner username

# Get file contents
python .agents/skills/codeberg-api/scripts/forgejo_api.py get-file \
  --owner username --repo myrepo \
  --path README.md --branch main

# Create an issue
python .agents/skills/codeberg-api/scripts/forgejo_api.py create-issue \
  --owner username --repo myrepo \
  --title "Bug: xyz" --body "Description"

# List open issues
python .agents/skills/codeberg-api/scripts/forgejo_api.py list-issues \
  --owner username --repo myrepo --state open

# Create or update a file
python .agents/skills/codeberg-api/scripts/forgejo_api.py put-file \
  --owner username --repo myrepo \
  --path docs/test.md --content "# Hello" \
  --message "docs: add test file" --branch main

Standalone Usage (from skill directory)

cd .agents/skills/codeberg-api
python scripts/forgejo_api.py --help

Common API Patterns

Read a file

curl -H "Authorization: token $FORGEJO_TOKEN" \
  "https://codeberg.org/api/v1/repos/{owner}/{repo}/contents/{filepath}?ref=main"

Response contains content (base64-encoded) and sha (needed for updates).

Create/update a file

curl -X PUT -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  "https://codeberg.org/api/v1/repos/{owner}/{repo}/contents/{filepath}" \
  -d '{"message":"commit msg","content":"<base64>","sha":"<existing_sha_or_omit>"}'

Create an issue

curl -X POST -H "Authorization: token $FORGEJO_TOKEN" \
  -H "Content-Type: application/json" \
  "https://codeberg.org/api/v1/repos/{owner}/{repo}/issues" \
  -d '{"title":"Issue title","body":"Body text"}'

List branches

curl "https://codeberg.org/api/v1/repos/{owner}/{repo}/branches"

Error Handling

Forgejo Actions (CI/CD)

Forgejo uses Forgejo Actions for CI/CD, fully compatible with GitHub Actions.

Workflow Location

Place workflows in .forgejo/workflows/ directory.

Example: Build Workflow

name: Build
version: "0.2.10"
on: [push, pull_request]
jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test
      - name: Build
        run: npm run build

Best Practices (2026)

• Use matrix builds for parallel testing
• Enable caching for dependencies
• Use branch protection with required workflows
• Leverage secrets for API tokens (FORGEJO_TOKEN)

Bundled Scripts

• scripts/forgejo_api.py — Main CLI tool for Forgejo API operations

See Also

• git-github-workflow — GitHub workflow and PR lifecycle
• cicd-pipeline — CI/CD pipeline design

Rationalizations

Red Flags

• Committing FORGEJO_TOKEN or any secrets to the repository
• Skipping SHA fetch before file updates — causes 409 Conflict errors
• Not checking token scopes when receiving 403 Forbidden responses

References

• agents-docs/SKILLS.md - Skill authoring guide

Voice & Context

• Default: professional + blog
• Reference: voice-profiles skill for definitions and auto-detection.