Penggunaan Gitea

Pengenalan

Setelah instalasi Gitea berhasil, panduan ini akan membantu Anda memahami cara menggunakan Gitea untuk mengelola repository, user, organization, dan fitur-fitur lainnya.

Login dan Dashboard

First Login

1. Akses Gitea web interface:

   https://git.your-domain.com

2. Login dengan credentials yang dibuat saat instalasi

3. Dashboard akan menampilkan:

   • Recent activities
   • Your repositories
   • Organizations
   • Quick actions

Dashboard Overview

Dashboard terbagi menjadi beberapa section:

• Profile: Informasi user dan settings
• Repositories: Daftar repositories yang Anda miliki
• Organizations: Organizations yang Anda ikuti
• Starred: Repositories yang di-star
• Watching: Repositories yang Anda watch

User Management

Create New User (Admin Only)

1. Navigate ke Site Administration
2. Click User Accounts
3. Click Create User Account
4. Fill form:

   Username: developer1
   Email: developer1@example.com
   Password: strong_password

5. Click Create User Account

User Roles

Gitea memiliki beberapa user roles:

Role	Permissions
Admin	Full system access
Owner	Full repository/org access
Member	Read/write access
Collaborator	Invited external user
Guest	Read-only access

User Settings

Akses User Settings untuk configure:

Profile

• Avatar
• Full name
• Website
• Location
• Biography

Account

• Email addresses
• Password change
• SSH keys
• GPG keys

Security

• Two-Factor Authentication (2FA)
• Active sessions
• Account activity

Repository Management

Create New Repository

Via Web Interface

1. Click + icon di top right
2. Select New Repository
3. Fill repository details:

Owner: username/organization
Repository Name: my-project
Description: My awesome project
Visibility: Public/Private
Initialize Repository: ✓
- Add .gitignore: Node.js
- Add LICENSE: MIT
- Add README: Default

4. Click Create Repository

Via Command Line

# Create directory
mkdir my-project
cd my-project

# Initialize git
git init

# Create README
echo "# My Project" > README.md

# Configure git
git config user.name "Your Name"
git config user.email "your@email.com"

# Add remote
git remote add origin https://git.your-domain.com/username/my-project.git

# First commit
git add .
git commit -m "Initial commit"

# Push to Gitea
git push -u origin main

Repository Settings

General Settings

Repository Name: my-project
Description: Project description
Website: https://project-website.com
Topics: nodejs, docker, kubernetes
Visibility: Private/Public
Template: Make this repository a template

Branches

• Default branch: main
• Protected branches
• Branch permissions
• Delete branch after merge

Collaborators

Add users dengan different permissions:

• Read: View and clone
• Write: Push changes
• Admin: Full control

# Add collaborator via web
Repository → Settings → Collaborators → Add Collaborator

Webhooks

Setup webhooks untuk external integrations:

Payload URL: https://your-webhook-endpoint.com/hook
Content Type: application/json
Secret: your_webhook_secret
Events:
  - Push
  - Pull Request
  - Issues
  - Release

Example webhook payload:

{
  "ref": "refs/heads/main",
  "repository": {
    "name": "my-project",
    "full_name": "username/my-project",
    "html_url": "https://git.your-domain.com/username/my-project"
  },
  "commits": [
    {
      "id": "abc123",
      "message": "Update README",
      "author": {
        "name": "Developer",
        "email": "dev@example.com"
      }
    }
  ]
}

Clone Repository

HTTPS Clone

git clone https://git.your-domain.com/username/my-project.git
cd my-project

SSH Clone

# Add SSH key terlebih dahulu
git clone git@git.your-domain.com:username/my-project.git
cd my-project

Configure Credentials

# HTTPS - Credential helper
git config --global credential.helper store

# SSH - Generate key
ssh-keygen -t ed25519 -C "your@email.com"

# Add to Gitea
# Settings → SSH/GPG Keys → Add Key
cat ~/.ssh/id_ed25519.pub

Branch Management

Create Branch

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

# Or via web interface
Repository → Branches → New Branch

Protected Branches

1. Repository → Settings → Branches
2. Add branch protection rule:

Branch Name Pattern: main
Protection Rules:
  ✓ Disable force push
  ✓ Disable deletion
  ✓ Require pull request reviews
  ✓ Require status checks to pass
  ✓ Require linear history

Pull Requests

Create Pull Request

1. Push branch ke Gitea:

git push origin feature/new-feature

2. Navigate ke repository
3. Click New Pull Request
4. Select branches:
   • Base: main
   • Compare: feature/new-feature
5. Fill PR details:

Title: Add new feature
Description:
## Changes
- Added feature X
- Updated documentation
- Added tests

## Testing
- [ ] Unit tests passed
- [ ] Integration tests passed
- [ ] Manual testing completed

