pg-api 0.1.0

# GitLab Repository Setup Guide

This guide explains how to create and configure the pg-api repository on GitLab using the API.

## Prerequisites

1. **GitLab Account**: You need a GitLab account (free tier works)
2. **Authentication**: Choose one:
   - **SSH Key** (Recommended): See [SSH_SETUP.md](SSH_SETUP.md)
   - **Personal Access Token**: Create one with `api` scope
3. **Git**: Installed and configured locally

## Creating a Personal Access Token

1. Go to GitLab → Settings → Access Tokens
2. Or visit: https://gitlab.com/-/profile/personal_access_tokens
3. Create a new token with:
   - Token name: `pg-api-setup`
   - Expiration date: (optional)
   - Scopes: Select `api` (required)
4. Save the token securely

## Method 1: Using Python Script (Recommended)

The script automatically detects if you have SSH keys configured and uses the best authentication method.

### Basic Usage

```bash
cd /opt/dev/pg-api

# With SSH key (auto-detected)
python3 scripts/create_gitlab_repo.py \
  --token YOUR_GITLAB_TOKEN \
  --push

# The script will show:
# 🔑 SSH key detected, using SSH for push...
# Or:
# 🔐 No SSH key found, using HTTPS with token...
```

### Advanced Options

```bash
# Create private repository with CI/CD setup and branch protection
python3 scripts/create_gitlab_repo.py \
  --token YOUR_GITLAB_TOKEN \
  --visibility private \
  --push \
  --setup-ci \
  --protect-main
```

### Script Options

- `--token`: Your GitLab personal access token (required)
- `--gitlab-url`: GitLab instance URL (default: https://gitlab.com)
- `--name`: Repository name (default: pg-api)
- `--visibility`: public, private, or internal (default: public)
- `--push`: Automatically push local code to GitLab
- `--setup-ci`: Configure CI/CD variables
- `--protect-main`: Enable branch protection for main branch

## Method 2: Using Bash Script

```bash
cd /opt/dev/pg-api

# Set your token as environment variable
export GITLAB_TOKEN="your_token_here"

# Run the script
./scripts/create_gitlab_repo.sh
```

## Method 3: Using cURL Directly

```bash
# Get your username
USERNAME=$(curl -s -H "PRIVATE-TOKEN: YOUR_TOKEN" \
  https://gitlab.com/api/v4/user | jq -r .username)

# Create repository
curl -X POST -H "PRIVATE-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://gitlab.com/api/v4/projects \
  -d '{
    "name": "pg-api",
    "description": "High-performance PostgreSQL REST API driver built with Rust",
    "visibility": "public",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true
  }'
```

## Method 4: Using GitLab CLI (glab)

```bash
# Install GitLab CLI
# macOS: brew install glab
# Linux: See https://gitlab.com/gitlab-org/cli/-/releases

# Authenticate
glab auth login

# Create repository
glab repo create pg-api --public \
  --description "High-performance PostgreSQL REST API driver built with Rust"

# Push code
git push -u origin main
```

## After Repository Creation

### 1. Configure CI/CD Variables

Go to: Settings → CI/CD → Variables

Add these variables:
- `CARGO_HOME`: `${CI_PROJECT_DIR}/.cargo`
- `RUST_BACKTRACE`: `1`

### 2. Enable Container Registry

Go to: Settings → General → Visibility → Container Registry
- Enable Container Registry

### 3. Configure Branch Protection

Go to: Settings → Repository → Protected branches
- Branch: `main`
- Allowed to merge: Developers + Maintainers
- Allowed to push: Maintainers

### 4. Add Topics/Tags

Go to: Settings → General → Topics
Add: `postgresql`, `rust`, `api`, `rest-api`, `database`, `driver`

### 5. Configure Webhooks (Optional)

Go to: Settings → Webhooks
Add webhooks for:
- Discord/Slack notifications
- Deploy triggers
- External CI/CD systems

## Manual Git Push

If the scripts don't automatically push, use:

```bash
# Initialize git (if needed)
git init
git add .
git commit -m "Initial commit: pg-api PostgreSQL REST API driver"

# Add GitLab remote
git remote add origin git@gitlab.com:YOUR_USERNAME/pg-api.git

# Push to GitLab
git branch -M main
git push -u origin main
```

## Verifying the Setup

1. **Check Repository**: Visit https://gitlab.com/YOUR_USERNAME/pg-api
2. **Check CI/CD**: Go to CI/CD → Pipelines
3. **Check Container Registry**: Go to Packages & Registries → Container Registry
4. **Run Test Pipeline**: Make a small change and push to trigger CI

## Troubleshooting

### Authentication Failed
- Verify your token has `api` scope
- Check token hasn't expired
- Ensure token is copied correctly (no spaces)

### Repository Already Exists
- Choose a different name with `--name` option
- Or delete existing repository first

### Push Failed
- Check SSH keys are configured: `ssh -T git@gitlab.com`
- Or use HTTPS with token: `https://oauth2:TOKEN@gitlab.com/username/pg-api.git`

### CI/CD Pipeline Failed
- Check `.gitlab-ci.yml` syntax
- Verify CI/CD variables are set
- Check runner availability

## Additional Resources

- [GitLab API Documentation](https://docs.gitlab.com/ee/api/)
- [Personal Access Tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
- [GitLab CI/CD](https://docs.gitlab.com/ee/ci/)
- [GitLab CLI](https://gitlab.com/gitlab-org/cli)

## Security Notes

- Never commit your personal access token
- Use environment variables for tokens
- Rotate tokens regularly
- Use project-specific deploy tokens for CI/CD
- Enable 2FA on your GitLab account