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:

# 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:

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:

"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:

"cloudflare-ops": {
  "tools": {
    "gitlab": true  // ← Already enabled for this agent
  }
}

Step 4: Test GitLab Connection

Launch OpenCode:

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:

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:

# 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:

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:

"cloudflare": {
  ...
  "enabled": true  // ← Change from false to true
}

Option B: Enable per-agent (recommended)

Already configured in cloudflare-ops and security-audit agents:

"cloudflare-ops": {
  "tools": {
    "cloudflare": true  // ← Already enabled
  }
}

Step 5: Test Cloudflare Connection

Launch OpenCode:

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:

# 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:

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

---

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

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

Verify:

git status | grep -i env

Should show nothing (env files not tracked).

---

7. Troubleshooting

GitLab MCP Not Loading

# 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

# 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:

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

Cloudflare:

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:

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.