Closes #123

6. Click Create Pull Request

Review Pull Request

Reviewer Actions:

• View changes (Files changed tab)
• Add comments
• Request changes
• Approve PR
• Merge PR

# Inline comments
Click line number → Add comment

# Review status
- Comment: General feedback
- Approve: Ready to merge
- Request Changes: Needs modification

Merge Strategies

1. Create Merge Commit

   • Preserves all commits
   • Creates merge commit

2. Squash and Merge

   • Combines all commits into one
   • Clean history

3. Rebase and Merge

   • Linear history
   • No merge commits

Issues

Create Issue

1. Repository → Issues → New Issue
2. Fill form:

Title: Bug in login feature
Labels: bug, priority:high
Assignees: @developer1
Milestone: v1.2.0

Description:
## Description
Login fails when using special characters

## Steps to Reproduce
1. Go to login page
2. Enter email with special characters
3. Click login

## Expected Behavior
Should login successfully

## Actual Behavior
Shows error message

## Environment
- Browser: Chrome 120
- OS: Windows 11

3. Click Create Issue

Issue Management

Labels:

bug, enhancement, documentation
priority:low, priority:high
status:in-progress, status:review

Milestones:

v1.0.0 - Initial Release
v1.1.0 - Feature Update
v2.0.0 - Major Release

Link Issues to PRs:

Closes #123
Fixes #456
Resolves #789

Releases

Create Release

1. Repository → Releases → New Release
2. Choose tag or create new:

   Tag: v1.0.0
   Target: main branch

3. Fill release info:

Release Title: Version 1.0.0
Description:
## What's New
- Feature A
- Feature B
- Bug fixes

## Breaking Changes
- API endpoint changed

## Upgrade Guide
1. Backup database
2. Update dependencies
3. Run migrations

4. Attach binaries/assets (optional)
5. Click Publish Release

Semantic Versioning

v1.0.0 = MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

Tags

# Create tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# Push tag
git push origin v1.0.0

# List tags
git tag -l

# Delete tag
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

Organization Management

Create Organization

1. Click + → New Organization
2. Fill details:

Organization Name: mycompany
Full Name: My Company Inc
Description: Company organization
Website: https://company.com
Location: Jakarta, Indonesia

3. Click Create Organization

Organization Structure

Organization
├── Teams
│   ├── Developers (write access)
│   ├── DevOps (admin access)
│   └── Viewers (read access)
└── Repositories
    ├── backend-api
    ├── frontend-app
    └── infrastructure

Create Team

1. Organization → Teams → New Team
2. Configure team:

Team Name: developers
Description: Development team
Permission: Write Access

3. Add members:

Search and add users
Set role: Member/Admin

Team Permissions

Permission	Access Level
Read	View and clone
Write	Push changes
Admin	Full control

Organization Repositories

Transfer repository ke organization:

1. Repository → Settings → Danger Zone
2. Click Transfer Ownership
3. Select organization
4. Confirm transfer

SSH Keys Management

Generate SSH Key

# Generate ED25519 key (recommended)
ssh-keygen -t ed25519 -C "your@email.com" -f ~/.ssh/gitea_ed25519

# Or RSA key
ssh-keygen -t rsa -b 4096 -C "your@email.com" -f ~/.ssh/gitea_rsa

Add SSH Key to Gitea

1. Copy public key:

cat ~/.ssh/gitea_ed25519.pub

2. Gitea → Settings → SSH/GPG Keys → Add Key
3. Paste key and give it a title
4. Click Add Key

Configure SSH

Create/edit ~/.ssh/config:

Host git.your-domain.com
    HostName git.your-domain.com
    User git
    IdentityFile ~/.ssh/gitea_ed25519
    IdentitiesOnly yes

Test SSH Connection

ssh -T git@git.your-domain.com

# Should output:
# Hi username! You've successfully authenticated, but Gitea does not provide shell access.

GPG Keys (Commit Signing)

Generate GPG Key

# Generate key
gpg --full-generate-key

# Select:
# - RSA and RSA (default)
# - 4096 bits
# - 0 (key does not expire)
# - Real name, email, comment

Add GPG Key to Gitea

# List keys
gpg --list-secret-keys --keyid-format LONG

# Export public key
gpg --armor --export YOUR_KEY_ID

# Copy output dan add ke Gitea:
# Settings → SSH/GPG Keys → Add GPG Key

Configure Git to Sign Commits

# Set signing key
git config --global user.signingkey YOUR_KEY_ID

# Auto-sign commits
git config --global commit.gpgsign true

# Make signed commit
git commit -S -m "Signed commit message"

Access Tokens

Create Personal Access Token

1. Settings → Applications → Generate New Token
2. Configure token:

Token Name: CI/CD Token
Scopes:
  ✓ repo (Full control)
  ✓ write:packages
  ✓ read:user

