Command-Line Administration

CLI tools for managing Gitea from the command line

Overview

Gitea provides a comprehensive command-line interface for administrative tasks. All commands are accessed through the gitea binary.

Command Structure

gitea [command] [subcommand] [options]

View all available commands:

gitea --help

Admin Commands

The admin command provides administrative operations (see cmd/admin.go:22-89).

gitea admin --help

User Management

All user management commands are under gitea admin user (see cmd/admin_user.go).

Create User

Create a new user account (see cmd/admin_user_create.go:22-101):

gitea admin user create \
  --username johndoe \
  --email [e-mail] \
  --password secretpassword

Options:

--username · string · required

Username for the new account

--email · string · required

Email address for the new account

--password · string

Password for the account (required unless using --random-password)

--random-password · boolean

Generate a random password

--random-password-length · number · default: "12"

Length of the generated random password

--admin · boolean

Create user as administrator

--must-change-password · boolean · default: "true"

Require password change on first login (default for all users except the first)

--restricted · boolean

Create as a restricted user account

--user-type · string · default: "individual"

User type: individual or bot

--fullname · string

Full, human-readable name of the user

--access-token · boolean

Generate an access token for the user

--access-token-name · string · default: "gitea-admin"

Name for the generated access token

--access-token-scopes · string · default: "all"

Comma-separated scopes: all, read:user, write:repository, etc.

Examples:

Create Admin User

gitea admin user create \
  --username admin \
  --email [e-mail] \
  --password AdminPassword123 \
  --admin

gitea admin user create \
  --username developer \
  --email [e-mail] \
  --random-password \
  --random-password-length 16

gitea admin user create \
  --username ci-bot \
  --email [e-mail] \
  --user-type bot \
  --access-token \
  --access-token-scopes "write:repository,read:organization"

List Users

gitea admin user list

Displays all registered users.

Change Password

gitea admin user change-password \
  --username johndoe \
  --password newpassword

Delete User

gitea admin user delete --username johndoe

Options:

• --id - Delete by user ID instead of username
• --purge - Purge user data completely

Generate Access Token

gitea admin user generate-access-token \
  --username johndoe \
  --token-name "API Token" \
  --scopes "write:repository,read:user"

Force Password Change

gitea admin user must-change-password \
  --username johndoe \
  --yes

Authentication Sources

Manage external authentication sources via CLI (see cmd/admin_auth.go).

List Authentication Sources

gitea admin auth list

Outputs a table showing:

• ID
• Name
• Type (LDAP, OAuth2, SMTP, etc.)
• Enabled status

Add LDAP Authentication

See Authentication Documentation for detailed LDAP configuration.

gitea admin auth add-ldap \
  --name "Corporate LDAP" \
  --security-protocol ldaps \
  --host ldap.example.com \
  --port 636 \
  --bind-dn "cn=gitea,ou=service,dc=example,dc=com" \
  --bind-password "service-password" \
  --user-search-base "ou=users,dc=example,dc=com" \
  --user-filter "(uid=%s)" \
  --email-attribute mail

Add OAuth2 Authentication

gitea admin auth add-oauth \
  --name "GitHub" \
  --provider github \
  --key "client-id" \
  --secret "client-secret"

Add SMTP Authentication

gitea admin auth add-smtp \
  --name "Corporate Email" \
  --host mail.example.com \
  --port 587 \
  --auth-type PLAIN

Update Authentication Source

gitea admin auth update-ldap --id 1 --port 636

Delete Authentication Source

gitea admin auth delete --id 1

Repository Operations

Sync Repository Releases

Synchronize repository releases with Git tags (see cmd/admin.go:98-157):

gitea admin repo-sync-releases

This command:

• Scans all repositories
• Compares tags with releases
• Creates releases for tags without corresponding releases

Regenerate Data

Regenerate Git hooks and SSH keys (see cmd/admin_regenerate.go).

Regenerate Git Hooks

gitea admin regenerate hooks

Regenerates Git hooks for all repositories. Useful after:

• Gitea upgrades
• Manual hook modifications
• Repository corruption

Regenerate SSH Keys

gitea admin regenerate keys

Rebuilds the authorized_keys file from the database.

