DOCSEARCHbyAlgolia
Submit Docs

Gitea

repository·main·Indexed 13 days ago

https://github.com/go-gitea/gitea

A lightweight, self-hosted, all-in-one software development service providing Git hosting, code management, issue tracking, package registry, and CI/CD compatible with GitHub Actions.

Tokens
44.3K
Snippets
140
Records
230
Agent score
99%

What's inside Gitea

  1. Explore official Gitea tools and projects

    main

    Gitea maintains several official tools and an ecosystem of third-party projects:

    Official Projects:

    • go-sdk: An official Go SDK.
    • tea: A CLI tool for Gitea.
    • action runner: A runner for Gitea Actions.

    Third-party Ecosystem:

    • awesome-gitea: A curated list of Gitea-related projects, including SDKs, plugins, and themes.

  2. Follow the dependency direction rules

    main

    To maintain architectural integrity, dependencies must only flow in one direction. A package on the left may import a package on its right, but never the reverse.

    Allowed dependency flow: cmd $\rightarrow$ routers $\rightarrow$ services $\rightarrow$ models $\rightarrow$ modules

  3. Handle Fork Pull Request security restrictions

    main

    Workflows triggered by Pull Requests from forks are subject to enhanced security restrictions to prevent untrusted code from accessing private data:

    1. Automatic Downgrade: The base permissions for the repository are automatically downgraded to Restricted mode (read or none).
    2. No Cross-Repo Access: Even if AllowedCrossRepoIDs is configured, fork PRs are strictly denied access to other private/internal repositories. They can only access the target repository and truly public repositories.

  4. Configure Actions Token Permissions via Clamping Hierarchy

    main

    Permissions for the GITEA_TOKEN are evaluated through a three-step process. Understanding this hierarchy is critical for debugging why a workflow might have less access than requested.

    1. Step 1: Determine Base Permissions: Gitea parses the permissions: block in the workflow (job-level or top-level). If no valid block is found, it falls back to the repository's TokenPermissionMode (Permissive or Restricted).
    2. Step 2: Apply Repository Clamping: The base permissions are clamped against the MaxTokenPermissions defined in the repository's Actions settings.
    3. Step 3: Apply Organization/User Clamping: Organization or User settings (UserActionsConfig) provide a global MaxTokenPermissions ceiling.
      • If OverrideOwnerConfig is false (default), the repository's permissions cannot exceed the owner's limits.
      • If OverrideOwnerConfig is true, the repository can define its own limits, provided they don't exceed the owner's settings (unless specifically allowed).

  5. Responsibilities of a Gitea Merger

    main

    Mergers handle the final steps of the PR lifecycle. Their duties include:

    • Merging from the queue: Process PRs from the merge queue in order once they have lgtm/done, no open discussions, and no merge conflicts.
    • Metadata management: Rewrite the PR title and description before merging to ensure the commit message is clear. Mergers should not edit the actual commit message except to remove unnecessary information.
    • Labeling: Assign correct labels (including type/…) to support changelog generation and backport decisions.
    • Release coordination: Agree with owners on when a release is ready.
    • Final Approval: A merge implies the merger has reviewed the PR and it looks good to them.

  6. Understand the Gitea Actions Token Permission System

    main

    Gitea Actions uses a strict clamping mechanism for the GITEA_TOKEN (the automatic token generated for each job). Permissions are determined by a hierarchy of settings, ensuring that workflows cannot bypass security restrictions set at the Repository or Organization level.

    Key Concepts

    • GITEA_TOKEN: A scoped token providing access to specific features (Code, Issues, etc.) for the repository where the workflow runs.
    • Token Permission Mode: The default access level when no permissions: block is defined in a workflow:
      • Permissive: Grants write access to most scopes by default.
      • Restricted: Grants read (or none) access to most scopes by default.
    • Clamping: A security process where requested permissions are bounded by a "hard ceiling" defined in settings. Even if a workflow requests write access, it will be downgraded to read if the repository or organization settings restrict it.
    • Cross-Repository Access: By default, tokens can access the current repository and any public repositories on the instance. To allow read-only access to other private/internal repositories, owners must configure an AllowedCrossRepoIDs list.

  7. Understand the Gitea backend architecture and package layout

    main

    The Gitea backend is written in Go, using chi for web routing and XORM for database access. The project follows a strict layered architecture to manage complexity.

    Package Layout

    • build: Compile-time helper scripts.
    • cmd: Subcommands (e.g., web, serv, hooks, doctor, admin utilities).
    • models: Data structures and XORM database operations. Keeps external dependencies minimal.
      • models/db: Core database operations.
      • models/fixtures: Test sample data.
    • modelmigration: Schema migration scripts.
    • modules: Standalone functionality with minimal dependencies (e.g., modules/setting for config, modules/git for Git CLI interaction).
    • routers: Request handlers, categorized into api, web, install, and private.
    • services: Business logic that orchestrates routers and models.
    • templates: Go HTML templates.
    • public: Compiled frontend assets.
    • tests: Integration and end-to-end test helpers.

  8. Improve accessibility for Fomantic UI Checkboxes

    main

    Fomantic UI uses a non-standard HTML layout for checkboxes that is not natively friendly to screen readers:

    <div class="ui checkbox">
  <input type="checkbox">
  <label>...</label>
