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**:
  ```bash
  # 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**:
  ```bash
  # 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**:
  ```bash
  git config --global credential.helper osxkeychain
  ```

### 4. manager (Generic)
- **Built-in**: Simple in-memory cache
- **Configuration**:
  ```bash
  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:
   ```bash
   git config --global credential.helper manager
   # First push will prompt for username and token
   ```

### Method 2: Direct Credential Storage
```bash
# Store credentials for specific Gitea instance
git config --global credential.https://go-gitea.mywire.org.helper manager
```

### Method 3: Environment Variables
```bash
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
```bash
# 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
```bash
# 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)

```bash
# 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:

```bash
# 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
```