go-forge/docs/index.md

title	description
go-forge	Full-coverage Go client for the Forgejo API with generics-based CRUD, pagination, and code-generated types.

go-forge

dappco.re/go/core/forge is a Go client library for the Forgejo REST API. It provides typed access to 20 API domains (repositories, issues, pull requests, organisations, milestones, ActivityPub, and more) through a single top-level Forge client. Types are generated directly from Forgejo's swagger.v1.json specification, keeping the library in lockstep with the server.

Module path: dappco.re/go/core/forge Go version: 1.26+ Licence: EUPL-1.2

Quick start

package main

import (
    "context"
    "fmt"
    "log"

    "dappco.re/go/core/forge"
)

func main() {
    // Create a client with your Forgejo URL and API token.
    f := forge.NewForge("https://forge.lthn.ai", "your-token")

    ctx := context.Background()

    // List repositories for an organisation (first page, 50 per page).
    result, err := f.Repos.List(ctx, forge.Params{"org": "core"}, forge.DefaultList)
    if err != nil {
        log.Fatal(err)
    }
    for _, repo := range result.Items {
        fmt.Println(repo.Name)
    }

    // Get a single repository.
    repo, err := f.Repos.Get(ctx, forge.Params{"owner": "core", "repo": "go-forge"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s — %s\n", repo.FullName, repo.Description)
}

Configuration from environment

If you prefer to resolve the URL and token from environment variables rather than hard-coding them, use NewForgeFromConfig:

// Priority: flags > env (FORGE_URL, FORGE_TOKEN) > defaults (http://localhost:3000)
f, err := forge.NewForgeFromConfig("", "", forge.WithUserAgent("my-tool/1.0"))
if err != nil {
    log.Fatal(err) // no token configured
}

Environment variables:

Variable	Purpose	Default
FORGE_URL	Base URL of the Forgejo instance	http://localhost:3000
FORGE_TOKEN	API token for authentication	(none -- required)

Package layout

go-forge/
├── client.go          HTTP client, auth, error handling, rate limits
├── config.go          Config resolution: flags > env > defaults
├── forge.go           Top-level Forge struct aggregating all 20 services
├── resource.go        Generic Resource[T, C, U] for CRUD operations
├── pagination.go      ListPage, ListAll, ListIter — paginated requests
├── params.go          Path variable resolution ({owner}/{repo} -> values)
├── repos.go           RepoService — repositories, forks, transfers, mirrors
├── issues.go          IssueService — issues, comments, labels, reactions
├── pulls.go           PullService — pull requests, merges, reviews
├── orgs.go            OrgService — organisations, members
├── users.go           UserService — users, followers, stars
├── teams.go           TeamService — teams, members, repositories
├── admin.go           AdminService — site admin, cron, user management
├── branches.go        BranchService — branches, branch protections
├── releases.go        ReleaseService — releases, assets, tags
├── labels.go          LabelService — repo and org labels
├── webhooks.go        WebhookService — repo and org webhooks
├── notifications.go   NotificationService — notifications, threads
├── packages.go        PackageService — package registry
├── actions.go         ActionsService — CI/CD secrets, variables, dispatches, tasks
├── contents.go        ContentService — file read/write/delete
├── wiki.go            WikiService — wiki pages
├── misc.go            MiscService — markdown, licences, gitignore, version
├── commits.go         CommitService — statuses, notes
├── milestones.go      MilestoneService — repository milestones
├── activitypub.go     ActivityPubService — ActivityPub actors and inboxes
├── types/             229 generated Go types from swagger.v1.json
│   ├── generate.go    go:generate directive
│   ├── repo.go        Repository, CreateRepoOption, EditRepoOption, ...
│   ├── issue.go       Issue, CreateIssueOption, ...
│   ├── pr.go          PullRequest, CreatePullRequestOption, ...
│   └── ... (36 files total, grouped by domain)
├── cmd/forgegen/      Code generator: swagger spec -> types/*.go
│   ├── main.go        CLI entry point
│   ├── parser.go      Swagger spec parsing, type extraction, CRUD pair detection
│   └── generator.go   Template-based Go source file generation
└── testdata/
    └── swagger.v1.json   Forgejo API specification (input for codegen)

Services

The Forge struct exposes 20 service fields, each handling a different API domain:

Service	Struct	Embedding	Domain
Repos	RepoService	Resource[Repository, ...]	Repositories, forks, transfers
Issues	IssueService	Resource[Issue, ...]	Issues, comments, labels, reactions
Pulls	PullService	Resource[PullRequest, ...]	Pull requests, merges, reviews
Orgs	OrgService	Resource[Organization, ...]	Organisations, members
Users	UserService	Resource[User, ...]	Users, followers, stars
Teams	TeamService	Resource[Team, ...]	Teams, members, repos
Admin	AdminService	(standalone)	Site admin, cron, user management
Branches	BranchService	Resource[Branch, ...]	Branches, protections
Releases	ReleaseService	Resource[Release, ...]	Releases, assets, tags
Labels	LabelService	(standalone)	Repo and org labels
Webhooks	WebhookService	Resource[Hook, ...]	Repo and org webhooks
Notifications	NotificationService	(standalone)	Notifications, threads
Packages	PackageService	(standalone)	Package registry
Actions	ActionsService	(standalone)	CI/CD secrets, variables, dispatches, tasks
Contents	ContentService	(standalone)	File read/write/delete
Wiki	WikiService	(standalone)	Wiki pages
Misc	MiscService	(standalone)	Markdown, licences, gitignore, version
Commits	CommitService	(standalone)	Commit statuses, git notes
Milestones	MilestoneService	(standalone)	Repository milestones
ActivityPub	ActivityPubService	(standalone)	ActivityPub actors and inboxes

Services that embed Resource[T, C, U] inherit List, ListAll, Iter, Get, Create, Update, and Delete methods automatically. Standalone services have hand-written methods because their API endpoints are heterogeneous and do not fit a uniform CRUD pattern.

Dependencies

This module has a small dependency set: dappco.re/go/core and github.com/goccy/go-json, plus the Go standard library (net/http, context, iter, etc.) where appropriate.

module dappco.re/go/core/forge

go 1.26.0