feat(install): add Gitea platform support with API fast path

Support Gitea (gitea.com and self-hosted instances) as a git hosting
platform for installing skills. Includes both core platform integration
and a Gitea Contents API fast path for direct file downloads without
full git clone.

Platform support (P0):
- auth.go: add PlatformGitea, detect gitea hosts, resolve GITEA_TOKEN
- config.go / project.go: add gitea_hosts config field with normalization,
  env var merge (SKILLSHARE_GITEA_HOSTS), and EffectiveGiteaHosts()
- source.go: add isGiteaHost() and GiteaHosts to ParseOptions
- install.go: pass GiteaHosts from config to source parsing
- install_git.go: include GITEA_TOKEN in auth error hints

API fast path (P1):
- gitea_download.go: Gitea Contents API recursive directory download
  (GET /api/v1/repos/{owner}/{repo}/contents/{path}), matching the
  GitHub Contents API pattern
- install_apply.go / install_discovery.go: hook Gitea API fallback
  after sparse checkout, before full clone
This commit is contained in:
zishuo
2026-05-26 19:00:25 +08:00
parent 17a9a0879b
commit ce9593e98e
9 changed files with 380 additions and 2 deletions
+2
View File
@@ -253,6 +253,7 @@ func parseOptsFromConfig(cfg *config.Config) install.ParseOptions {
GitLabHosts: cfg.EffectiveGitLabHosts(),
AzureHosts: cfg.EffectiveAzureHosts(),
CNBHosts: cfg.EffectiveCNBHosts(),
GiteaHosts: cfg.EffectiveGiteaHosts(),
}
}
@@ -262,6 +263,7 @@ func parseOptsFromProjectConfig(cfg *config.ProjectConfig) install.ParseOptions
GitLabHosts: cfg.EffectiveGitLabHosts(),
AzureHosts: cfg.EffectiveAzureHosts(),
CNBHosts: cfg.EffectiveCNBHosts(),
GiteaHosts: cfg.EffectiveGiteaHosts(),
}
}
+21
View File
@@ -279,6 +279,7 @@ type Config struct {
GitLabHosts []string `yaml:"gitlab_hosts,omitempty"`
AzureHosts []string `yaml:"azure_hosts,omitempty"`
CNBHosts []string `yaml:"cnb_hosts,omitempty"`
GiteaHosts []string `yaml:"gitea_hosts,omitempty"`
// PreserveTildeOnSave folds $HOME prefixes back to ~ when serializing the
// config to YAML. Useful when the config is shared via dotfiles across
@@ -364,6 +365,11 @@ func (c *Config) EffectiveCNBHosts() []string {
return mergeCNBHostsFromEnv(c.CNBHosts)
}
// EffectiveGiteaHosts returns GiteaHosts merged with SKILLSHARE_GITEA_HOSTS env var.
func (c *Config) EffectiveGiteaHosts() []string {
return mergeGiteaHostsFromEnv(c.GiteaHosts)
}
// IsTUIEnabled reports whether interactive TUI is enabled.
// nil (absent from config) is treated as true for backward compatibility.
func (c *Config) IsTUIEnabled() bool {
@@ -512,6 +518,13 @@ func Load() (*Config, error) {
}
cfg.CNBHosts = cnbHosts
// Validate and normalize gitea_hosts
giteaHosts, err := normalizeGiteaHosts(cfg.GiteaHosts)
if err != nil {
return nil, err
}
cfg.GiteaHosts = giteaHosts
// Migrate legacy flat target fields to skills: sub-key (one-time, persisted immediately)
if migrateTargetConfigs(cfg.Targets) {
if data, err := marshalYAML(&cfg); err == nil {
@@ -775,6 +788,10 @@ func normalizeCNBHosts(hosts []string) ([]string, error) {
return normalizeHostList(hosts, "cnb_hosts")
}
func normalizeGiteaHosts(hosts []string) ([]string, error) {
return normalizeHostList(hosts, "gitea_hosts")
}
// mergeHostsFromEnv merges comma-separated env var entries with config file hosts.
// Invalid entries in the env var are silently skipped.
func mergeHostsFromEnv(configHosts []string, envKey string) []string {
@@ -812,6 +829,10 @@ func mergeCNBHostsFromEnv(configHosts []string) []string {
return mergeHostsFromEnv(configHosts, "SKILLSHARE_CNB_HOSTS")
}
func mergeGiteaHostsFromEnv(configHosts []string) []string {
return mergeHostsFromEnv(configHosts, "SKILLSHARE_GITEA_HOSTS")
}
func normalizeAuditBlockThreshold(v string) (string, error) {
threshold := strings.ToUpper(strings.TrimSpace(v))
if threshold == "" {
+13
View File
@@ -274,6 +274,7 @@ type ProjectConfig struct {
GitLabHosts []string `yaml:"gitlab_hosts,omitempty"`
AzureHosts []string `yaml:"azure_hosts,omitempty"`
CNBHosts []string `yaml:"cnb_hosts,omitempty"`
GiteaHosts []string `yaml:"gitea_hosts,omitempty"`
}
// EffectiveSkillsSource returns the resolved skills source directory.
@@ -345,6 +346,11 @@ func (c *ProjectConfig) EffectiveCNBHosts() []string {
return mergeCNBHostsFromEnv(c.CNBHosts)
}
// EffectiveGiteaHosts returns GiteaHosts merged with SKILLSHARE_GITEA_HOSTS env var.
func (c *ProjectConfig) EffectiveGiteaHosts() []string {
return mergeGiteaHostsFromEnv(c.GiteaHosts)
}
// ProjectConfigPath returns the project config path for the given root.
func ProjectConfigPath(projectRoot string) string {
return filepath.Join(projectRoot, ".skillshare", "config.yaml")
@@ -394,6 +400,13 @@ func LoadProject(projectRoot string) (*ProjectConfig, error) {
}
cfg.CNBHosts = cnbHosts
// Validate and normalize gitea_hosts
giteaHosts, err := normalizeGiteaHosts(cfg.GiteaHosts)
if err != nil {
return nil, fmt.Errorf("project config: %w", err)
}
cfg.GiteaHosts = giteaHosts
for _, target := range cfg.Targets {
if strings.TrimSpace(target.Name) == "" {
return nil, fmt.Errorf("project config has target with empty name")
+9 -1
View File
@@ -18,6 +18,7 @@ const (
PlatformBitbucket // bitbucket.org
PlatformAzureDevOps // dev.azure.com and visualstudio.com
PlatformCNB // cnb.cool and self-hosted CNB instances
PlatformGitea // gitea.com and self-hosted Gitea instances
)
// extractHost returns the hostname from a clone URL.
@@ -66,6 +67,9 @@ func detectPlatform(cloneURL string) Platform {
if strings.Contains(host, "cnb.cool") {
return PlatformCNB
}
if strings.Contains(host, "gitea") {
return PlatformGitea
}
return PlatformUnknown
}
@@ -106,6 +110,10 @@ func resolveToken(cloneURL string) (token, username string) {
if t := os.Getenv("CNB_TOKEN"); t != "" {
return t, "cnb"
}
case PlatformGitea:
if t := os.Getenv("GITEA_TOKEN"); t != "" {
return t, "x-access-token"
}
}
// Generic fallback — use platform-appropriate username, or preserve
@@ -203,7 +211,7 @@ func sanitizeTokens(text string) string {
vars := []string{
"GITHUB_TOKEN", "GH_TOKEN", "GITLAB_TOKEN", "BITBUCKET_TOKEN",
"AZURE_DEVOPS_TOKEN", "SKILLSHARE_GIT_TOKEN", "BITBUCKET_USERNAME",
"CNB_TOKEN",
"CNB_TOKEN", "GITEA_TOKEN",
}
for _, v := range vars {
if t := os.Getenv(v); t != "" {
+286
View File
@@ -0,0 +1,286 @@
package install
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"path/filepath"
"strings"
"time"
)
type giteaContentItem struct {
Type string `json:"type"`
Name string `json:"name"`
Path string `json:"path"`
DownloadURL string `json:"download_url"`
}
type giteaCommit struct {
SHA string `json:"sha"`
}
// isGiteaAPISource reports whether the source is a Gitea instance that supports
// the Contents API for direct file downloads.
func isGiteaAPISource(source *Source) bool {
if source == nil {
return false
}
host := strings.ToLower(extractHost(source.CloneURL))
return strings.Contains(host, "gitea")
}
// downloadGiteaDir downloads a repository subdirectory via the Gitea Contents API.
func downloadGiteaDir(owner, repo, path, destDir string, source *Source, onProgress ProgressCallback) (string, error) {
if owner == "" || repo == "" {
return "", fmt.Errorf("gitea download requires owner and repo")
}
apiBase := giteaAPIBase(source)
if err := os.MkdirAll(destDir, 0755); err != nil {
return "", err
}
if onProgress != nil {
onProgress("Downloading via Gitea API...")
}
client := &http.Client{Timeout: 30 * time.Second}
if err := giteaDownloadDirRecursive(client, apiBase, owner, repo, strings.Trim(path, "/"), destDir, onProgress); err != nil {
return "", err
}
commitHash, err := giteaFetchLatestCommitHash(apiBase, owner, repo, source)
if err != nil {
return "", nil
}
return shortCommitHash(commitHash), nil
}
// giteaAPIBase returns the base API URL for a Gitea instance.
func giteaAPIBase(source *Source) string {
host := strings.ToLower(extractHost(source.CloneURL))
scheme := "https"
// For standard gitea.com, use api.gitea.com convention
// For self-hosted, use https://{host}/api/v1
if host == "gitea.com" {
return "https://gitea.com/api/v1"
}
return fmt.Sprintf("%s://%s/api/v1", scheme, host)
}
// giteaDownloadDirRecursive recursively downloads a directory via the Gitea Contents API.
func giteaDownloadDirRecursive(client *http.Client, apiBase, owner, repo, path, destDir string, onProgress ProgressCallback) error {
contentsURL := fmt.Sprintf("%s/repos/%s/%s/contents/%s",
strings.TrimRight(apiBase, "/"), owner, repo, url.PathEscape(path))
req, err := giteaNewRequest(contentsURL)
if err != nil {
return err
}
resp, err := client.Do(req)
if err != nil {
return fmt.Errorf("Gitea API request failed: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return fmt.Errorf("Gitea contents API returned %d for %s", resp.StatusCode, path)
}
var raw json.RawMessage
if err := json.NewDecoder(resp.Body).Decode(&raw); err != nil {
return fmt.Errorf("failed to parse Gitea contents response: %w", err)
}
trimmed := bytes.TrimSpace(raw)
if len(trimmed) == 0 {
return fmt.Errorf("empty Gitea contents response for %q", path)
}
// Single file response: {type, name, path, download_url, ...}
if trimmed[0] == '{' {
var item giteaContentItem
if err := json.Unmarshal(trimmed, &item); err != nil {
return err
}
if item.Type != "file" {
return fmt.Errorf("unsupported Gitea content type %q", item.Type)
}
fileName, err := giteaSanitizeName(item.Name)
if err != nil {
return err
}
target := filepath.Join(destDir, fileName)
if onProgress != nil {
onProgress(fmt.Sprintf("Downloading %s", item.Path))
}
return giteaDownloadFile(client, item.DownloadURL, target)
}
// Directory listing response: [{type, name, path, download_url, ...}]
if trimmed[0] == '[' {
var items []giteaContentItem
if err := json.Unmarshal(trimmed, &items); err != nil {
return err
}
for _, item := range items {
name, err := giteaSanitizeName(item.Name)
if err != nil {
return err
}
switch item.Type {
case "dir":
childDir := filepath.Join(destDir, name)
if err := os.MkdirAll(childDir, 0755); err != nil {
return err
}
if err := giteaDownloadDirRecursive(client, apiBase, owner, repo, item.Path, childDir, onProgress); err != nil {
return err
}
case "file":
target := filepath.Join(destDir, name)
if onProgress != nil {
onProgress(fmt.Sprintf("Downloading %s", item.Path))
}
if err := giteaDownloadFile(client, item.DownloadURL, target); err != nil {
return err
}
}
}
return nil
}
return fmt.Errorf("unexpected Gitea contents payload for %q", path)
}
// giteaDownloadFile downloads a single file from a URL.
func giteaDownloadFile(client *http.Client, fileURL, destPath string) error {
req, err := giteaNewRequest(fileURL)
if err != nil {
return err
}
resp, err := client.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return fmt.Errorf("download returned %d", resp.StatusCode)
}
if err := os.MkdirAll(filepath.Dir(destPath), 0755); err != nil {
return err
}
f, err := os.OpenFile(destPath, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644)
if err != nil {
return err
}
defer f.Close()
_, err = io.Copy(f, resp.Body)
return err
}
// giteaNewRequest creates a GET request with Gitea API headers and optional
// token authentication (GITEA_TOKEN or platform-resolved token).
func giteaNewRequest(reqURL string) (*http.Request, error) {
req, err := http.NewRequest(http.MethodGet, reqURL, nil)
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
// Try GITEA_TOKEN first, then SKILLSHARE_GIT_TOKEN
token := os.Getenv("GITEA_TOKEN")
if token == "" {
token = os.Getenv("SKILLSHARE_GIT_TOKEN")
}
if token != "" {
req.Header.Set("Authorization", "token "+token)
}
return req, nil
}
// giteaFetchLatestCommitHash retrieves the latest commit SHA from a Gitea repo.
func giteaFetchLatestCommitHash(apiBase, owner, repo string, source *Source) (string, error) {
commitsURL := fmt.Sprintf("%s/repos/%s/%s/commits?per_page=1",
strings.TrimRight(apiBase, "/"), owner, repo)
req, err := giteaNewRequest(commitsURL)
if err != nil {
return "", err
}
client := &http.Client{Timeout: 15 * time.Second}
resp, err := client.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
if resp.StatusCode == http.StatusOK {
var commits []giteaCommit
if decodeErr := json.NewDecoder(resp.Body).Decode(&commits); decodeErr == nil && len(commits) > 0 {
return commits[0].SHA, nil
}
}
// Fallback: use git ls-remote
if source != nil && source.CloneURL != "" {
return getRemoteHeadCommit(source.CloneURL)
}
return "", fmt.Errorf("failed to fetch latest commit hash")
}
// giteaSanitizeName validates a Gitea file/directory name.
func giteaSanitizeName(name string) (string, error) {
name = strings.TrimSpace(name)
if name == "" || name == "." || name == ".." || strings.Contains(name, "/") || strings.Contains(name, "\\") {
return "", fmt.Errorf("invalid Gitea item name %q", name)
}
return name, nil
}
// giteaOwnerRepo extracts the owner and repo name from a Gitea clone URL.
// Clone URLs are in the format: https://host/owner/repo.git or git@host:owner/repo.git
func giteaOwnerRepo(cloneURL string) (owner, repo string) {
u := strings.TrimSpace(cloneURL)
u = strings.TrimSuffix(u, ".git")
u = strings.TrimSuffix(u, "/")
// SSH: git@host:owner/repo
if strings.HasPrefix(u, "git@") {
parts := strings.Split(u, ":")
if len(parts) == 2 {
segments := strings.Split(parts[1], "/")
if len(segments) >= 2 {
return segments[0], segments[1]
}
}
return "", ""
}
// HTTPS: https://host/owner/repo
parsed, err := url.Parse(u)
if err != nil {
return "", ""
}
path := strings.Trim(parsed.Path, "/")
segments := strings.Split(path, "/")
if len(segments) >= 2 {
return segments[0], segments[1]
}
return "", ""
}
+15
View File
@@ -492,6 +492,21 @@ func installFromGitSubdir(source *Source, destPath string, result *InstallResult
}
}
// Fast path 2b: Gitea Contents API
if subdirPath == "" && isGiteaAPISource(source) {
owner, repo := giteaOwnerRepo(source.CloneURL)
resolved = source.Subdir
subdirPath = filepath.Join(tempRepoPath, resolved)
hash, dlErr := downloadGiteaDir(owner, repo, source.Subdir, subdirPath, source, opts.OnProgress)
if dlErr == nil {
commitHash = hash
} else {
result.Warnings = append(result.Warnings, fmt.Sprintf("Gitea API install fallback: %v", dlErr))
subdirPath = ""
_ = os.RemoveAll(tempRepoPath)
}
}
// Fallback: full clone + fuzzy subdir resolution
if subdirPath == "" {
_ = os.RemoveAll(tempRepoPath)
+27
View File
@@ -389,6 +389,33 @@ func discoverFromGitSubdirWithProgressImpl(source *Source, onProgress ProgressCa
subdirPath = ""
}
// Fast path 2b: Gitea Contents API
if subdirPath == "" && isGiteaAPISource(source) {
owner, repo := giteaOwnerRepo(source.CloneURL)
subdirPath = filepath.Join(repoPath, source.Subdir)
hash, dlErr := downloadGiteaDir(owner, repo, source.Subdir, subdirPath, source, onProgress)
if dlErr == nil {
commitHash = hash
skills := discoverSkills(subdirPath, true)
agents := discoverAgents(subdirPath, len(skills) > 0)
skills, agents, err = constrainDiscoveryToExplicitSkill(source, skills, agents)
if err != nil {
_ = os.RemoveAll(tempDir)
return nil, err
}
return &DiscoveryResult{
RepoPath: tempDir,
Skills: skills,
Agents: agents,
Source: source,
CommitHash: commitHash,
}, nil
}
warnings = append(warnings, fmt.Sprintf("Gitea API discovery fallback: %v", dlErr))
_ = os.RemoveAll(repoPath)
subdirPath = ""
}
// Fallback: full clone + fuzzy subdir resolution
_ = os.RemoveAll(repoPath)
if onProgress != nil {
+1 -1
View File
@@ -74,7 +74,7 @@ func WrapGitError(stderr string, err error, tokenAuthAttempted bool) error {
}
return fmt.Errorf("authentication required — options:\n"+
" 1. SSH URL: git@<host>:<owner>/<repo>.git\n"+
" 2. Token env var: GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN, AZURE_DEVOPS_TOKEN, CNB_TOKEN, or SKILLSHARE_GIT_TOKEN\n"+
" 2. Token env var: GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN, AZURE_DEVOPS_TOKEN, CNB_TOKEN, GITEA_TOKEN, or SKILLSHARE_GIT_TOKEN\n"+
" 3. Git credential helper: gh auth login\n %s", s)
}
if s != "" {
+6
View File
@@ -82,6 +82,7 @@ type ParseOptions struct {
GitLabHosts []string // extra hostnames to treat as GitLab (nested subgroup support)
AzureHosts []string // extra hostnames to treat as Azure DevOps on-premises
CNBHosts []string // extra hostnames to treat as CNB instances
GiteaHosts []string // extra hostnames to treat as Gitea instances
}
// ParseSource analyzes the input string and returns a Source struct.
@@ -468,6 +469,11 @@ func isCNBHost(host string, extraHosts []string) bool {
return strings.Contains(host, "cnb.cool") || hostMatchesAny(host, extraHosts)
}
// isGiteaHost returns true if the host should be treated as a Gitea instance.
func isGiteaHost(host string, extraHosts []string) bool {
return strings.Contains(host, "gitea") || hostMatchesAny(host, extraHosts)
}
// stripGitBranchPrefix removes platform-specific branch path segments from web URLs.
// Bitbucket: src/{branch}/path → path
// GitLab: -/tree/{branch}/path → path, -/blob/{branch}/path → path