gitcaddy-server/GUIDE.md

# GitCaddy Users Guide

A comprehensive guide to using GitCaddy, a self-hosted Git repository management platform with AI capabilities, encrypted secrets management, and enterprise features.

## Table of Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [First-Time Setup](#first-time-setup)
- [Basic Repository Operations](#basic-repository-operations)
  - [Creating a Repository](#creating-a-repository)
  - [Cloning and Pushing Code](#cloning-and-pushing-code)
  - [Managing Branches and Tags](#managing-branches-and-tags)
  - [File Operations](#file-operations)
- [Collaboration Workflows](#collaboration-workflows)
  - [Working with Issues](#working-with-issues)
  - [Pull Request Workflow](#pull-request-workflow)
  - [Code Reviews](#code-reviews)
  - [Project Boards](#project-boards)
- [Wiki Documentation](#wiki-documentation)
- [CI/CD with GitCaddy Actions](#cicd-with-gitcaddy-actions)
  - [Creating Workflows](#creating-workflows)
  - [Managing Runners](#managing-runners)
  - [Secrets and Variables](#secrets-and-variables)
- [Vault: Encrypted Secrets Management](#vault-encrypted-secrets-management)
  - [Creating Secrets](#creating-secrets)
  - [Using Secrets in CI/CD](#using-secrets-in-cicd)
  - [Audit Logs and Version History](#audit-logs-and-version-history)
- [Package Registry](#package-registry)
  - [Publishing Packages](#publishing-packages)
  - [Installing Packages](#installing-packages)
- [AI-Powered Features](#ai-powered-features)
  - [AI Code Review](#ai-code-review)
  - [AI Issue Triage](#ai-issue-triage)
  - [Code Explanation](#code-explanation)
- [Organizations and Teams](#organizations-and-teams)
  - [Creating Organizations](#creating-organizations)
  - [Managing Teams](#managing-teams)
  - [Team Permissions](#team-permissions)
- [Landing Pages and Custom Domains](#landing-pages-and-custom-domains)
- [Authentication and Security](#authentication-and-security)
  - [Two-Factor Authentication](#two-factor-authentication)
  - [SSH and GPG Keys](#ssh-and-gpg-keys)
  - [OAuth2 and SSO](#oauth2-and-sso)
- [Customization and Settings](#customization-and-settings)
  - [User Preferences](#user-preferences)
  - [Repository Settings](#repository-settings)
  - [Webhooks and Integrations](#webhooks-and-integrations)
- [Tips and Best Practices](#tips-and-best-practices)
- [Troubleshooting](#troubleshooting)

---

## Introduction

GitCaddy is a powerful, self-hosted Git repository management platform that provides a complete solution for version control, issue tracking, CI/CD workflows, package registry, and team collaboration. Built as an enhanced fork of Gitea, GitCaddy adds enterprise features including:

- **AI-powered code review and issue triage**
- **Vault encrypted secrets management** with audit logging
- **Package registry** supporting npm, Maven, Docker, PyPI, Go, Cargo, NuGet, and more
- **Custom landing pages** with SSL/TLS support
- **Comprehensive internationalization** with 18+ supported languages
- **GitCaddy Actions** for CI/CD automation
- **Advanced collaboration tools** including project boards, wikis, and time tracking

This guide will walk you through everything you need to know to effectively use GitCaddy, from initial setup to advanced workflows.

---

## Getting Started

### Prerequisites

Before installing GitCaddy, ensure you have the following:

- **Go runtime** (version 1.18 or higher)
- **Node.js and npm** (for building frontend assets)
- **Git** (version 2.0 or higher)
- **Database**: PostgreSQL, MySQL, SQLite, or MSSQL
- **Operating System**: Linux, macOS, or Windows

### Installation

Follow these steps to install GitCaddy on your server:

#### 1. Clone the Repository

```bash
git clone https://github.com/your-org/gitcaddy.git
cd gitcaddy
```

#### 2. Build the Backend

```bash
# Install Go dependencies
go mod download

# Build the GitCaddy binary
go build -o gitcaddy
```

#### 3. Build the Frontend

```bash
# Install Node.js dependencies
npm install

# Build frontend assets
npm run build
```

#### 4. Configure the Database

Create a configuration file `custom/conf/app.ini` with your database settings:

```ini
[database]
DB_TYPE = postgres
HOST = localhost:5432
NAME = gitcaddy
USER = gitcaddy_user
PASSWD = your_secure_password
```

Supported database types: `postgres`, `mysql`, `sqlite3`, `mssql`

#### 5. Start GitCaddy

```bash
./gitcaddy web
```

By default, GitCaddy runs on port 3000. Access it at `http://localhost:3000`

### First-Time Setup

When you first access GitCaddy, you'll be guided through a web-based installation wizard:

1. **Database Configuration**: Verify or adjust database connection settings
2. **General Settings**: Configure site title, domain, and SSH/HTTP ports
3. **Administrator Account**: Create your admin user account
4. **Optional Settings**: Configure email, server paths, and additional features
5. **Install**: Click "Install GitCaddy" to complete setup

After installation, you'll be redirected to your dashboard where you can start creating repositories and inviting users.

---

## Basic Repository Operations

### Creating a Repository

To create a new repository:

1. Click the **"+"** icon in the top navigation bar
2. Select **"New Repository"**
3. Fill in the repository details:
   - **Owner**: Select your user or an organization
   - **Repository Name**: Choose a unique name
   - **Description**: Optional description of your project
   - **Visibility**: Public or Private
   - **Initialize Repository**: Optionally add README, .gitignore, and license
   - **Template**: Search for and select a repository template

4. Click **"Create Repository"**

**Example**: Creating a Node.js project repository

```
Owner: myusername
Repository Name: my-nodejs-app
Description: A sample Node.js application
Visibility: Private
✓ Initialize with README
.gitignore: Node
License: MIT License
```

### Cloning and Pushing Code

After creating a repository, clone it to your local machine:

```bash
# Clone via HTTPS
git clone https://gitcaddy.example.com/username/my-nodejs-app.git

# Or clone via SSH
git clone git@gitcaddy.example.com:username/my-nodejs-app.git
```

Add files and push your first commit:

```bash
cd my-nodejs-app
echo "# My Node.js App" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main
```

### Managing Branches and Tags

#### Creating a Branch

```bash
# Create and switch to a new branch
git checkout -b feature/new-feature

# Push the branch to GitCaddy
git push origin feature/new-feature
```

In the GitCaddy web interface:
1. Navigate to your repository
2. Click the **branch dropdown** (usually shows "main")
3. Type a new branch name and click **"Create branch"**

#### Branch Protection Rules

Protect important branches from direct pushes:

1. Go to **Settings** → **Branches**
2. Click **"Add Rule"**
3. Configure protection settings:
   - Require pull request reviews
   - Require status checks to pass
   - Restrict who can push
   - Enable force push protection

#### Creating Tags

```bash
# Create an annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# Push tags to GitCaddy
git push origin --tags
```

### File Operations

GitCaddy provides a web-based file editor for quick changes:

1. Navigate to a file in your repository
2. Click the **pencil icon** to edit
3. Make your changes in the markdown-aware editor
4. Add a commit message
5. Choose to commit directly or create a new branch
6. Click **"Commit Changes"**

**Uploading Files:**
1. Navigate to the target directory
2. Click **"Upload file"**
3. Drag and drop files or click to browse
4. Add a commit message and commit

**Deleting Files:**
1. Navigate to the file
2. Click the **trash icon**
3. Confirm deletion with a commit message

---

## Collaboration Workflows

### Working with Issues

Issues are the foundation of project tracking in GitCaddy. They support rich features including labels, milestones, assignments, time tracking, and dependencies.

#### Creating an Issue

1. Navigate to your repository
2. Click the **"Issues"** tab
3. Click **"New Issue"**
4. Fill in the details:
   - **Title**: Brief description of the issue
   - **Description**: Detailed explanation using markdown
   - **Labels**: Categorize the issue (bug, enhancement, question, etc.)
   - **Milestone**: Associate with a project milestone
   - **Assignees**: Assign team members
   - **Projects**: Add to a project board

5. Click **"Create Issue"**

**Example Issue:**

```markdown
Title: Add user authentication to API

Description:
## Problem
The API currently lacks authentication, allowing unauthorized access.

## Proposed Solution
Implement JWT-based authentication with the following endpoints:
- POST /api/auth/login
- POST /api/auth/register
- POST /api/auth/refresh

## Acceptance Criteria
- [ ] JWT tokens are generated on successful login
- [ ] Protected endpoints validate tokens
- [ ] Refresh token mechanism is implemented
- [ ] Unit tests cover all auth flows

Labels: enhancement, security
Milestone: v2.0.0
Assignees: @developer1, @developer2
```

#### Time Tracking

Track time spent on issues:

1. Open an issue
2. In the sidebar, find **"Time Tracking"**
3. Click **"Add Time"** and enter hours/minutes
4. View total time spent and estimates

#### Issue Dependencies

Create dependencies between issues:

1. Open an issue
2. In the description or comments, reference another issue: `Depends on #123`
3. GitCaddy automatically creates a dependency link
4. The dependent issue cannot be closed until dependencies are resolved

### Pull Request Workflow

Pull requests (PRs) enable code review and collaborative development.

#### Creating a Pull Request

1. Push your feature branch to GitCaddy
2. Navigate to the repository
3. Click **"New Pull Request"**
4. Select the base branch (e.g., `main`) and compare branch (e.g., `feature/new-feature`)
5. Review the diff visualization
6. Fill in PR details:
   - **Title**: Descriptive title
   - **Description**: Explain changes, link related issues
   - **Reviewers**: Request reviews from team members
   - **Labels, Milestone, Assignees**: Same as issues

7. Click **"Create Pull Request"**

**Example PR Description:**

```markdown
## Changes
This PR implements user authentication for the API as described in #45.

## Implementation Details
- Added JWT middleware for token validation
- Created auth controller with login/register/refresh endpoints
- Implemented password hashing with bcrypt
- Added comprehensive unit tests (95% coverage)

## Testing
- All existing tests pass
- New tests cover authentication flows
- Manual testing completed on staging environment

Closes #45
```

#### Reviewing Pull Requests

As a reviewer:

1. Open the pull request
2. Navigate to the **"Files changed"** tab
3. Review the diff:
   - Click on a line number to add inline comments
   - Suggest specific code changes
   - Mark files as reviewed

4. Submit your review:
   - **Comment**: General feedback without approval
   - **Approve**: Approve the changes
   - **Request Changes**: Block merging until issues are addressed

#### Merging Pull Requests

Once approved and status checks pass:

1. Click the **"Merge Pull Request"** button
2. Choose a merge strategy:
   - **Create a merge commit**: Preserves all commits with a merge commit
   - **Squash and merge**: Combines all commits into one
   - **Rebase and merge**: Replays commits on top of base branch

3. Confirm the merge
4. Optionally delete the feature branch

### Code Reviews

GitCaddy supports comprehensive code review features:

- **Inline comments**: Comment on specific lines of code
- **Suggestion blocks**: Propose code changes that can be committed directly
- **Review threads**: Discussions can be marked as resolved
- **Status checks**: Automated checks must pass before merging
- **Required approvals**: Enforce minimum number of approvals

**Making a code suggestion:**

```markdown
```suggestion
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}
```
```

### Project Boards

Organize work using Kanban-style project boards:

1. Navigate to your repository
2. Click the **"Projects"** tab
3. Click **"New Project"**
4. Choose a template or start blank
5. Create columns (e.g., "To Do", "In Progress", "Done")
6. Add issues and pull requests to columns
7. Drag and drop cards between columns

**Best Practice**: Use automation rules to move cards automatically based on issue/PR status.

---

## Wiki Documentation

Every repository includes a wiki for documentation.

### Creating Wiki Pages

1. Navigate to the **"Wiki"** tab in your repository
2. Click **"New Page"**
3. Enter a page title
4. Write content using the EasyMDE markdown editor with live preview
5. Click **"Save Page"**

### Wiki Features

- **Markdown support**: Full markdown syntax including tables, code blocks, and images
- **Mermaid diagrams**: Embed flowcharts, sequence diagrams, and more
- **Math formulas**: Use KaTeX for mathematical notation
- **Page hierarchy**: Organize pages with forward slashes (e.g., `Getting Started/Installation`)
- **History**: View page revisions and revert changes
- **Search**: Full-text search across all wiki pages

**Example Wiki Page:**

```markdown
# API Documentation

## Authentication

All API requests require a JWT token in the Authorization header:

```http
GET /api/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## Endpoints

### GET /api/users

Returns a list of users.

**Response:**
```json
{
  "users": [
    {"id": 1, "username": "alice"},
    {"id": 2, "username": "bob"}
  ]
}
```

## Rate Limiting

API requests are limited to 100 requests per hour per user.
```

---

## CI/CD with GitCaddy Actions

GitCaddy Actions provides integrated CI/CD automation similar to GitHub Actions.

### Creating Workflows

Workflows are defined in YAML files stored in `.gitea/workflows/` directory.

#### Example: Node.js Test Workflow

Create `.gitea/workflows/test.yml`:

```yaml
name: Node.js Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [14, 16, 18]
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Upload coverage
        uses: actions/upload-artifact@v3
        with:
          name: coverage-report
          path: coverage/
```

Commit and push this file to trigger the workflow.

### Managing Runners

Runners execute your workflow jobs. GitCaddy supports self-hosted runners.

#### Registering a Runner

1. Navigate to **Settings** → **Actions** → **Runners**
2. Click **"Add Runner"**
3. Follow the instructions to download and configure the runner on your machine:

```bash
# Download runner
wget https://gitcaddy.example.com/actions/runner/download

# Extract and configure
./config.sh --url https://gitcaddy.example.com --token YOUR_RUNNER_TOKEN

# Start the runner
./run.sh
```

#### Monitoring Runners

- View runner status (online/offline) in the Runners page
- Check runner tasks and job history
- Run bandwidth tests to verify connectivity

### Secrets and Variables

Store sensitive data like API keys and passwords securely.

#### Adding Secrets

1. Navigate to **Settings** → **Secrets and Variables** → **Actions**
2. Click **"New repository secret"**
3. Enter a name (e.g., `API_KEY`) and value
4. Click **"Add secret"**

#### Using Secrets in Workflows

```yaml
steps:
  - name: Deploy to production
    run: ./deploy.sh
    env:
      API_KEY: ${{ secrets.API_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
```

**Security Note**: Secrets are encrypted and never exposed in logs.

---

## Vault: Encrypted Secrets Management

Vault is an enterprise feature providing advanced encrypted secrets management with version history and audit logging.

### Creating Secrets

1. Navigate to **Settings** → **Vault**
2. Click **"New Secret"**
3. Enter secret details:
   - **Key**: Secret identifier (e.g., `production-db-password`)
   - **Value**: Secret content (automatically encrypted)
   - **Description**: Optional description

4. Click **"Create Secret"**

### Using Secrets in CI/CD

Vault secrets can be accessed in workflows using access tokens.

#### Generate an Access Token

1. In Vault settings, click **"Access Tokens"**
2. Click **"Generate Token"**
3. Configure token permissions:
   - **Scope**: Select specific secrets or all secrets
   - **Expiration**: Set token lifetime
   - **Permissions**: Read-only or read-write

4. Copy the generated token (shown only once)

#### Use Token in Workflow

```yaml
steps:
  - name: Fetch database credentials
    run: |
      curl -H "Authorization: Bearer ${{ secrets.VAULT_TOKEN }}" \
           https://gitcaddy.example.com/api/vault/secrets/production-db-password
```

### Audit Logs and Version History

Vault maintains comprehensive audit logs:

1. Navigate to **Vault** → **Audit Logs**
2. View all operations:
   - Secret creation, updates, deletions
   - Access token generation and usage
   - User who performed each action
   - Timestamp of each operation

3. **Version History**: Click on a secret to view all previous versions
4. **Rollback**: Restore a previous version if needed

**Vault Licensing Tiers:**
- **Solo**: Basic secrets management
- **Pro**: Advanced access controls
- **Team**: Multi-user collaboration features
- **Enterprise**: Full audit logging and compliance features

---

## Package Registry

GitCaddy includes a multi-format package registry supporting popular ecosystems.

### Publishing Packages

#### npm Packages

Configure npm to use GitCaddy registry:

```bash
# Set registry URL
npm config set registry https://gitcaddy.example.com/api/packages/username/npm/

# Authenticate
npm login --registry=https://gitcaddy.example.com/api/packages/username/npm/

# Publish package
npm publish
```

#### Docker Images

```bash
# Login to registry
docker login gitcaddy.example.com

# Tag image
docker tag myimage:latest gitcaddy.example.com/username/myimage:latest

# Push image
docker push gitcaddy.example.com/username/myimage:latest
```

#### Maven Packages

Add to your `pom.xml`:

```xml
<distributionManagement>
  <repository>
    <id>gitcaddy</id>
    <url>https://gitcaddy.example.com/api/packages/username/maven</url>
  </repository>
</distributionManagement>
```

Deploy with Maven:

```bash
mvn deploy
```

#### Python Packages (PyPI)

Configure `.pypirc`:

```ini
[distutils]
index-servers = gitcaddy

[gitcaddy]
repository = https://gitcaddy.example.com/api/packages/username/pypi
username = your-username
password = your-token
```

Upload package:

```bash
python setup.py sdist bdist_wheel
twine upload --repository gitcaddy dist/*
```

### Installing Packages

GitCaddy provides installation instructions for each package in the web interface:

1. Navigate to **Packages** in your repository or user profile
2. Click on a package
3. View ecosystem-specific installation commands

**Example for npm:**

```bash
npm install --registry=https://gitcaddy.example.com/api/packages/username/npm/ package-name
```

---

## AI-Powered Features

GitCaddy integrates AI capabilities to enhance code quality and productivity.

### AI Code Review

Enable AI-assisted code reviews to receive automated feedback on pull requests.

#### Enabling AI Code Review

1. Navigate to **Repository Settings** → **AI Features**
2. Enable **"AI Code Review"**
3. Configure review preferences:
   - **Review depth**: Quick scan or comprehensive analysis
   - **Focus areas**: Security, performance, best practices
   - **Auto-comment**: Automatically post suggestions as PR comments

#### How It Works

When a pull request is created:
1. AI analyzes the code changes
2. Identifies potential issues:
   - Security vulnerabilities
   - Performance bottlenecks
   - Code smells and anti-patterns
   - Style inconsistencies

3. Posts suggestions as PR comments
4. Provides explanations and recommended fixes

**Example AI Comment:**

> 🤖 **AI Code Review**
> 
> **Potential Security Issue**: SQL query is vulnerable to injection attacks.
> 
> **Location**: `src/database.js:45`
> 
> **Recommendation**: Use parameterized queries instead of string concatenation.
> 
> ```javascript
> // Instead of:
> const query = `SELECT * FROM users WHERE id = ${userId}`;
> 
> // Use:
> const query = 'SELECT * FROM users WHERE id = ?';
> db.query(query, [userId]);
> ```

### AI Issue Triage

AI automatically categorizes and prioritizes new issues.

#### Enabling AI Issue Triage

1. Navigate to **Repository Settings** → **AI Features**
2. Enable **"AI Issue Triage"**
3. Configure triage rules:
   - **Auto-label**: Automatically apply labels based on content
   - **Priority assignment**: Suggest priority levels
   - **Similar issues**: Link to related issues

#### How It Works

When an issue is created:
1. AI analyzes the issue title and description
2. Suggests appropriate labels (bug, enhancement, documentation, etc.)
3. Identifies priority based on keywords and context
4. Finds similar existing issues to prevent duplicates

### Code Explanation

Get AI-generated explanations for complex code.

#### Using Code Explanation

1. Navigate to a file in your repository
2. Select a code block
3. Click the **"Explain with AI"** button
4. View the explanation in plain language

**Example:**

```javascript
const memoize = (fn) => {
  const cache = new Map();
  return (...args) => {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key);
    const result = fn(...args);
    cache.set(key, result);
    return result;
  };
};
```

**AI Explanation:**
> This code implements a memoization function, which is a performance optimization technique. It creates a cache to store the results of expensive function calls. When the function is called with the same arguments again, it returns the cached result instead of recalculating it. This is useful for pure functions with expensive computations.

---

## Organizations and Teams

Organizations enable collaborative management of multiple repositories with team-based permissions.

### Creating Organizations

1. Click the **"+"** icon in the top navigation
2. Select **"New Organization"**
3. Fill in organization details:
   - **Organization Name**: Unique identifier
   - **Display Name**: Full name
   - **Description**: Organization purpose
   - **Website**: Optional URL
   - **Location**: Optional location

4. Click **"Create Organization"**

### Managing Teams

Teams group users within an organization and control access to repositories.

#### Creating a Team

1. Navigate to your organization
2. Click the **"Teams"** tab
3. Click **"New Team"**
4. Configure team settings:
   - **Team Name**: Descriptive name
   - **Description**: Team purpose
   - **Visibility**: Visible or hidden

5. Click **"Create Team"**

#### Adding Team Members

1. Open the team
2. Click **"Add Member"**
3. Search for users and click **"Add"**
4. Assign roles:
   - **Member**: Standard access
   - **Admin**: Can manage team settings

### Team Permissions

Control repository access per team:

1. Navigate to **Teams** → Select a team
2. Click **"Repositories"**
3. Click **"Add Repository"**
4. Select repository and set permissions:
   - **Read**: View code and issues
   - **Write**: Push commits, create issues/PRs
   - **Admin**: Full repository management

**Best Practice**: Use teams to implement the principle of least privilege. Grant only the permissions necessary for each team's responsibilities.

---

## Landing Pages and Custom Domains

Create professional landing pages for your repositories with custom domains.

### Enabling Landing Pages

1. Navigate to **Repository Settings** → **Pages**
2. Enable **"Landing Pages"**
3. Configure page settings:
   - **Source**: Select branch and directory (e.g., `main/docs`)
   - **Custom Domain**: Enter your domain (e.g., `docs.myproject.com`)
   - **SSL/TLS**: Enable HTTPS with automatic certificate

4. Customize your landing page:
   - **Hero Section**: Add title, subtitle, and call-to-action
   - **Features**: Highlight key features with icons
   - **Pricing**: Display pricing tiers
   - **Branding**: Upload logo and customize colors

5. Click **"Save Settings"**

### Configuring Custom Domains

1. In your DNS provider, add a CNAME record:
   ```
   docs.myproject.com CNAME gitcaddy.example.com
   ```

2. In GitCaddy Pages settings, enter the custom domain
3. Click **"Verify Domain"**
4. Enable **"Enforce HTTPS"** for automatic SSL certificate

Your landing page will be accessible at `https://docs.myproject.com`

### SEO Optimization

Optimize landing pages for search engines:

1. Navigate to **Pages** → **SEO Settings**
2. Configure meta tags:
   - **Title**: Page title for search results
   - **Description**: Meta description
   - **Keywords**: Relevant keywords
   - **Open Graph**: Social media preview settings

---

## Authentication and Security

GitCaddy provides multiple authentication methods and security features.

### Two-Factor Authentication

Enhance account security with 2FA.

#### Enabling 2FA

1. Navigate to **Settings** → **Security**
2. Click **"Enable Two-Factor Authentication"**
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
4. Enter the verification code
5. Save recovery codes in a secure location
6. Click **"Enable 2FA"**

#### WebAuthn (Hardware Keys)

Use hardware security keys for passwordless authentication:

1. Navigate to **Settings** → **Security** → **WebAuthn**
2. Click **"Add Security Key"**
3. Enter a nickname for the key
4. Follow browser prompts to register your key
5. Test the key by logging out and back in

### SSH and GPG Keys

#### Adding SSH Keys

1. Generate an SSH key pair on your machine:
   ```bash
   ssh-keygen -t ed25519 -C "your_email@example.com"
   ```

2. Navigate to **Settings** → **SSH / GPG Keys**
3. Click **"Add Key"**
4. Paste your public key (`~/.ssh/id_ed25519.pub`)
5. Give it a descriptive name
6. Click **"Add Key"**

Test your SSH connection:
```bash
ssh -T git@gitcaddy.example.com
```

#### Signing Commits with GPG

1. Generate a GPG key:
   ```bash
   gpg --full-generate-key
   ```

2. Export your public key:
   ```bash
   gpg --armor --export your_email@example.com
   ```

3. Navigate to **Settings** → **SSH / GPG Keys** → **GPG Keys**
4. Click **"Add Key"** and paste your public key
5. Configure Git to sign commits:
   ```bash
   git config --global user.signingkey YOUR_KEY_ID
   git config --global commit.gpgsign true
   ```

Signed commits display a "Verified" badge in GitCaddy.

### OAuth2 and SSO

Configure external authentication providers for single sign-on.

#### Supported Providers

- GitHub
- GitLab
- Google
- Microsoft Azure AD
- LDAP/Active Directory
- SAML 2.0
- OpenID Connect

#### Configuring OAuth2 (Admin)

1. Navigate to **Site Administration** → **Authentication Sources**
2. Click **"Add Authentication Source"**
3. Select provider type (e.g., **OAuth2**)
4. Configure provider settings:
   - **Client ID**: From provider
   - **Client Secret**: From provider
   - **Authorization URL**: Provider-specific
   - **Token URL**: Provider-specific
   - **User Info URL**: Provider-specific

5. Click **"Add Authentication Source"**

Users can now log in using the external provider.

---

## Customization and Settings

### User Preferences

Personalize your GitCaddy experience:

1. Navigate to **Settings** → **Profile**
2. Configure preferences:
   - **Display Name**: Your full name
   - **Email**: Primary email address
   - **Website**: Personal or company website
   - **Location**: Your location
   - **Biography**: Brief description

3. **Appearance Settings**:
   - **Language**: Select from 18+ supported languages (English, German, Hindi, Italian, Polish, Portuguese, etc.)
   - **Theme**: Light, dark, or auto (system preference)

4. **Notification Settings**:
   - **Email Notifications**: Configure which events trigger emails
   - **Web Notifications**: Enable browser notifications
   - **Watching**: Auto-watch repositories you create or contribute to

### Repository Settings

Configure individual repository settings:

1. Navigate to your repository → **Settings**
2. **General**:
   - Repository name, description, website
   - Visibility (public/private)
   - Template repository
   - Archive repository

3. **Features**:
   - Enable/disable issues, wiki, projects, actions
   - External wiki URL
   - External issue tracker

4. **Collaborators**:
   - Add users with specific permissions
   - Manage access levels

5. **Branches**:
   - Default branch
   - Branch protection rules
   - Required status checks

6. **Webhooks**:
   - Configure webhooks for external integrations

### Webhooks and Integrations

Integrate GitCaddy with external services.

#### Creating a Webhook

1. Navigate to **Repository Settings** → **Webhooks**
2. Click **"Add Webhook"**
3. Configure webhook:
   - **Payload URL**: Endpoint to receive events
   - **Content Type**: JSON or form-encoded
   - **Secret**: Optional secret for verification
   - **Events**: Select which events trigger the webhook
     - Push events
     - Pull request events
     - Issue events
     - Release events
     - etc.

4. Click **"Add Webhook"**

#### Supported Integrations

GitCaddy provides pre-configured integrations for:

- **Slack**: Post notifications to Slack channels
- **Discord**: Send updates to Discord servers
- **Microsoft Teams**: Integrate with Teams channels
- **Matrix**: Connect to Matrix chat rooms
- **Telegram**: Send notifications to Telegram
- **Email**: Custom email notifications

**Example: Slack Integration**

1. Create an incoming webhook in Slack
2. In GitCaddy, add a Slack webhook
3. Paste the Slack webhook URL
4. Select events to post (push, PR, issues)
5. Customize message format and channel

---

## Tips and Best Practices

### Repository Management

1. **Use Templates**: Create repository templates for common project structures to save time
2. **Branch Protection**: Always enable branch protection on `main` and `production` branches
3. **Required Reviews**: Enforce at least one code review before merging pull requests
4. **Status Checks**: Set up CI/CD workflows as required status checks
5. **CODEOWNERS File**: Create a `CODEOWNERS` file to automatically request reviews from relevant team members

### Issue Tracking

1. **Labels**: Establish a consistent labeling system across repositories
2. **Templates**: Create issue templates for bug reports, feature requests, and questions
3. **Milestones**: Use milestones to track progress toward releases
4. **Project Boards**: Visualize work with project boards for sprint planning
5. **Time Tracking**: Estimate and track time for better project planning

### Pull Requests

1. **Small PRs**: Keep pull requests focused and small for easier review
2. **Descriptive Titles**: Write clear, descriptive PR titles
3. **Link Issues**: Always reference related issues in PR descriptions
4. **Draft PRs**: Use draft pull requests for work-in-progress code
5. **Review Checklist**: Create a PR template with a review checklist

### CI/CD Workflows

1. **Matrix Testing**: Test across multiple versions and platforms
2. **Caching**: Cache dependencies to speed up workflow runs
3. **Artifacts**: Upload build artifacts and test results
4. **Conditional Jobs**: Use conditions to skip unnecessary jobs
5. **Secrets Management**: Use Vault for sensitive credentials

### Security

1. **2FA**: Require two-factor authentication for all organization members
2. **Signed Commits**: Enforce GPG-signed commits for critical repositories
3. **Dependency Scanning**: Set up automated dependency vulnerability scanning
4. **Secret Scanning**: Enable secret scanning to prevent credential leaks
5. **Regular Audits**: Review access permissions and audit logs regularly

### Performance

1. **LFS for Large Files**: Use Git LFS for binary files and large assets
2. **Shallow Clones**: Use shallow clones in CI/CD to reduce clone time
3. **Archive Inactive Repos**: Archive repositories that are no longer maintained
4. **Cleanup**: Regularly clean up old branches and tags

---

## Troubleshooting

### Authentication Issues

**Problem**: Cannot push or pull from repository

**Solutions**:
1. Verify SSH key is added to your GitCaddy account
2. Test SSH connection: `ssh -T git@gitcaddy.example.com`
3. For HTTPS, ensure you're using a personal access token, not your password
4. Check repository permissions (you may only have read access)

**Problem**: 2FA code not working

**Solutions**:
1. Ensure your device clock is synchronized (2FA is time-based)
2. Try using a recovery code instead
3. Contact an administrator to reset 2FA if locked out

### Workflow Issues

**Problem**: GitCaddy Actions workflow not triggering

**Solutions**:
1. Verify the workflow file is in `.gitea/workflows/` directory
2. Check YAML syntax (use a YAML validator)
3. Ensure the trigger events match your actions (e.g., `on: push`)
4. Check if Actions are enabled in repository settings
5. Verify at least one runner is online and available

**Problem**: Workflow fails with "runner not found"

**Solutions**:
1. Check runner status in **Settings** → **Actions** → **Runners**
2. Restart the runner service
3. Verify runner labels match workflow requirements
4. Check runner logs for connection issues

### Repository Issues

**Problem**: Large repository clone is slow

**Solutions**:
1. Use shallow clone: `git clone --depth=1 <url>`
2. Enable Git LFS for large files
3. Consider using sparse checkout for monorepos
4. Check network connectivity and bandwidth

**Problem**: Cannot merge pull request

**Solutions**:
1. Resolve merge conflicts locally and push
2. Ensure all required status checks pass
3. Verify you have required approvals
4. Check branch protection rules
5. Ensure you have write permissions

### Vault Issues

**Problem**: Cannot access Vault secrets in workflow

**Solutions**:
1. Verify access token has correct permissions
2. Check token hasn't expired
3. Ensure secret key name matches exactly (case-sensitive)
4. Verify Vault is enabled for the repository/organization

### Package Registry Issues

**Problem**: Cannot publish package

**Solutions**:
1. Verify authentication credentials
2. Check package name doesn't conflict with existing package
3. Ensure you have write permissions to the registry
4. Review package manifest for errors
5. Check registry URL is correct for the package type

**Problem**: Cannot install package

**Solutions**:
1. Verify registry URL is configured correctly
2. Check authentication if package is private
3. Ensure package version exists
4. Try clearing package manager cache

### Performance Issues

**Problem**: GitCaddy web interface is slow

**Solutions**:
1. Check server resources (CPU, memory, disk)
2. Review database performance and optimize queries
3. Enable caching in `app.ini` configuration
4. Check for large repositories causing indexing delays
5. Review logs for errors: `./gitcaddy admin logs`

**Problem**: Git operations are slow

**Solutions**:
1. Run `git gc` to optimize repository
2. Check if repository needs LFS for large files
3. Verify network latency between client and server
4. Consider using SSH instead of HTTPS (or vice versa)

### Getting Help

If you continue to experience issues:

1. **Documentation**: Check the official GitCaddy documentation
2. **Community Forum**: Search or post in the community forum
3. **Issue Tracker**: Report bugs in the GitCaddy repository
4. **Admin Logs**: Review system logs in **Site Administration** → **Monitoring**
5. **Support**: Contact your GitCaddy administrator or support team

**Useful Commands**:

```bash
# Check GitCaddy version
./gitcaddy --version

# View logs
./gitcaddy admin logs

# Run diagnostics
./gitcaddy doctor

# Database maintenance
./gitcaddy admin regenerate hooks
./gitcaddy admin regenerate keys
```

---

## Conclusion

GitCaddy provides a comprehensive, self-hosted solution for Git repository management with powerful features for collaboration, automation, and security. This guide has covered the essential workflows and features to help you get started and become productive quickly.

For advanced topics, enterprise features, and administrative configuration, refer to the official GitCaddy documentation or contact your system administrator.

Happy coding! 🚀