</div>

    To resolve this, Gitea uses initAriaLabels to link the input and label elements. The system automatically adds IDs to all Fomantic UI checkboxes via JavaScript to ensure proper association.

    Note: If the <label> element is empty, you must manually provide an aria-label attribute to the checkbox to ensure screen readers can identify it.

  9. Understand the Gitea frontend architecture

    main

    Gitea's frontend is a hybrid system using Go HTML templates for rendering and Vue 3 for complex interactivity. The architecture relies on three main technologies:

    • Vue 3: Used for interactive components. Gitea uses Vue without JSX to maintain a strict separation between HTML and JavaScript.
    • Fomantic-UI (jQuery): A deprecated dependency used for certain UI elements. It is vendored with specific patches.
    • Tailwind CSS: Used for styling via utility classes.

    Source File Locations:

    • web_src/css/: CSS styles
    • web_src/js/: JavaScript and TypeScript
    • web_src/js/components/: Vue components
    • web_src/js/features/: Feature modules wired up at page load
    • templates/: Go HTML templates

  10. How LDAP authentication works in Gitea

    main

    Gitea supports two primary methods for LDAP authentication. Choosing the right one depends on your security requirements and LDAP server configuration.

    1. LDAP via BindDN (Recommended)

    This method uses a service account (Bind DN) to search the LDAP directory for a user before attempting to authenticate them.

    Workflow:

    1. Gitea connects to the LDAP server using the provided Bind DN and Bind Password.
    2. It performs a search using the User Search Base and User Filter to find the user record matching the provided username.
    3. Once the user is found, Gitea attempts to bind to the LDAP server using the discovered user's DN and the credentials supplied by the user during login.

    Why use it? It is more secure because the Bind DN can be restricted to read-only permissions, and it allows for complex user lookups via filters.

  11. Follow backend naming conventions

    main

    Gitea uses specific naming patterns for packages to maintain clarity:

    • Top-level packages: Use plural forms (e.g., services, models, routers).
    • Subpackages: Use singular forms (e.g., services/user, models/repository).

    Disambiguation: If packages from different layers share a name, use a snake_case import alias to avoid collisions:

    import user_service "gitea.dev/services/user"

  12. Gitea Package Registry data models and relationships

    main

    All package registry implementations in Gitea rely on a consistent set of underlying models. The hierarchy follows a specific relationship: a Package contains multiple PackageVersions, which contain multiple PackageFiles, and multiple files can share a single PackageBlob.

    Models

    ModelDescription
    PackageThe root of a package; provides values fixed for every version (e.g., the package name).
    PackageVersionA specific version of a package containing metadata (e.g., the package description).
    PackageFileA file within a package describing its content (e.g., file name).
    PackageBlobThe actual content of a file (can be shared by multiple files).
    PackagePropertyAdditional properties attached to Package, PackageVersion, or PackageFile (e.g., for routing metadata).

    Model Relationship Diagram

    Package <1---*> PackageVersion <1---*> PackageFile <*---1> PackageBlob