tools-installer/GIT_CREDENTIAL_MANAGERS.md

Git Credential Managers for Gitea

Git credential managers provide secure storage and automatic retrieval of your Git credentials, eliminating the need to repeatedly enter usernames and passwords/tokens.

Supported Credential Managers

1. Git Credential Manager (GCM) - Console & GUI

• Cross-platform: Windows, macOS, Linux
• Official Microsoft project
• Console-First: Works perfectly in terminal without GUI
• Supports: HTTPS authentication, personal access tokens, OAuth
• Installation:

  # Linux (various distributions)
  sudo apt install git-credential-manager  # Ubuntu/Debian
  sudo yum install git-credential-manager  # RHEL/CentOS
  sudo pacman -S git-credential-manager     # Arch
  
  # macOS
  brew install git-credential-manager
  
  # Windows
  # Included with Git for Windows
  

• Console Usage: All operations are terminal-based, no GUI required

2. libsecret (Linux) - Console Only

• Linux native: Uses system keyring (GNOME Keyring, KWallet)
• Console-Only: No GUI components, pure terminal integration
• Installation:

  # Ubuntu/Debian
  sudo apt install libsecret-1-0 libsecret-1-dev
  
  # RHEL/CentOS
  sudo yum install libsecret-devel
  
  # Configure Git
  git config --global credential.helper /usr/share/doc/git/contrib/credential/gnome-keyring/git-credential-gnome-keyring
  

3. osxkeychain (macOS) - Console & GUI

• Built-in: Uses macOS Keychain
• Console-First: Works in terminal, can also access GUI keychain
• Configuration:

  git config --global credential.helper osxkeychain
  

4. manager (Generic)

• Built-in: Simple in-memory cache
• Configuration:

  git config --global credential.helper manager
  

Configuration for Gitea

Method 1: Personal Access Token

1. Generate token in Gitea: User Settings → Applications → Generate Token
2. Configure Git:

   git config --global credential.helper manager
   # First push will prompt for username and token
   

Method 2: Direct Credential Storage

# Store credentials for specific Gitea instance
git config --global credential.https://go-gitea.mywire.org.helper manager

Method 3: Environment Variables

export GIT_USERNAME="your_username"
export GIT_PASSWORD="your_access_token"

Security Considerations

✅ Secure Options

• GCM: Encrypts credentials, integrates with OS keyring
• libsecret/osxkeychain: Uses system secure storage
• Personal Access Tokens: More secure than passwords, can be revoked

⚠️ Less Secure Options

• Plain text: Storing credentials in .netrc files
• Environment variables: Visible in process list
• Cache-only: Credentials stored in memory only

Console-Only Operation

How It Works Without GUI

1. Terminal Prompts: Git prompts for username/token in console
2. Secure Storage: Credentials stored in system keyring (encrypted)
3. Automatic Retrieval: Subsequent Git operations use stored credentials
4. No GUI Required: All operations happen in terminal

Console Workflow Example

# First time - prompts in terminal
$ git push origin main
Username for 'https://go-gitea.mywire.org': kadu
Password for 'https://kadu@go-gitea.mywire.org': your_access_token

# Subsequent times - automatic
$ git push origin main
Everything up-to-date

# No more prompts!

Integration with Setup Script

The setup script can:

1. Detect available credential managers
2. Configure Git to use the best available option
3. Guide users through secure credential setup
4. Test credential storage and retrieval
5. Check all required Git presets after installation
6. Provide exact commands to complete configuration

Post-Installation Configuration Check

The installer automatically checks and configures these Git presets:

✅ Required Presets

• credential.helper manager - Global credential helper
• credential.https://github.com.helper manager - GitHub specific
• credential.https://gitlab.com.helper manager - GitLab specific
• credential.https://bitbucket.org.helper manager - Bitbucket specific
• credential.https://dev.azure.com.useHttpPath true - Azure DevOps
• Domain-specific helpers for Gitea servers

📋 Configuration Summary

After installation, the installer provides:

• Status of each preset (✓ configured, ✗ missing)
• Exact commands to complete configuration
• Testing commands to verify setup
• Usage guidance for different Git hosting services

5. Work entirely in console mode

Best Practices for Gitea

1. Use Personal Access Tokens instead of passwords
2. Set token expiration and permissions appropriately
3. Use HTTPS with credential manager for most users (console-friendly)
4. Use SSH keys for automated/scripted access
5. Regularly rotate tokens for security
6. Console environments: All credential managers work perfectly in SSH/remote terminals

Troubleshooting

Common Issues

• Token not working: Ensure token has required scopes (repo, user)
• Credential manager not found: Install appropriate package for your OS
• HTTPS certificate errors: Configure Git to trust your Gitea certificate
• Authentication prompts: Check credential helper configuration

Debug Commands

# Test credential storage
git credential fill

# Check current configuration
git config --global --show-origin --get credential.helper

# Clear stored credentials
git credential-cache exit

Example Workflow (Console Only)

# 1. Configure credential manager
git config --global credential.helper manager

# 2. First time authentication (console prompts)
$ git clone https://go-gitea.mywire.org/username/repo.git
Username for 'https://go-gitea.mywire.org': your_username
Password for 'https://go-gitea.mywire.org': your_access_token

# 3. Subsequent operations use stored credentials automatically
$ git pull
Already up to date.

$ git push
Everything up-to-date

# No more prompts - works in any terminal/SSH session!

Remote/SSH Console Usage

Credential managers work perfectly in remote SSH sessions:

# SSH into remote server
ssh user@server

# Git operations work with stored credentials
cd /project
git pull  # Uses stored credentials, no prompts
git push  # Automatic authentication