Send Mail to All Users

Send an administrative message to all users:

gitea admin sendmail \
  --title "Maintenance Notice" \
  --content "System maintenance scheduled for Saturday" \
  --force

Backup and Restore

See Backup and Restore Documentation for complete details.

Create Backup

gitea dump --file backup.zip

Restore Repository

gitea restore-repo \
  --repo_dir /backup/repos/owner/repo.git \
  --owner_name owner \
  --repo_name repo

Database Operations

Run Migrations

gitea migrate

Manually run database migrations.

Migrate Storage

Migrate storage between different backends:

gitea migrate-storage \
  --type lfs \
  --storage local-lfs

Supported types:

• lfs - LFS objects
• avatars - User avatars
• attachments - Issue/comment attachments
• packages - Package registry data
• repo-avatars - Repository avatars

Configuration Management

View Configuration

gitea manager show-config

Displays the effective configuration including:

• Default values
• app.ini overrides
• Environment variable overrides

Logging Management

# Add logger
gitea manager logging add-logger \
  --name console \
  --level Info

# Remove logger
gitea manager logging remove-logger --name console

# Pause logging
gitea manager logging pause

# Resume logging
gitea manager logging resume

Doctor Commands

Diagnostic and repair tools:

gitea doctor check --all

Available Checks

• paths - Check path configurations
• db-version - Verify database version
• db-consistency - Check database consistency
• repo-integrity - Verify repository integrity
• check-hooks - Validate Git hooks
• check-db-consistency - Advanced database checks
• authorized-keys - Check SSH authorized_keys file
• config - Validate configuration

Run Specific Check

gitea doctor check --run db-version

Repair Mode

gitea doctor check --all --fix

Convert Database Encoding

gitea doctor convert --from utf8 --to utf8mb4

Certificate Management

Generate Self-Signed Certificate

gitea cert \
  --host localhost,example.com \
  --ca \
  --duration 8760h

Outputs:

• cert.pem - Certificate
• key.pem - Private key

Web Server

Start Gitea

gitea web

Options:

• --port - Override HTTP port
• --pid - Write PID to file
• --config - Specify config file location

Generate Commands

Generate Secret Keys

# Generate SECRET_KEY
gitea generate secret SECRET_KEY

# Generate INTERNAL_TOKEN
gitea generate secret INTERNAL_TOKEN

# Generate LFS_JWT_SECRET
gitea generate secret LFS_JWT_SECRET

# Generate JWT_SECRET
gitea generate secret JWT_SECRET

Hook Commands

Internal Git hook commands (used by Git, not for manual execution):

gitea hook --config /path/to/app.ini update
gitea hook --config /path/to/app.ini pre-receive
gitea hook --config /path/to/app.ini post-receive

Service Commands

Manager Commands

# Shutdown server gracefully
gitea manager shutdown

# Cancel shutdown
gitea manager cancel-shutdown

# Restart server
gitea manager restart

# Flush queues
gitea manager flush-queues

Environment Variables

Common environment variables for CLI commands:

# Specify config file
export GITEA_CUSTOM=/path/to/custom

# Specify work path
export GITEA_WORK_DIR=/path/to/work

# Override config values
export GITEA__database__DB_TYPE=postgres

Best Practices

1. Use Configuration File

   Always specify --config or set GITEA_CUSTOM to ensure commands use the correct configuration

2. Run as Correct User

   Execute commands as the same user that runs Gitea (typically git)

   sudo -u git gitea admin user list
   
3. Backup Before Major Operations

   Always backup before running regenerate or repair commands

4. Test in Development

   Test administrative commands in a development environment first

5. Script Repetitive Tasks

   Create scripts for common administrative tasks

Troubleshooting

Command Not Found

# Verify Gitea binary location
which gitea

# Or use full path
/usr/local/bin/gitea admin user list

Permission Denied

# Run as git user
sudo -u git gitea admin user list

# Or fix ownership
sudo chown git:git /path/to/gitea

Database Connection Failed

# Verify configuration
gitea doctor check --run config

# Check database is running
sudo systemctl status postgresql

Related Resources

• Configuration
• Authentication
• Database Setup
• Backup and Restore