[Feature]: Support for Gitea platform in CI/CD

[karthikbhandary2]

I’ve noticed that support is currently limited to Bitbucket, GitHub, and GitLab. However, Gitea, an increasingly popular open-source and enterprise Git platform has been gaining significant traction. As an active user of Gitea, I believe it would be valuable to include native support for it as well.

[Coder222005]

Hey i want to work with you on this feature

[maxprilutskiy]

@karthikbhandary2 @Coder222005

To move forward with Gitea support, please create a design spec showing:

Required:

• Intended developer experience (code examples, config snippets)
• Gitea API endpoints needed
• Auth approach (tokens, OAuth, etc.)
• Key differences vs GitHub/GitLab implementation

What would the ideal integration look like from a developer's perspective?

[karthikbhandary2]

@maxprilutskiy I will get back to you with that. Give me some time.

[karthikbhandary2]

@maxprilutskiy I am working on it and will get back to by afternoon.

[karthikbhandary2]

@maxprilutskiy Here is the detailed design spec for Gitea integration as you requested—I've attached the full proposal and am looking forward to your feedback!

GITEA_INTEGRATION_DESIGN.md

[karthikbhandary2]

@maxprilutskiy can you please take a look at my proposal.

[karthikbhandary2]

@maxprilutskiy hope you got some time to take a look at my proposal.

[gagan052]

Gitea support sounds like a valuable addition, especially given its growth in open-source and enterprise setups. Adding native CI/CD integration would definitely benefit users relying on self-hosted Git workflows.

[gagan052]

No rush — excited to see the design spec when it’s ready.

[karthikbhandary2]

I have already shared a .md file in the comments previously. You can check it out if interested and let me know if any changes can be made.

[karthikbhandary2]

Lingo.dev – Gitea Integration Design Specification

1. Overview

This proposal introduces first-class support for Gitea within Lingo.dev’s CI/CD and repository integration modules.
Currently, Lingo.dev supports GitHub, GitLab, and Bitbucket. With Gitea’s growing adoption among enterprises and self-hosted developers, native support will allow Lingo.dev users to seamlessly integrate translation workflows into their self-managed Gitea environments, without relying on GitHub or GitLab APIs.

---

2. Developer Experience (DX)

Goal

Allow developers to connect Lingo.dev to their Gitea repositories and automatically manage translation updates (e.g., auto-commits, PRs, or translation jobs) exactly as they do with GitHub or GitLab, but using Gitea’s REST API.

Example: CLI Usage

# Authenticate with a Gitea instance
lingo auth --provider gitea   --url https://gitea.yourdomain.com   --token <PERSONAL_ACCESS_TOKEN>

# Link the current repo
lingo link --repo user/wiki-service

# Push translation updates to Gitea
lingo push --branch i18n-updates --create-pr

Example: Config File (lingo.config.json)

{
  "provider": "gitea",
  "server_url": "https://gitea.yourdomain.com",
  "repo": "acme/wiki-service",
  "default_branch": "main",
  "auth": {
    "type": "token",
    "token_env_var": "GITEA_TOKEN"
  },
  "auto_pr": {
    "enabled": true,
    "branch_name": "i18n-updates",
    "commit_message": "chore: sync translations via Lingo.dev"
  }
}

This mirrors the GitHub and GitLab configuration style for a familiar developer workflow, minimizing cognitive overhead.

---

3. Gitea API Endpoints Needed

Purpose	Gitea REST API Endpoint	Method	Notes
Fetch repository metadata	/api/v1/repos/{owner}/{repo}	GET	To validate repository and get default branch
Create branch	/api/v1/repos/{owner}/{repo}/branches	POST	For creating i18n-updates branch
Get file content	/api/v1/repos/{owner}/{repo}/contents/{path}	GET	To read existing translation files
Update or create file	/api/v1/repos/{owner}/{repo}/contents/{path}	POST	To commit translated files
Create pull request	/api/v1/repos/{owner}/{repo}/pulls	POST	To open a PR for review/merge
List pull requests	/api/v1/repos/{owner}/{repo}/pulls	GET	Optional: check if existing PRs are open
Get authenticated user	/api/v1/user	GET	For validating token & identifying user
Get repo branches	/api/v1/repos/{owner}/{repo}/branches	GET	To verify branch creation success

Optional (for advanced use):

Purpose	Endpoint	Method	Notes
Add PR comment	/api/v1/repos/{owner}/{repo}/issues/{index}/comments	POST	To leave translation summary comments
Webhook management	/api/v1/repos/{owner}/{repo}/hooks	GET/POST	For automated translation triggers

---

4. Authentication Approach

Supported Auth Modes

1. Personal Access Token

• Stored locally or as an environment variable.
• Passed as a Bearer token in the Authorization header.

export GITEA_TOKEN=<your_token>
lingo auth --provider gitea --url https://gitea.company.local

• Mirrors GitHub’s PAT auth model for simplicity.

2. OAuth2

• For public Gitea instances or enterprise SSO setups.
• Uses /login/oauth/authorize and /login/oauth/access_token.
• Provides a smoother login flow for developers already authenticated in Gitea.

Example HTTP Header

Authorization: token <GITEA_TOKEN>
Accept: application/json
Content-Type: application/json

---

5. Key Differences vs GitHub / GitLab

Feature	GitHub / GitLab	Gitea
API base URL	https://api.github.com / https://gitlab.com/api/v4	Custom, e.g., https://gitea.company.local/api/v1
Authentication	OAuth / PAT	OAuth/PAT
Rate limits	Strict	Typically none or configurable
Webhooks	Built-in UI configuration	Built-in, similar payloads
Enterprise use	SaaS + self-managed	Primarily self-managed
API schema	Rich metadata	Lightweight and simpler
Permissions	Scoped tokens	Simple read/write/admin

Implementation Notes

• Allow custom API base URLs for self-hosted Gitea.
• Support non-standard OAuth endpoints.
• Use token-based authentication by default.
• Handle simplified PR payloads and branch operations.

---

6. Internal Architecture Impact

Component	Change Needed	Description
@lingo/integrations	Add gitea.ts	New module implementing shared VCSProvider interface
auth module	Extend to support gitea	Token storage, validation, refresh logic
cli	Add --provider gitea flag	Extend CLI UX for Gitea
config schema	Add server_url field	To support self-hosted Gitea instances
tests	Add mock API fixtures	Simulate Gitea REST responses using nock/jest

---

7. Future Enhancements

• Webhook-based triggers for automatic translation sync on push events.
• Custom commit templates and PR labeling support.
• API pagination handling for large repos.
• Enterprise SSL/CA certificate handling for internal Gitea setups.

---

8. Summary

This proposal introduces robust support for self-hosted Gitea instances in Lingo.dev’s localization workflow.
It follows the same architectural conventions as GitHub/GitLab integrations while accommodating Gitea’s lightweight and customizable API design.

Developers can expect a consistent, intuitive experience, requiring only the base URL and token to integrate their repositories.

---

Once go through this and let me know if anything else needs to be added or any modifications required.