Quick Start Guide

5-Minute Quick Start

This guide will get you from zero to a working Gitea instance with your first repository in just 5 minutes.

This quick start uses Docker for the fastest setup. For other installation methods, see the Installation Guide.

Prerequisites

Before you begin, ensure you have:

Docker installed - Get Docker
Terminal/Command line access
5 minutes of your time

That’s it! No other dependencies required.

Step 1: Start Gitea

Run this single command to start Gitea:

docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:22 \
  -v gitea-data:/data \
  gitea/gitea:latest

What this does:

Downloads the latest Gitea Docker image
Starts Gitea on port 3000 (web interface)
Maps port 222 for SSH access
Creates a Docker volume for persistent data

Wait for Gitea to start

Give it a few seconds to initialize. Check if it’s running:

docker ps

You should see the gitea container in the list.

Access the web interface

Open your browser and go to:

http://localhost:3000

You’ll see the Gitea installation page.

Step 2: Complete Initial Setup

Gitea will guide you through the initial configuration:

Configure database

The default SQLite configuration is perfect for getting started:

Database Type: SQLite3 (pre-selected)
Path: Default value is fine

SQLite requires no additional setup and is perfect for small to medium installations. You can migrate to PostgreSQL or MySQL later if needed.

Configure basic settings

Adjust these settings for your environment:

For Local Development
For Production/Remote Server

Server Domain: localhost
SSH Server Port: 222
Gitea Base URL: http://localhost:3000/

Keep the defaults - they work great for local testing!

Server Domain: Your domain or IP (e.g., git.example.com)
SSH Server Port: 222 (or 22 if not using Docker)
Gitea Base URL: http://your-domain-or-ip:3000/

Make sure to use your actual domain or IP address that users will use to access Gitea.

Create administrator account

Scroll down to the “Administrator Account Settings” section:

Administrator Username: Choose your admin username (e.g., admin)
Password: Choose a strong password
Email: Your email address

Keep these credentials safe! This account has full control over your Gitea instance.

Install Gitea

Click the “Install Gitea” button at the bottom of the page.The installation takes just a few seconds. You’ll be redirected to the login page when complete.

Step 3: Create Your First Repository

Use the administrator credentials you just created to log in.

Create a new repository

Click the ”+” icon in the top right corner and select “New Repository”.

You can also click the green “Create Repository” button on your dashboard.

Configure your repository

Fill in the repository details:

Owner: Your username (pre-selected)
Repository Name: e.g., my-first-repo
Description: (optional) “My first Gitea repository”
Visibility: Choose Public or Private
Initialize Repository: Check this box
- ✅ Add .gitignore: Select a template (optional)
- ✅ Add README: Recommended for getting started
- ✅ Add License: Choose a license (optional)

Click “Create Repository” when ready.

Explore your repository

Congratulations! You now have your first Gitea repository.You’ll see:

Your README.md file
Repository navigation (Code, Issues, Pull Requests, etc.)
Clone URL (HTTP and SSH)

Step 4: Clone and Push Code

Now let’s interact with your repository from the command line:

Using HTTPS
Using SSH

Clone the repository

Copy the HTTPS clone URL from your repository page and run:

git clone http://localhost:3000/admin/my-first-repo.git
cd my-first-repo

Make changes

echo "# Hello Gitea!" >> hello.md
git add hello.md
git commit -m "Add hello file"

Push changes

git push origin main

Enter your Gitea username and password when prompted.

Add SSH key to Gitea

First, generate an SSH key if you don’t have one:

ssh-keygen -t ed25519 -C "[email protected]"

Copy your public key:

cat ~/.ssh/id_ed25519.pub

In Gitea:

Click your avatar → Settings
Go to SSH / GPG Keys
Click Add Key
Paste your public key and give it a name
Click Add Key

Clone the repository

git clone ssh://git@localhost:222/admin/my-first-repo.git
cd my-first-repo

Notice port 222 in the SSH URL - this matches the port we mapped in Docker.

Make and push changes

echo "# Hello Gitea!" >> hello.md
git add hello.md
git commit -m "Add hello file"
git push origin main

Verify your changes

Go back to your browser and refresh the repository page.You should see your new hello.md file!

Step 5: Explore Gitea Features

Now that you have a working repository, explore what Gitea can do:

Create an Issue

Try the issue tracker:

Go to Issues tab
Click New Issue
Add a title and description
Submit the issue

Make a Pull Request

Test the code review workflow:

Create a new branch
Make changes and push
Create a pull request
Review and merge

Add Collaborators

Invite team members:

Go to repository Settings
Click Collaborators
Add users and set permissions

Setup Webhooks

Integrate with external services:

Go to repository Settings
Click Webhooks
Add webhook URL
Configure events

Common Tasks

Create an Organization

Organizations help manage multiple repositories and team members:

Create organization

Click the ”+” icon → New Organization

Configure organization

Set organization name and description
Choose visibility settings
Click Create Organization

Add team members

Go to organization Teams
Create teams with different permissions
Add members to teams

Enable Gitea Actions (CI/CD)

Gitea Actions provides GitHub Actions-compatible CI/CD capabilities.

Enable actions in repository

Go to repository Settings → Actions and enable Actions.

Create workflow file

Create .gitea/workflows/test.yaml in your repository:

