gitea-sdk-rs

中文文档

An async Rust SDK for the Gitea REST API, with full coverage of repositories, issues, pull requests, organizations, users, admin operations, and more.

Installation

Add this to your Cargo.toml:

[dependencies]
gitea-sdk-rs = "0.1.0"

Feature Flags

Quick Start

use gitea_sdk_rs::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder("https://gitea.example.com")
        .token("your-token-here")
        .build()?;

    let (user, _) = client.users().get_my_info().await?;
    println!("Logged in as: {}", user.user_name);

    Ok(())
}

More examples are in the examples/ directory:

cargo run --example basic_usage
cargo run --example authentication

API Overview

Repository Management

ReposApi — Full repository lifecycle and contents management.

• CRUD — create_repo, get_repo, edit_repo, delete_repo, search_repos
• Branches — list_branches, create_branch, delete_branch, list_branch_protections
• Tags — list_tags, create_tag, delete_tag, list_tag_protections
• Files — get_contents, create_file, update_file, delete_file, get_raw_file
• Collaborators — list_collaborators, add_collaborator, get_collaborator_permission
• Commits — list_commits, get_single_commit, compare_commits
• Actions — list_action_secrets, list_action_variables, create_action_secret
• Wiki — create_wiki_page, get_wiki_page, edit_wiki_page, list_wiki_pages
• Misc — list_forks, create_fork, mirror_sync, transfer_repo, get_archive

ReleasesApi — Releases and attachments.

• list, create, edit, delete, get_by_tag, list_attachments, create_attachment

Issues & Pull Requests

IssuesApi — Full issue tracking with rich metadata.

• CRUD — list_repo_issues, create_issue, edit_issue, delete_issue
• Comments — list_issue_comments, create_issue_comment, edit_issue_comment
• Labels — get_issue_labels, add_issue_labels, replace_issue_labels
• Milestones — list_repo_milestones, create_milestone, edit_milestone
• Reactions — post_issue_reaction, post_issue_comment_reaction
• Dependencies — list_issue_dependencies, create_issue_dependency
• Time Tracking — add_time, list_issue_tracked_times, list_my_tracked_times
• Subscriptions — list_issue_subscribers, add_issue_subscription
• Pins — list_repo_pinned_issues, pin_issue, unpin_issue

PullsApi — Pull request workflow.

• CRUD — list, get, create, edit
• Merge — merge, is_merged, patch, diff
• Reviews — list_reviews, create_review, submit_review, dismiss_review
• Files — list_commits, list_files

Users & Organizations

UsersApi — User profiles, keys, and social features.

• Profile — get, get_my_info, search, get_settings, update_settings
• Keys — list_public_keys, create_public_key, list_gpg_keys, create_gpg_key
• Social — follow, unfollow, list_followers, block_user, unblock_user
• Email — list_emails, add_email, delete_email
• Tokens — list_access_tokens, create_access_token, delete_access_token

OrgsApi — Organization and team management.

• CRUD — list_orgs, create_org, edit_org, delete_org
• Teams — list_org_teams, create_team, add_team_member, add_team_repo
• Members — list_org_membership, set_public_org_membership
• Labels — list_org_labels, create_org_label
• Actions — list_org_action_secrets, list_org_action_variables
• Blocks — list_org_blocks, block_org_user, unblock_org_user

System & Administration

AdminApi — Server administration (requires admin privileges).

• Users — list_users, create_user, edit_user, delete_user
• Orgs — list_orgs, create_org_for_user
• Cron — list_cron_tasks, run_cron_task
• Hooks — list_hooks, create_hook, edit_hook
• Repos — list_unadopted_repos, adopt_unadopted_repo
• Badges — list_user_badges, add_user_badges

SettingsApi — get_api_settings, get_repo_settings, get_ui_settings

MiscApi — get_version, render_markdown, list_gitignore_templates, list_license_templates, get_signing_key_gpg

Other Modules

Authentication

use gitea_sdk_rs::Client;

// Personal access token
let client = Client::builder("https://gitea.example.com")
    .token("your-token-here")
    .build()?;

// Username and password
let client = Client::builder("https://gitea.example.com")
    .basic_auth("username", "password")
    .build()?;

// Token with two-factor OTP
let client = Client::builder("https://gitea.example.com")
    .token("your-token-here")
    .otp("123456")
    .build()?;

// Act as another user (sudo)
let client = Client::builder("https://gitea.example.com")
    .token("your-token-here")
    .sudo("target-username")
    .build()?;

The client is thread-safe and supports swapping credentials at runtime via set_token(), set_basic_auth(), set_otp(), and set_sudo().

Pagination

List endpoints accept option structs that embed pagination parameters:

use gitea_sdk_rs::ListOptions;
use gitea_sdk_rs::options::repo::ListReposOptions;

let opts = ListReposOptions {
    list_options: ListOptions {
        page: Some(1),
        page_size: Some(50),
    },
};
let (repos, _) = client.repos().list_my_repos(opts).await?;

Set page to Some(0) to disable pagination and fetch all results at once.

Error Handling

All API methods return Result<(T, Response)> where T is the deserialized response body and Response contains HTTP status, headers, and pagination links.

use gitea_sdk_rs::{Client, Error};

async fn example(client: &Client) {
    match client.repos().get_repo("owner", "repo").await {
        Ok((repo, response)) => {
            println!("Repo: {}", repo.name);
            println!("Status: {}", response.status);
        }
        Err(Error::Http(status, msg)) => {
            eprintln!("HTTP {status}: {msg}");
        }
        Err(e) => {
            eprintln!("Error: {e}");
        }
    }
}

Minimum Rust Version

Requires Rust 1.88 or later (edition 2024).

License

Licensed under the MIT License.

Links

• API Documentation (docs.rs)
• Repository (GitHub)
• Changelog
• Gitea API Reference