go-scm

Module: forge.lthn.ai/core/go-scm
Go: 1.25.5
Licence: EUPL-1.2

Multi-platform source control abstraction for the Core ecosystem. Provides unified Forgejo and Gitea clients, AgentCI orchestration via the Clotho Protocol, parallel git operations, a poll-dispatch job runner, and a data collection subsystem.

Package Structure

Package	Import Path	Purpose
`forge/`	`forge.lthn.ai/core/go-scm/forge`	Forgejo SDK wrapper -- repos, issues, PRs, labels, webhooks, organisations
`gitea/`	`forge.lthn.ai/core/go-scm/gitea`	Gitea SDK wrapper -- repos, issues, PRs, mirrors
`agentci/`	`forge.lthn.ai/core/go-scm/agentci`	Clotho Protocol orchestration, agent config, security utilities
`git/`	`forge.lthn.ai/core/go-scm/git`	Multi-repo parallel status, push, pull operations
`jobrunner/`	`forge.lthn.ai/core/go-scm/jobrunner`	Signal polling, handler dispatch, JSONL audit journal
`jobrunner/forgejo/`	`forge.lthn.ai/core/go-scm/jobrunner/forgejo`	Forgejo-specific job source (epic polling)
`jobrunner/handlers/`	`forge.lthn.ai/core/go-scm/jobrunner/handlers`	Built-in handlers: dispatch, completion, merge, draft publish, fix commands, tick parent
`collect/`	`forge.lthn.ai/core/go-scm/collect`	Data collection: GitHub issues, BitcoinTalk scraping, CoinGecko market data, IACR/arXiv papers

Quick Start

Forgejo Client

import "forge.lthn.ai/core/go-scm/forge"

// Create from explicit credentials
client, err := forge.New("https://forge.lthn.ai", "your-token")

// Or resolve from config file / env vars / flags
client, err := forge.NewFromConfig("", "")

// Use the client
user, err := client.GetCurrentUser()
issues, err := client.ListIssues("core", "go-scm", forge.ListIssuesOpts{State: "open"})

Gitea Client

import "forge.lthn.ai/core/go-scm/gitea"

client, err := gitea.New("https://git.lthn.ai", "your-token")
repos, err := client.ListOrgRepos("Agentic")

Multi-Repo Git Status

import "forge.lthn.ai/core/go-scm/git"

statuses := git.Status(ctx, git.StatusOptions{
    Paths: []string{"/path/to/repo-a", "/path/to/repo-b"},
    Names: map[string]string{"/path/to/repo-a": "repo-a"},
})

for _, s := range statuses {
    if s.IsDirty() {
        fmt.Printf("%s has %d modified, %d untracked files\n", s.Name, s.Modified, s.Untracked)
    }
}

Job Runner

import (
    "forge.lthn.ai/core/go-scm/jobrunner"
    forgejoSource "forge.lthn.ai/core/go-scm/jobrunner/forgejo"
    "forge.lthn.ai/core/go-scm/jobrunner/handlers"
)

poller := jobrunner.NewPoller(jobrunner.PollerConfig{
    Sources:      []jobrunner.JobSource{forgejoSource.New(cfg, forgeClient)},
    Handlers:     []jobrunner.JobHandler{handlers.NewEnableAutoMergeHandler(forgeClient)},
    Journal:      journal,
    PollInterval: 60 * time.Second,
})

poller.Run(ctx) // Blocking poll-dispatch loop

Dependencies

Dependency	Version	Purpose
`codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2`	v2.2.0	Forgejo API SDK
`code.gitea.io/sdk/gitea`	v0.23.2	Gitea API SDK
`forge.lthn.ai/core/go`	workspace	Core framework (config, logging, services)
`golang.org/x/net`	v0.50.0	HTML parsing for collect package

Key Features

Dual SCM support -- identical patterns for Forgejo and Gitea with shared auth resolution
Clotho Protocol -- dual-run verification for critical repositories, configurable per-agent
Epic-driven pipeline -- polls epic issues, discovers child tasks, dispatches to agents via SSH
Built-in handlers -- auto-merge, draft publishing, review dismissal, fix commands, parent checkbox ticking
Data collection -- GitHub, BitcoinTalk, CoinGecko, IACR, arXiv with rate limiting and resume support
Parallel git ops -- concurrent status checks across dozens of repositories
JSONL audit journal -- date-partitioned, path-traversal-safe logging of all pipeline actions
Security hardened -- path sanitisation, shell argument escaping, strict SSH, token masking

Wiki Pages

Forge-Client -- Forgejo API wrapper and configuration
Gitea-Client -- Gitea API wrapper and configuration
AgentCI-and-Clotho -- Agent orchestration and the Clotho Protocol
Git-Operations -- Multi-repo git utilities and Core service integration
Job-Runner -- Signal polling, handler dispatch, and built-in handlers
Data-Collection -- GitHub, BitcoinTalk, market data, and paper collection