Clowderlabs Capabilities & Forgejo API Guide 🐾

Welcome to the Clowderlabs Forgejo guide! This repository serves as an interactive reference for developers, administrators, CI/CD runners, and integration scripts to explore and interact with the git hosting infrastructure at git.clowderlabs.com.

---

🚀 The Forgejo Platform at a Glance

Forgejo is a community-driven, self-hosted Git service (a fork of Gitea). It is lightweight, fast, and feature-complete, offering:

• 📦 Built-in Package Registries (npm, PyPI, Cargo, Docker, NuGet, etc.)
• 🔄 Built-in CI/CD (Forgejo Actions) compatible with GitHub Actions syntax
• 🌐 Federated Social Features using the ActivityPub protocol
• 🛡️ Full REST API (300+ endpoints) for total programmatic interaction

---

🧑‍💻 Guide for Developers

Here is how to get started interacting with the platform:

1. Account Setup

User accounts on Clowderlabs are integrated with the Authentik single sign-on provider.

• To log in via the web interface, click Sign In and choose the authentik option.
• Keep your profile settings updated under git.clowderlabs.com/user/settings.

2. Configure SSH Keys

To interact with repositories via your terminal, add your public key:

1. Go to Settings > SSH / GPG Keys (git.clowderlabs.com/user/settings/keys).
2. Paste your SSH public key (e.g., id_ed25519.pub).
3. Verify your SSH connection using:

   ssh -T git@git.clowderlabs.com
   

   Expected response: Hi there, <username>! You've successfully authenticated with the key... but Forgejo does not provide shell access.

3. Creating Repositories & Collaboration

• Create a repository from the + dropdown on the top-right corner.
• Use Issues and Pull Requests inside repositories to discuss changes and review code.

4. Repository Wiki & Documentation

Forgejo repositories include a built-in Wiki for hosting project documentation.

• Enable/Disable: Enable the wiki via repository Settings > Repository under the Units section.
• Editing Pages:
  • Web Interface: Create and edit pages directly in your browser.
  • Local Git Clone: The wiki is a standalone Git repository. You can clone it locally and push Markdown files:

    git clone https://git.clowderlabs.com/{owner}/{repo}.wiki.git
    # Or via SSH:
    git clone git@git.clowderlabs.com:{owner}/{repo}.wiki.git
    

• Permissions: Wiki permissions match the repository's access level.

---

🤖 Guide for API Integrations & Automations

If you are writing scripts, configuring custom automation workflows, or integrating API clients, you can use the Forgejo REST API. Here is how to authenticate and invoke it.

1. API Authentication

The REST API is hosted at /api/v1. It does not accept SSH key auth. You must authenticate using a Personal Access Token (PAT) in the HTTP headers:

• Base URL: https://git.clowderlabs.com/api/v1
• HTTP Header format:

  Authorization: token <your_personal_access_token>
  Accept: application/json
  

Tip

You can generate API tokens for scripts and integrations under Settings > Applications (git.clowderlabs.com/user/settings/applications).

2. Core REST API Domains

Forgejo organizes its API into several key functional modules:

API Domain	Endpoints	Key Capabilities
repository	188	Create/delete repos, write/read files directly without cloning, manage branch protection
issue & pull	67	Create issues, post review comments, merge pull requests
organization	69	Manage team members, public/private visibility, and org repos
notification	7	Poll unread events (GET /notifications?unread=true)
package	6	Search, query, and delete package registry uploads
settings	4	Inspect global instance parameters (attachment limits, maximum sizes)

---

🛠️ Code Examples for Automations

A. Read/Write Repository Files Directly

You can push code directly using HTTP requests without invoking shell commands or cloning the repository:

import requests
import base64

TOKEN = "YOUR_TOKEN_HERE"
API_URL = "https://git.clowderlabs.com/api/v1"
headers = {"Authorization": f"token {TOKEN}", "Accept": "application/json"}

# Commit a file
content = base64.b64encode(b"print('Hello from Automation!')\n").decode("utf-8")
payload = {
    "content": content,
    "message": "add automation script",
    "branch": "main"
}
# Replace {owner} and {repo} with target repository details
r = requests.post(f"{API_URL}/repos/{owner}/{repo}/contents/script.py", json=payload, headers=headers)
print("File committed status:", r.status_code)

