codeberg-api

name	codeberg-api
version	0.2.10
category	platform
description	Interact with Forgejo/Codeberg repositories via the REST API — read or write files, manage issues, create pull requests, list branches/tags, search repos, and automate CI/CD workflows. Use this skill when the user wants to interact with a Forgejo or Codeberg repository, even if they just say "read a file from Codeberg" or "create an issue on my Forgejo repo". Not for GitHub (use git-github-workflow) or GitLab (use cicd-pipeline).
license	MIT
compatibility	Requires Python 3.10+, httpx or requests. Needs FORGEJO_TOKEN env var for write operations.
allowed-tools	Bash(python:*|curl:*) Read
metadata	{"author":"d.o.","version":"1.0","spec":"agentskills.io","triggers":["forgejo","codeberg","forgejo issue","forgejo pr","forgejo branch","forgejo repo","forgejo actions"]}

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:

Operation	Scope needed
Read public repos	(none, token optional)
Read private repos	read:repository
Write files / create PRs	write:repository
Manage issues	write:issue
Read user info	read:user

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

HTTP Status	Meaning	Action
401	Unauthorized	Check FORGEJO_TOKEN
403	Forbidden	Check token scopes
404	Not found	Verify owner/repo/path
409	Conflict	SHA mismatch on file update — fetch current SHA first
422	Validation error	Check request body fields
429	Rate limited	Wait and retry with backoff

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

Rationalization	Reality
"I'll hardcode the token in the script for convenience."	Hardcoded tokens leak into version control and logs; always use environment variables or .env files.
"The API is the same as GitHub — I'll just use GitHub patterns."	Forgejo/Codeberg API has different endpoints, auth scopes, and error codes; copying GitHub patterns silently fails.

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.