vm-cloudflare/GITLAB_CLOUDFLARE_AUTH.md

# GitLab & Cloudflare API Authentication Setup

Complete guide to authenticate OpenCode with GitLab and Cloudflare APIs.

---

## **1. GitLab Authentication**

### What GitLab MCP Lets You Do

**In OpenCode, you can:**
```
/agent cloudflare-ops
Check our GitLab repository for recent infrastructure changes
and show me the commit history for terraform/ directory.
```

Result:
- Browse GitLab repos from OpenCode
- View merge requests and issues
- Query commit history
- Trigger pipelines
- Manage infrastructure-as-code in GitLab

### Step 1: Create GitLab Personal Access Token

**Location:** https://gitlab.com/-/user_settings/personal_access_tokens

**Or for self-hosted GitLab:**
```
https://your-gitlab-instance.com/-/user_settings/personal_access_tokens
```

**Required Settings:**

| Field | Value |
|-------|-------|
| **Token name** | `opencode-agent` |
| **Expiration date** | 90 days (recommended for security) |
| **Scopes** | See below |

**Required Scopes (checkboxes to enable):**
- ✅ `api` - Full API access
- ✅ `read_user` - Read user information
- ✅ `read_repository` - Read repositories
- ✅ `write_repository` - Optional (for commits/MRs)
- ✅ `read_registry` - Optional (for container registry)

**Click "Create personal access token"**

You'll see:
```
glpat-XXXXXXXXXXXXXX
```

