Quick Start Guide

Get up and running with Gitea in 5 minutes - from installation to your first repository

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

1. 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.

2. 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:

1. 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.

2. Configure basic settings

   Adjust these settings for your environment:

   For Local Development

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

   Keep the defaults - they work great for local testing!

   For Production/Remote Server

   • 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.

3. 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.

4. 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

1. Log in to Gitea

   Use the administrator credentials you just created to log in.

2. 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.

3. 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.

4. 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

1. 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
   
2. Make changes

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

   git push origin main
   

   Enter your Gitea username and password when prompted.

Using SSH

1. Add SSH key to Gitea

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

   ssh-keygen -t ed25519 -C "[e-mail]"
   

   Copy your public key:

   cat ~/.ssh/id_ed25519.pub
   

   In Gitea:

   1. Click your avatar → Settings
   2. Go to SSH / GPG Keys
   3. Click Add Key
   4. Paste your public key and give it a name
   5. Click Add Key
2. 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.

3. Make and push changes

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

1. 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:

1. Go to Issues tab
2. Click New Issue
3. Add a title and description
4. Submit the issue

Make a Pull Request

Test the code review workflow:

1. Create a new branch
2. Make changes and push
3. Create a pull request
4. Review and merge

Add Collaborators

Invite team members:

1. Go to repository Settings
2. Click Collaborators
3. Add users and set permissions

Setup Webhooks

Integrate with external services:

1. Go to repository Settings
2. Click Webhooks
3. Add webhook URL
4. Configure events

Common Tasks

Create an Organization

Organizations help manage multiple repositories and team members:

1. Create organization

   Click the ”+” icon → New Organization

2. Configure organization

   • Set organization name and description
   • Choose visibility settings
   • Click Create Organization
3. Add team members

   1. Go to organization Teams
   2. Create teams with different permissions
   3. Add members to teams

Enable Gitea Actions (CI/CD)

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

1. Enable actions in repository

   Go to repository Settings → Actions and enable Actions.

2. 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
   
3. 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:

1. 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
   
2. Add SMTP settings

   Add these lines to app.ini:

   [mailer]
   ENABLED = true
   FROM = [e-mail]
   PROTOCOL = smtps
   SMTP_ADDR = smtp.example.com
   SMTP_PORT = 465
   USER = [e-mail]
   PASSWD = your-password
   
3. 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!