3. Copy token (shown only once!)

Use Token

# Clone with token
git clone https://TOKEN@git.your-domain.com/username/repo.git

# Or configure credential helper
git config credential.helper store
git clone https://git.your-domain.com/username/repo.git
# Enter TOKEN as password

API Usage

# List repositories
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.your-domain.com/api/v1/user/repos

# Create repository
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-repo","private":true}' \
  https://git.your-domain.com/api/v1/user/repos

Notifications

Configure Notifications

Settings → Notifications:

Email Notifications:
  ✓ Watching repositories
  ✓ Participating repositories
  ✓ Mentions
  ✓ Issues assigned
  
Web Notifications:
  ✓ Enable web notifications

Notification Types

• Watching: All activities
• Participating: Your involvement
• Mentioned: Direct mentions (@username)
• Assigned: Tasks assigned to you

Wiki

Enable Wiki

Repository → Settings → Features → ✓ Enable Wiki

Create Wiki Page

1. Repository → Wiki → New Page
2. Create page:

Title: Installation Guide
Content:
# Installation Guide

## Prerequisites
- Node.js 20+
- Docker 24+

## Steps
1. Clone repository
2. Install dependencies
3. Run application

3. Click Save

Wiki Structure

Home (default page)
├── Installation
├── Configuration
├── API Documentation
└── Troubleshooting

Advanced Features

Repository Templates

1. Create repository
2. Settings → Check "Template Repository"
3. Users can create repos from template:
   • Use this template button
   • All files copied to new repo

Mirroring Repositories

Push Mirror

Repository → Settings → Mirror Settings
Direction: Push
Remote Address: https://github.com/username/repo.git
Authentication: Username/Password or Token
Sync Interval: Every 8 hours

Pull Mirror

Create Repository → Migrate/Mirror
Clone Address: https://github.com/username/repo.git
Mirror: ✓ This repository will be a mirror
Sync Interval: Every 8 hours

Repository Archive

Download repository:

1. Repository → More → Download Repository
2. Choose format:
   • ZIP
   • TAR.GZ

Repository Transfer

Transfer ownership:

1. Settings → Danger Zone → Transfer Ownership
2. Select new owner (user/organization)
3. Confirm transfer

Best Practices

Commit Messages

# Good commit message format
git commit -m "feat: add user authentication

- Implement JWT tokens
- Add login/logout endpoints
- Update documentation

Closes #123"

Branch Naming

feature/feature-name
bugfix/bug-description
hotfix/critical-fix
release/v1.2.0

Code Review Checklist

• Code follows style guide
• Tests added/updated
• Documentation updated
• No merge conflicts
• CI/CD passes
• Security considerations addressed

Git Workflow

# 1. Create feature branch
git checkout -b feature/new-feature

# 2. Make changes
# ... edit files ...

# 3. Commit changes
git add .
git commit -m "feat: add new feature"

# 4. Keep branch updated
git checkout main
git pull origin main
git checkout feature/new-feature
git rebase main

# 5. Push and create PR
git push origin feature/new-feature

# 6. After PR merged, cleanup
git checkout main
git pull origin main
git branch -d feature/new-feature

Troubleshooting

Permission Denied

# Check SSH key
ssh -T git@git.your-domain.com

# Check remote URL
git remote -v

# Fix URL if needed
git remote set-url origin git@git.your-domain.com:username/repo.git

Large File Issues

# Git LFS for large files
git lfs install
git lfs track "*.psd"
git lfs track "*.zip"
git add .gitattributes

Merge Conflicts

# Update your branch
git fetch origin
git merge origin/main

# Resolve conflicts in files
# ... edit conflicting files ...

# Mark as resolved
git add .
git commit -m "Resolve merge conflicts"

Reset to Remote

# Discard local changes
git fetch origin
git reset --hard origin/main

# Careful: This deletes all local changes!

Integration Examples

VS Code Integration

Install Git extension and configure:

{
  "git.defaultCloneDirectory": "~/projects",
  "git.autofetch": true,
  "git.confirmSync": false,
  "gitea.url": "https://git.your-domain.com",
  "gitea.token": "YOUR_TOKEN"
}

CLI Tools

# tea - Gitea CLI
# Install
brew install gitea/tap/tea

# Configure
tea login add \
  --url https://git.your-domain.com \
  --token YOUR_TOKEN \
  --name production

# Use
tea repos list
tea issues list
tea pulls create

Next Steps

Setelah menguasai penggunaan dasar Gitea:

1. ✅ Setup Gitea Runner - Configure runners
2. ✅ CI/CD Overview - Learn CI/CD concepts
3. ✅ Implementasi CI/CD - Build pipelines
4. ✅ Best Practices - Learn best practices

Happy coding with Gitea! 🚀