B. Poll Notifications (Event Loop)

Keep your automation tool responsive to issue mentions and pull request reviews:

import requests

TOKEN = "YOUR_TOKEN_HERE"
headers = {"Authorization": f"token {TOKEN}"}

r = requests.get("https://git.clowderlabs.com/api/v1/notifications?unread=true", headers=headers)
if r.status_code == 200:
    for item in r.json():
        print(f"[{item['repository']['full_name']}] {item['subject']['title']} ({item['subject']['type']})")

---

📦 PyPI Package Registry

Forgejo includes a built-in PyPI package registry to publish and install Python packages privately or publicly under a user or organization namespace.

1. Configuration & Authentication

Choose your tool of choice (standard tools or the modern uv manager).

Option A: Using Twine (Classic)

Configure your repository credentials in ~/.pypirc. Using a Personal Access Token (PAT) as the password is highly recommended:

[distutils]
index-servers =
    clowder

[clowder]
repository = https://git.clowderlabs.com/api/packages/{owner}/pypi
username = {username}
password = {your_personal_access_token}

Replace {owner}, {username}, and {your_personal_access_token} with your Clowderlabs details.

Option B: Using uv

With uv, you configure the private index in your project's pyproject.toml.

1. Add the index to pyproject.toml:

[[tool.uv.index]]
name = "clowder"
url = "https://git.clowderlabs.com/api/packages/{owner}/pypi/simple"

2. Authenticate using environment variables (do not hardcode credentials in pyproject.toml):

export UV_INDEX_CLOWDER_USERNAME="{username}"
export UV_INDEX_CLOWDER_PASSWORD="{your_personal_access_token}"

---

2. Publishing Packages

Option A: Using Twine (Classic)

Build your package distribution files, then upload them using twine:

python3 -m pip install --upgrade twine build
python3 -m build
python3 -m twine upload --repository clowder dist/*

Option B: Using uv

To build and publish with uv:

# Build the project
uv build

# Publish using your credentials
export UV_PUBLISH_USERNAME="{username}"
export UV_PUBLISH_PASSWORD="{your_personal_access_token}"
uv publish --index https://git.clowderlabs.com/api/packages/{owner}/pypi

Warning

Forgejo does not allow overwriting an existing package version. If you need to re-upload the same version, you must first delete the existing version via the web interface or the Packages API.

---

3. Installing Packages

Option A: Using pip (Classic)

To install packages from the Clowderlabs PyPI registry, specify the --index-url with your credentials:

pip install --index-url https://{username}:{your_personal_access_token}@git.clowderlabs.com/api/packages/{owner}/pypi/simple {package_name}

Important

To prevent Dependency Confusion attacks (where pip might look up internal packages in the public PyPI registry), always use --index-url instead of --extra-index-url. --index-url forces pip to only look in your specified registry.

Option B: Using uv

If your index is configured in pyproject.toml as shown above, you can install packages normally:

uv add {package_name}

To prevent dependency confusion and ensure a specific internal package is only pulled from Clowderlabs, define it as a source in your pyproject.toml:

[tool.uv.sources]
{package_name} = { index = "clowder" }

Alternatively, you can install ad-hoc without pyproject.toml configuration by using the pip interface compatibility layer:

uv pip install {package_name} --index-url https://{username}:{your_personal_access_token}@git.clowderlabs.com/api/packages/{owner}/pypi/simple

---

⚡ Forgejo Actions (CI/CD)

Forgejo Actions is built-in and uses standard YAML files located in .forgejo/workflows/ or .github/workflows/.

# Example workflow: .forgejo/workflows/test.yaml
name: Test and Build
on: [push]
jobs:
  build:
    runs-on: docker
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Run Tests
        run: python -m unittest discover

Secrets and Variables for Actions

Users and tools can configure Actions environments using the REST API:

• Create/Update Secret: PUT /repos/{owner}/{repo}/actions/secrets/{secret_name}
• Create/Update Variable: PUT /repos/{owner}/{repo}/actions/variables/{var_name}

---

🔗 Useful Links

• Interactive Swagger Docs: git.clowderlabs.com/api/swagger
• Official Forgejo Documentation: forgejo.org/docs