Gitea Go SDK

Overview

The official Go SDK for Gitea provides 332+ API methods with full type safety. Use it for bots, automation, integrations, and complex workflows. For quick CLI operations, use gitea:tea-cli instead.

Quick Setup

import "code.gitea.io/sdk/gitea"

// Create client
client, err := gitea.NewClient(
    "https://gitea.example.com",
    gitea.SetToken("your-token"),
)

go get code.gitea.io/sdk/gitea

See references/authentication.md in tea-cli for token creation.

Quick Reference

| Task | Method | |------|--------| | Repos | | | List my repos | client.ListMyRepos(ListReposOptions{}) | | Get repo | client.GetRepo(owner, repo) | | Create repo | client.CreateRepo(CreateRepoOption{}) | | Issues | | | List issues | client.ListRepoIssues(owner, repo, ListIssueOption{}) | | Create issue | client.CreateIssue(owner, repo, CreateIssueOption{}) | | Edit issue | client.EditIssue(owner, repo, index, EditIssueOption{}) | | PRs | | | List PRs | client.ListRepoPullRequests(owner, repo, ListPullRequestsOptions{}) | | Create PR | client.CreatePullRequest(owner, repo, CreatePullRequestOption{}) | | Merge PR | client.MergePullRequest(owner, repo, index, MergePullRequestOption{}) | | Releases | | | List releases | client.ListReleases(owner, repo, ListReleasesOptions{}) | | Create release | client.CreateRelease(owner, repo, CreateReleaseOption{}) |

API Categories

See references/api-reference.md for complete method list:

• Repositories (70+ methods)
• Issues & comments (50+ methods)
• Pull requests & reviews (40+ methods)
• Releases & attachments
• Organizations & teams
• Users, webhooks, actions

Common Types

See references/types.md for struct definitions:

• Repository, Issue, PullRequest, Release
• User, Organization, Team
• ListOptions for pagination
• Option structs for create/edit

Patterns

See references/examples.md for idiomatic patterns:

• Error handling
• Pagination
• Context usage
• Webhook handlers

Authentication Options

// Token auth (recommended)
client, _ := gitea.NewClient(url, gitea.SetToken(token))

// Basic auth
client, _ := gitea.NewClient(url, gitea.SetBasicAuth(user, pass))

// With 2FA
client, _ := gitea.NewClient(url,
    gitea.SetBasicAuth(user, pass),
    gitea.SetOTP(otp),
)

// SSH key
client, _ := gitea.NewClient(url,
    gitea.UseSSHPubkey(fingerprint, keyPath, passphrase),
)

Common Patterns

// Pagination
opts := gitea.ListOptions{Page: 1, PageSize: 50}
for {
    repos, resp, _ := client.ListMyRepos(gitea.ListReposOptions{ListOptions: opts})
    // process repos...
    if resp.NextPage == 0 {
        break
    }
    opts.Page = resp.NextPage
}

// Context support
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
client.SetContext(ctx)

Common Mistakes

| Problem | Solution | |---------|----------| | Nil pointer panic | Always check error before using result | | Missing pagination | Use resp.NextPage to get all results | | Context timeout | Set appropriate timeout for bulk operations | | Rate limiting | Check resp.Header for rate limit info |