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]
Admin Commands
The admin command provides administrative operations (see cmd/admin.go:22-89).
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 [email protected] \
--password secretpassword
Username for the new account
Email address for the new account
Password for the account (required unless using --random-password)
Generate a random password
Length of the generated random password
Create user as administrator
Require password change on first login (default for all users except the first)
Create as a restricted user account
--user-type
string
default:"individual"
User type: individual or bot
Full, human-readable name of the user
Generate an access token for the user
--access-token-name
string
default:"gitea-admin"
Name for the generated access token
Comma-separated scopes: all, read:user, write:repository, etc.
gitea admin user create \
--username admin \
--email [email protected] \
--password AdminPassword123 \
--admin
List Users
Displays all registered users.
Change Password
gitea admin user change-password \
--username johndoe \
--password newpassword
Delete User
gitea admin user delete --username johndoe
--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
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
- 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
- Gitea upgrades
- Manual hook modifications
- Repository corruption
Regenerate SSH Keys
gitea admin regenerate keys
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
Manually run database migrations.
Migrate Storage
Migrate storage between different backends:
gitea migrate-storage \
--type lfs \
--storage local-lfs
lfs - LFS objectsavatars - User avatarsattachments - Issue/comment attachmentspackages - Package registry datarepo-avatars - Repository avatars
Configuration Management
View Configuration
gitea manager show-config
- 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:
Available Checks
paths - Check path configurationsdb-version - Verify database versiondb-consistency - Check database consistencyrepo-integrity - Verify repository integritycheck-hooks - Validate Git hookscheck-db-consistency - Advanced database checksauthorized-keys - Check SSH authorized_keys fileconfig - 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
cert.pem - Certificatekey.pem - Private key
Web Server
Start Gitea
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
Use Configuration File
Always specify --config or set GITEA_CUSTOM to ensure commands use the correct configuration
Run as Correct User
Execute commands as the same user that runs Gitea (typically git)sudo -u git gitea admin user list
Backup Before Major Operations
Always backup before running regenerate or repair commands
Test in Development
Test administrative commands in a development environment first
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