name: Test Workflow
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          echo "Running tests..."
          # Add your test commands here

Push and watch it run

Commit and push the workflow file. Check the Actions tab to see it run!

For Actions to work, you need to set up an Act Runner. The workflow will be queued until a runner is available.

Configure Email Notifications

Enable email notifications for issues, pull requests, and more:

Edit configuration

Stop Gitea and edit the configuration file.For Docker:

docker stop gitea
docker exec -it gitea sh
vi /data/gitea/conf/app.ini

Add SMTP settings

Add these lines to app.ini:

[mailer]
ENABLED = true
FROM = [email protected]
PROTOCOL = smtps
SMTP_ADDR = smtp.example.com
SMTP_PORT = 465
USER = [email protected]
PASSWD = your-password

Restart Gitea

docker restart gitea

Managing Your Gitea Instance

Start/Stop/Restart Gitea

# Check status
docker ps

# Stop Gitea
docker stop gitea

# Start Gitea
docker start gitea

# Restart Gitea
docker restart gitea

# View logs
docker logs gitea

# Follow logs in real-time
docker logs -f gitea

Backup Your Data

Always backup your data regularly!

# Backup the Docker volume
docker run --rm \
  -v gitea-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/gitea-backup-$(date +%Y%m%d).tar.gz /data

# Or copy the entire volume
docker cp gitea:/data ./gitea-backup-$(date +%Y%m%d)

Update Gitea

Keep your Gitea instance up to date:

# Pull the latest image
docker pull gitea/gitea:latest

# Stop and remove the old container
docker stop gitea
docker rm gitea

# Start with the new image (use your original docker run command)
docker run -d \
  --name=gitea \
  -p 3000:3000 \
  -p 222:22 \
  -v gitea-data:/data \
  gitea/gitea:latest

Your data is safe in the Docker volume and will persist across container updates.

Troubleshooting

Can't access Gitea at localhost:3000

Check if container is running:

docker ps

Check logs for errors:

docker logs gitea

Verify port isn’t already in use:

lsof -i :3000

Git push asks for password every time

Using HTTPS: Set up credential helper:

git config --global credential.helper store

Or switch to SSH: Add your SSH key to Gitea and use SSH clone URLs instead.

SSH connection refused

Check SSH port mapping:

docker port gitea

Test SSH connection:

ssh -T git@localhost -p 222

Make sure you’re using port 222 (not 22) as specified in the Docker command.

Lost administrator password

Reset via command line:

docker exec -it gitea gitea admin user change-password \
  --username admin \
  --password new-password

Next Steps

Configuration Guide

Learn about advanced configuration options and customization

Features Overview

Discover all features available in Gitea

API Documentation

Integrate Gitea with other tools using the REST API

Actions & CI/CD

Set up continuous integration and deployment pipelines

Additional Resources

Official Documentation

Comprehensive documentation for all Gitea features

Community Forum

Get help and discuss with the community

Discord Server

Chat with other Gitea users and developers

GitHub Repository

Source code, issues, and contributions

Congratulations! You’ve successfully set up Gitea and created your first repository. You’re now ready to use Gitea for your development projects!

Getting Started

Core Features

Administration

User Management

Integrations

Quick Start Guide

5-Minute Quick Start

Prerequisites

Step 1: Start Gitea

Step 2: Complete Initial Setup

Step 3: Create Your First Repository

Step 4: Clone and Push Code

Step 5: Explore Gitea Features

Create an Issue

Make a Pull Request

Add Collaborators

Setup Webhooks

Common Tasks

Create an Organization

Enable Gitea Actions (CI/CD)

Configure Email Notifications

Managing Your Gitea Instance

Start/Stop/Restart Gitea

Backup Your Data

Update Gitea

Troubleshooting

Next Steps

Configuration Guide

Features Overview

API Documentation

Actions & CI/CD

Additional Resources

Official Documentation

Community Forum

Discord Server

GitHub Repository

Build docs developers (and LLMs) love

Getting Started

Core Features

Administration

User Management

Integrations

​5-Minute Quick Start

​Prerequisites

​Step 1: Start Gitea

​Step 2: Complete Initial Setup

​Step 3: Create Your First Repository

​Step 4: Clone and Push Code

​Step 5: Explore Gitea Features

Create an Issue

Make a Pull Request

Add Collaborators

Setup Webhooks

​Common Tasks

​Create an Organization

​Enable Gitea Actions (CI/CD)

​Configure Email Notifications

​Managing Your Gitea Instance

​Start/Stop/Restart Gitea

​Backup Your Data

​Update Gitea

​Troubleshooting

​Next Steps

Configuration Guide

Features Overview

API Documentation

Actions & CI/CD

​Additional Resources

Official Documentation

Community Forum

Discord Server

GitHub Repository

Build docs developers (and LLMs) love

5-Minute Quick Start

Prerequisites

Step 1: Start Gitea

Step 2: Complete Initial Setup

Step 3: Create Your First Repository

Step 4: Clone and Push Code

Step 5: Explore Gitea Features

Common Tasks

Create an Organization

Enable Gitea Actions (CI/CD)

Configure Email Notifications

Managing Your Gitea Instance

Start/Stop/Restart Gitea

Backup Your Data

Update Gitea

Troubleshooting

Next Steps

Additional Resources