**Copy this token immediately** (you won't see it again).

### Step 2: Set Environment Variable

In your shell, before running OpenCode:

```bash
# For gitlab.com
export GITLAB_TOKEN="glpat_your_token_here"
export GITLAB_URL="https://gitlab.com"

# For self-hosted GitLab
export GITLAB_TOKEN="glpat_your_token_here"
export GITLAB_URL="https://your-gitlab-instance.com"
```

Verify:
```bash
echo $GITLAB_TOKEN
```

Should output: `glpat_...` (the token prefix)

### Step 3: Enable in OpenCode Config

The config is already set up. To enable GitLab MCP:

**Option A: Enable globally (simple)**

In `opencode.jsonc`, find the gitlab section and change:
```jsonc
"gitlab": {
  ...
  "enabled": true  // ← Change from false to true
}
```

**Option B: Enable per-agent only (recommended)**

Keep it disabled globally (resource savings), but enable only when needed:

In `opencode.jsonc`, agents section is already configured:
```jsonc
"cloudflare-ops": {
  "tools": {
    "gitlab": true  // ← Already enabled for this agent
  }
}
```

### Step 4: Test GitLab Connection

Launch OpenCode:
```bash
export GITLAB_TOKEN="glpat_..."
cd /Users/sovereign/Desktop/CLOUDFLARE
opencode
```

Inside OpenCode:
```
/mcp status gitlab
```

Should report: `✅ gitlab - loaded and ready`

### Example: GitLab Workflows

**Query Recent Commits:**
```
/agent cloudflare-ops
Show me the last 10 commits to the terraform/ directory in our GitLab repo.
What infrastructure changes were made?
```

**Manage Merge Requests:**
```
/agent cloudflare-ops
List all open merge requests for the Cloudflare infrastructure project.
Show me the approval status and comments.
```

**Check Pipeline Status:**
```
/agent cloudflare-ops
What's the status of the latest CI/CD pipeline for our terraform changes?
Are there any failed jobs?
```

**Create Infrastructure Documentation:**
```
/agent cloudflare-ops
Pull the latest commits from our GitLab repo and summarize all 
infrastructure changes made in the last 2 weeks. Create a report.
```

---

## **2. Cloudflare API Authentication**

### What Cloudflare MCP Lets You Do

**In OpenCode, you can:**
```
/agent cloudflare-ops
Query our Cloudflare account directly. Show me all DNS records,
WAF rules, and origin health status.
```

Result:
- Query live DNS records
- Check WAF rule status
- Monitor origin health
- View tunnel configurations
- Validate infrastructure matches Terraform state

### Step 1: Create Cloudflare API Token

**Location:** https://dash.cloudflare.com/profile/api-tokens

**Click "Create Token"**

**Setup for Terraform/Infrastructure:**

| Field | Value |
|-------|-------|
| **Token name** | `opencode-infra-api` |
| **Permissions** | See below |
| **Account Resources** | Your account |
| **Zone Resources** | Specific zones or all zones |
| **TTL** | 90 days |

**Required Permissions:**

Create a custom token with:
- ✅ `Zone.DNS:Read` - Read DNS records
- ✅ `Zone.Settings:Read` - Read zone settings
- ✅ `Account.Firewall Rules:Read` - Read WAF/firewall rules
- ✅ `Account.Tunnels:Read` - Read tunnel configs
- ✅ `Account.Load Balancing:Read` - Read load balancers

Or use the **"Edit Cloudflare Workers"** template (has most permissions).

**Click "Create Token"**

You'll see:
```
Token: 1234567890abcdef1234567890abcdef
```

**Copy immediately** (you won't see it again).

### Step 2: Get Your Cloudflare Account ID

**In Cloudflare Dashboard:**
1. Go to https://dash.cloudflare.com/
2. Click on any domain
3. Look for **Account ID** in the right sidebar
4. Copy it (looks like `abc123def456ghi789`)

Or via API:
```bash
curl -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  https://api.cloudflare.com/client/v4/accounts
```

Look for `id` field in response.

### Step 3: Set Environment Variables

In your shell, before running OpenCode:

```bash
# Cloudflare API Token (required)
export CLOUDFLARE_API_TOKEN="1234567890abcdef1234567890abcdef"

# Your Cloudflare Account ID (required)
export CLOUDFLARE_ACCOUNT_ID="abc123def456ghi789"

# Optional: Zone ID if querying specific zone
export CLOUDFLARE_ZONE_ID="zone123zone123zone123"
```

Verify:
```bash
echo $CLOUDFLARE_API_TOKEN
echo $CLOUDFLARE_ACCOUNT_ID
```

### Step 4: Enable in OpenCode Config

The config is already set up. To enable Cloudflare MCP:

**Option A: Enable globally**

In `opencode.jsonc`:
```jsonc
"cloudflare": {
  ...
  "enabled": true  // ← Change from false to true
}
```

**Option B: Enable per-agent (recommended)**

Already configured in `cloudflare-ops` and `security-audit` agents:
```jsonc
"cloudflare-ops": {
  "tools": {
    "cloudflare": true  // ← Already enabled
  }
}
```

### Step 5: Test Cloudflare Connection

Launch OpenCode:
```bash
export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_ACCOUNT_ID="..."
cd /Users/sovereign/Desktop/CLOUDFLARE
opencode
```

Inside OpenCode:
```
/mcp status cloudflare
```

Should report: `✅ cloudflare - loaded and ready`

### Example: Cloudflare Workflows

**Query Live DNS Records:**
```
/agent cloudflare-ops
Query Cloudflare API: Show me all DNS records for offsec.global zone.
Cross-check them against our terraform/dns.tf configuration.
Are they in sync?
```

**Validate WAF Rules:**
```
/agent security-audit
Query Cloudflare API to show all active WAF rules.
Check them against PCI-DSS requirements. Report gaps.
```

**Monitor Tunnel Health:**
```
/agent cloudflare-ops
Query Cloudflare API for tunnel status and origin health.
Show me response times and any degraded origins.
```

**Compare State:**
```
/agent cloudflare-ops
Pull live configuration from Cloudflare API.
Compare against our Terraform code.
Show me any drift (manual changes outside Terraform).
```

**Generate Infrastructure Report:**
```
/agent cloudflare-ops
Query Cloudflare API for: zones, DNS records, WAF rules, 
tunnels, SSL certificates, and load balancers.
Generate a complete infrastructure inventory report.
```

---

## **3. Combined Workflow: GitLab + Cloudflare**

### Real Example: Validate Infrastructure Changes

```
/agent cloudflare-ops

I'm about to merge a GitLab MR that modifies our WAF rules.
1. Fetch the proposed changes from the MR
2. Query Cloudflare API for current WAF rules
3. Show me what will change
4. Check against PCI-DSS requirements
5. Validate terraform syntax
6. Only PLAN, don't apply
```

OpenCode will:
1. **[gitlab]** - Read the MR changes
2. **[cloudflare]** - Query live WAF rules
3. **[filesystem]** - Read terraform/waf.tf
4. **[git]** - Show the diff
5. **[context7]** - Check compliance
6. **Report:** "Safe to merge, no compliance gaps"

### Real Example: Disaster Recovery Check

```
/agent security-audit

Validate that our infrastructure is resilient:
1. Query GitLab for backup/DR scripts
2. Query Cloudflare for failover configuration
3. Check terraform for multi-region setup
4. Report on recovery capabilities
```

OpenCode will:
1. **[gitlab]** - Find DR playbooks
2. **[cloudflare]** - Verify failover IPs
3. **[filesystem]** - Examine terraform
4. **Report:** "Failover set to 5-second TTL, tested 2 weeks ago"

---

## **4. Environment Variables Summary**

Create a `.env` file in your project:

```bash
# GitHub (already configured)
export GITHUB_TOKEN="ghp_your_token"

# GitLab (NEW)
export GITLAB_TOKEN="glpat_your_token"
export GITLAB_URL="https://gitlab.com"

# Cloudflare (NEW)
export CLOUDFLARE_API_TOKEN="your_api_token"
export CLOUDFLARE_ACCOUNT_ID="your_account_id"

# Optional Cloudflare
export CLOUDFLARE_ZONE_ID="your_zone_id"
```

Load before running OpenCode:
```bash
cd /Users/sovereign/Desktop/CLOUDFLARE
source .env
opencode
```

---

## **5. Multiple Accounts Configuration 🔐**

For managing multiple GitHub, GitLab, or Cloudflare accounts, see: [MULTI_ACCOUNT_AUTH.md](MULTI_ACCOUNT_AUTH.md)

---

## **6. Security Best Practices**

### Token Management

**Do:**
- ✅ Rotate tokens every 90 days
- ✅ Use separate tokens for different purposes
- ✅ Store in `.env` (don't commit to git)
- ✅ Use `environment` variables in opencode.jsonc, not hardcoded tokens
- ✅ Set narrow scopes (minimal permissions needed)

**Don't:**
- ❌ Hardcode tokens in opencode.jsonc
- ❌ Commit tokens to git
- ❌ Share tokens via chat/email
- ❌ Use the same token for everything
- ❌ Set tokens with unlimited expiration

### .gitignore Update

```bash
# Add to your .gitignore
.env
.env.local
.env.*.local
```

Verify:
```bash
git status | grep -i env
```

Should show nothing (env files not tracked).

---

## **7. Troubleshooting**

### GitLab MCP Not Loading

```bash
# Check token is set
echo $GITLAB_TOKEN

# Check URL is correct
echo $GITLAB_URL

# Try test in OpenCode
/mcp status gitlab
```

**Common Issues:**
- Token expired → Create new token
- Wrong scopes → Recreate token with `api` + `read_repository`
- Self-hosted URL wrong → Verify with your GitLab admin

### Cloudflare MCP Not Loading

```bash
# Check token is set
echo $CLOUDFLARE_API_TOKEN

# Check account ID is set
echo $CLOUDFLARE_ACCOUNT_ID

# Try test in OpenCode
/mcp status cloudflare
```

**Common Issues:**
- Wrong token format → Get new token from dashboard
- Account ID missing → Get from https://dash.cloudflare.com/
- Insufficient scopes → Recreate token with proper permissions
- API rate limit → Wait a few minutes and retry

### Testing API Directly

**GitLab:**
```bash
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  https://gitlab.com/api/v4/user
```

**Cloudflare:**
```bash
curl -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  https://api.cloudflare.com/client/v4/accounts
```

Both should return successful JSON responses.

---

## **8. Next Steps**

### Now:
1. Create GitLab PAT → export `GITLAB_TOKEN`
2. Create Cloudflare API token → export `CLOUDFLARE_API_TOKEN`
3. Get Cloudflare Account ID → export `CLOUDFLARE_ACCOUNT_ID`
4. Test MCPs: `/mcp list`

### Then:
1. Run cloudflare-ops with GitLab + Cloudflare together
2. Try a full validation workflow
3. Generate an infrastructure report

---

**Ready?** Set the env vars and try:

```bash
export GITLAB_TOKEN="glpat_..."
export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_ACCOUNT_ID="..."
opencode
/agent cloudflare-ops
Show me all infrastructure from GitLab and Cloudflare, then compare.
```