forgejo_clients

Comprehensive Rust client library for Forgejo/Gitea with Rhai scripting, MCP server, and demo data generation.

Features

• Forgejo/Gitea REST API Client - Type-safe HTTP client for all Forgejo operations
• Rhai Scripting - Execute scripts with Forgejo integration via forgejo-client binary
• MCP Server - Run as an MCP (Model Context Protocol) server for AI integration
• Demo Data - Generate test data for development and testing
• Async/Await - Full async runtime support with Tokio

Packages

• client - Main Forgejo client library with optional rhai and mcp features
• runners - Scripts for setting up Forgejo CI runners

Installation

Quick Install

Download and install the latest binaries for your platform:

curl -sSL https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-runner/dev/install.sh | bash

This will:

• Detect your OS and architecture (macOS/Linux, arm64/amd64)
• Download the latest forgejo-client and forgejo-runner binaries
• Install them to ~/hero/bin/
• Make them executable

After installation, add the binaries to your PATH:

export PATH="$HOME/hero/bin:$PATH"

Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export PATH="$HOME/hero/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Manual Installation

Download binaries directly from the package registry:

macOS (Apple Silicon):

mkdir -p ~/hero/bin
curl -L -o ~/hero/bin/forgejo-client https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-client/dev/forgejo-client-darwin-arm64
curl -L -o ~/hero/bin/forgejo-runner https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-runner/dev/forgejo-runner-darwin-arm64
chmod +x ~/hero/bin/forgejo-*

macOS (Intel):

mkdir -p ~/hero/bin
curl -L -o ~/hero/bin/forgejo-client https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-client/dev/forgejo-client-darwin-amd64
curl -L -o ~/hero/bin/forgejo-runner https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-runner/dev/forgejo-runner-darwin-amd64
chmod +x ~/hero/bin/forgejo-*

Linux (x86_64):

mkdir -p ~/hero/bin
curl -L -o ~/hero/bin/forgejo-client https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-client/dev/forgejo-client-linux-amd64
curl -L -o ~/hero/bin/forgejo-runner https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-runner/dev/forgejo-runner-linux-amd64
chmod +x ~/hero/bin/forgejo-*

Linux (ARM64):

mkdir -p ~/hero/bin
curl -L -o ~/hero/bin/forgejo-client https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-client/dev/forgejo-client-linux-arm64
curl -L -o ~/hero/bin/forgejo-runner https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-runner/dev/forgejo-runner-linux-arm64
chmod +x ~/hero/bin/forgejo-*

Quick Start

Prerequisites

Note: Our clients depend on features which are not installed in the standard Forgejo server.

For testing with a demo deployment, see: https://forge.ourworld.tf/lhumina_research/forgejo_fork

Run run_test.sh which sets up:

• Forgejo instance at http://localhost:3000
• Admin user: forgejo_admin / admin
• Test user: testuser / testuser

Using the Rhai Script Runner

# Execute a single Rhai script
forgejo-client script.rhai [args...]

# Run all scripts in a directory
forgejo-client --dir ./scripts

# Syntax check scripts without executing
forgejo-client --test ./scripts

Example script (get_user.rhai):

#!/usr/bin/env forgejo-client

let client = new_forgejo_client("http://localhost:3000")
    .token(env("FORGEJO_TOKEN"))
    .connect()?;

let user = client.get_current_user()?;
print(`Logged in as: ${user.login}`);

Running the MCP Server

# Start MCP server on default address (127.0.0.1:3659)
export FORGEJO_URL=http://localhost:3000
export FORGEJO_TOKEN=your_token_here
forgejo-client --mcp

# Start on custom address
forgejo-client --mcp --bind 0.0.0.0:5000

The server outputs connection information for Claude Desktop and other MCP clients.

Using the Client Library

use ourforge_client::{ForgejoClient, FeedConfig, demo_feed};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = ForgejoClient::new(
        "http://localhost:3000",
        "your_token_here"
    )?;

    // Get current user
    let user = client.get_current_user().await?;
    println!("User: {}", user.login);

    // Generate demo data
    let result = demo_feed(&client, FeedConfig::default()).await?;
    println!("Created {} users, {} orgs, {} repos",
        result.users_created,
        result.orgs_created,
        result.repos_created
    );

    Ok(())
}

Available Operations

Repository Management

• list_my_repos, list_org_repos, get_repo
• create_repo, create_org_repo
• delete_repo

Issue Tracking

• list_issues, get_issue, create_issue
• update_issue, delete_issue

Labels & Milestones

• list_labels, get_label, create_label, delete_label
• list_milestones, get_milestone, create_milestone, delete_milestone

Organizations

• list_my_orgs, list_orgs, get_org
• create_org, delete_org
• list_org_members

Users (Admin)

• get_current_user, get_user
• list_users, create_user, delete_user

Teams

• list_org_teams, get_team, create_team, delete_team
• add_team_member, remove_team_member, list_team_members

Demo Data

The demodata module provides utilities for generating and testing demo data:

use ourforge_client::{demo_feed, demo_test, FeedConfig, TestConfig};

// Populate with demo data
let feed_result = demo_feed(&client, FeedConfig::default()).await?;

// Validate the data
let test_result = demo_test(&client, TestConfig::default()).await?;

Setting Up Forgejo Runners

See runners/README.md for instructions on:

• Registering your machine as a Forgejo runner
• Installing and running the runner service
• Using Rhai scripts with the runner

Building

# Build client only
cargo build -p ourforge_client

# Build with Rhai scripting support
cargo build -p ourforge_client --features rhai

# Build with MCP server support
cargo build -p ourforge_client --features mcp

# Build with all features
cargo build -p ourforge_client --all-features

Environment Variables

• FORGEJO_URL - Base URL of the Forgejo instance (default: http://localhost:3000)
• FORGEJO_TOKEN - API token for authentication (required for most operations)

License

See LICENSE file for details