Skip to main content

​
Overview

Gitea provides full-featured Git repository management that supports all standard Git operations along with advanced features like Git LFS, protected branches, and repository mirroring. Built on native Git functionality, Gitea offers a web-based interface for managing your source code efficiently.

​
Repository Creation

1

Create a New Repository

Navigate to the Gitea dashboard and click the ”+” icon or “New Repository” button. Repositories can be created under your user account or any organization where you have permissions.
// From services/repository/create.go
func CreateRepository(ctx context.Context, doer *user_model.User, 
                     repo *repo_model.Repository, 
                     opts CreateRepoOptions) error {
    // Repository creation with initialization
    if err := gitrepo.InitRepository(ctx, repo, 
                                    repo.ObjectFormatName); err != nil {
        return err
    }
    return nil
}
2

Initialize with Options

Choose repository visibility (public/private), add a README, select a license, and configure a .gitignore template during creation.
3

Configure Repository Settings

After creation, configure additional settings like description, website URL, topics, and default branch.

​
Branch Management

​
Creating and Managing Branches

Gitea provides comprehensive branch management through both the web interface and Git operations: 
// From services/repository/branch.go
func CreateNewBranch(ctx context.Context, doer *user_model.User, 
                     repo *repo_model.Repository, 
                     oldBranchName, branchName string) error {
    branch, err := git_model.GetBranch(ctx, repo.ID, oldBranchName)
    if err != nil {
        return err
    }
    return CreateNewBranchFromCommit(ctx, doer, repo, 
                                    branch.CommitID, branchName)
}
Create a Branch
  1. Navigate to your repository
  2. Click the branch dropdown menu
  3. Type a new branch name
  4. Select the source branch
  5. Click “Create Branch”
View Branch List
  • Access the “Branches” tab to see all branches
  • View commits ahead/behind default branch
  • See branch protection status
  • Access branch deletion options

​
Protected Branches

Protect important branches from force pushes and require specific conditions before merging:

Branch Protection Rules

  • Require pull request reviews
  • Enforce status checks
  • Restrict who can push
  • Prevent force pushes
  • Require signed commits

Advanced Options

  • Required approvals count
  • Dismiss stale reviews
  • Required status checks
  • Allowed push users/teams
  • Pattern-based protection
Branch protection rules are evaluated based on pattern matching. Use wildcards like release/* to protect multiple branches with a single rule.

​
Tag Management

Tags mark specific points in repository history, typically for releases:

​
Creating Tags

  1. Navigate to Releases tab
  2. Click New Release
  3. Enter tag name (e.g., v1.0.0)
  4. Select target branch or commit
  5. Add release notes
  6. Attach binary files if needed

​
Git LFS (Large File Storage)

​
Overview

Gitea includes built-in support for Git LFS, enabling efficient handling of large binary files: 
// From services/repository/lfs.go
func GarbageCollectLFSMetaObjects(ctx context.Context, 
                                 opts GarbageCollectLFSMetaObjectsOptions) error {
    if !setting.LFS.StartServer {
        return nil
    }
    return git_model.IterateRepositoryIDsWithLFSMetaObjects(ctx, 
        func(ctx context.Context, repoID, count int64) error {
            repo, err := repo_model.GetRepositoryByID(ctx, repoID)
            if err != nil {
                return err
            }
            return GarbageCollectLFSMetaObjectsForRepo(ctx, repo, opts)
        })
}

​
Enabling and Using LFS

1

Enable LFS for Repository

Repository administrators can enable LFS in the repository settings under the “Git LFS” section.
2

Configure Git LFS Client

# Install Git LFS (if not already installed)
git lfs install

# Track large file types
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"

# Add .gitattributes
git add .gitattributes
3

Push LFS Files

# Add and commit large files
git add large-file.zip
git commit -m "Add large file"

# Push to Gitea (LFS files uploaded automatically)
git push origin main
LFS objects are stored separately from the Git repository and retrieved on-demand. This keeps repository clones fast even with large files.

​
Repository Mirroring

​
Mirror from External Repository

Gitea can mirror repositories from external sources (GitHub, GitLab, Bitbucket, etc.):
Pull Mirroring
  • Mirror external repositories into Gitea
  • Automatic sync on configurable intervals
  • Supports authentication with tokens/passwords
  • One-way synchronization (external → Gitea)
Push Mirroring
  • Push Gitea repository to external Git hosting
  • Automatic sync on push events
  • Useful for backup and redundancy
  • One-way synchronization (Gitea → external)
// From services/mirror/mirror.go
func SyncPullMirror(ctx context.Context, repoID int64) {
    // Fetch from remote and update local mirror
    repo, err := repo_model.GetRepositoryByID(ctx, repoID)
    if err != nil {
        return
    }
    // Perform sync operation
}

​
Repository Templates

Create repository templates to standardize new projects:

Template Creation

  1. Create a repository with standard structure
  2. Enable “Template Repository” in settings
  3. Others can generate repositories from template
  4. Template includes files, directories, and history

Using Templates

  1. Click “New Repository”
  2. Select “Repository template” dropdown
  3. Choose from available templates
  4. Customize repository name and settings

​
Repository Transfer

Transfer repository ownership between users or organizations: 
// From services/repository/transfer.go
func TransferOwnership(ctx context.Context, doer *user_model.User, 
                      newOwnerName string, repo *repo_model.Repository) error {
    // Transfer repository to new owner
    // Update all related data (issues, PRs, webhooks, etc.)
    return db.WithTx(ctx, func(ctx context.Context) error {
        // Atomic transfer operation
        return performTransfer(ctx, repo, newOwner)
    })
}
1

Initiate Transfer

Navigate to Settings → Danger Zone → Transfer Repository
2

Specify New Owner

Enter the username or organization name that will receive the repository
3

Confirm Transfer

The new owner must accept the transfer. All issues, pull requests, and settings are preserved.

​
Repository Archive

​
Downloading Repository Archives

Download repository snapshots in various formats:
  • ZIP: Compressed archive of repository contents
  • TAR.GZ: Compressed tarball for Unix systems
  • Bundle: Git bundle format with full history

​
Archiving Repositories

Archive repositories to make them read-only:
Archived repositories are read-only. No pushes, pull requests, or issues can be created. This is useful for preserving historical projects.

​
Collaboration Features

Collaborators

  • Add individual collaborators
  • Assign read, write, or admin permissions
  • Manage access per repository
  • Remove access when needed

Teams (Organizations)

  • Assign teams to repositories
  • Team-based permissions
  • Bulk access management
  • Hierarchical organization

​
Best Practices

Naming Conventions
  • Use descriptive, lowercase names
  • Separate words with hyphens
  • Avoid special characters
Branch Strategy
  • Use main or master for production
  • Create feature branches for development
  • Use semantic version tags for releases
  • Protect main branches
Repository Structure
  • Include README.md with project description
  • Add LICENSE file for open source
  • Use .gitignore to exclude build artifacts
  • Document contribution guidelines

​
See Also

  • Pull Requests - Code review and merging workflow
  • Issues - Bug tracking and project management
  • Actions - CI/CD automation
  • Wiki - Project documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us