Add CLI installers for Tea, Borg, and Git Credential Manager, and enhance setup script with improved authentication
This commit is contained in:
kdusek
205
GIT_CREDENTIAL_MANAGERS.md
Normal file
205
GIT_CREDENTIAL_MANAGERS.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user