> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Repository Secrets & Variables Configuration

> Complete guide for configuring GitHub Actions secrets and variables required for CI/CD workflows including GCP, AWS, authentication, and monitoring integrations

# GitHub Repository Secrets & Variables Configuration

This document lists all required secrets and variables needed for CI/CD workflows.

## Overview

The MCP Server LangGraph project uses GitHub Actions for CI/CD automation. To enable full functionality, you need to configure repository secrets (sensitive data) and variables (non-sensitive configuration).

**Configuration Location**: `Settings` → `Secrets and variables` → `Actions`

***

## Required Repository Variables

Configure these under `Settings` → `Secrets and variables` → `Actions` → **Variables** tab.

### GCP Project Configuration

| Variable         | Required       | Default                   | Description                                           |
| ---------------- | -------------- | ------------------------- | ----------------------------------------------------- |
| `GCP_PROJECT_ID` | ✅ Yes          | `vishnu-sandbox-20250310` | Google Cloud project ID                               |
| `GCP_REGION`     | ✅ Yes          | `us-central1`             | Primary GCP region for resources                      |
| `PROJECT_NUMBER` | ⚠️ Conditional | `1024691643349`           | GCP project number (required for compliance scanning) |

### GKE Cluster Configuration

| Variable              | Required | Default                               | Description                 |
| --------------------- | -------- | ------------------------------------- | --------------------------- |
| `GKE_STAGING_CLUSTER` | No       | `staging-mcp-server-langgraph-gke`    | Staging GKE cluster name    |
| `GKE_PROD_CLUSTER`    | No       | `production-mcp-server-langgraph-gke` | Production GKE cluster name |

### Namespace Configuration

| Variable               | Required | Default                           | Description                         |
| ---------------------- | -------- | --------------------------------- | ----------------------------------- |
| `STAGING_NAMESPACE`    | No       | `staging-mcp-server-langgraph`    | Kubernetes namespace for staging    |
| `PRODUCTION_NAMESPACE` | No       | `production-mcp-server-langgraph` | Kubernetes namespace for production |

***

## Required Repository Secrets

Configure these under `Settings` → `Secrets and variables` → `Actions` → **Secrets** tab.

### GCP Authentication (Workload Identity Federation)

| Secret                    | Required | Format                                                                                   | Description                                |
| ------------------------- | -------- | ---------------------------------------------------------------------------------------- | ------------------------------------------ |
| `GCP_WIF_PROVIDER`        | ✅ Yes    | `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER` | Workload Identity Federation provider path |
| `GCP_STAGING_SA_EMAIL`    | ✅ Yes    | `SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com`                                     | Staging service account email              |
| `GCP_PRODUCTION_SA_EMAIL` | ✅ Yes    | `SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com`                                     | Production service account email           |

**Example Values**:

```properties theme={null}
GCP_WIF_PROVIDER=projects/1024691643349/locations/global/workloadIdentityPools/github-actions-pool/providers/github-provider
GCP_STAGING_SA_EMAIL=mcp-staging-sa@vishnu-sandbox-20250310.iam.gserviceaccount.com
GCP_PRODUCTION_SA_EMAIL=mcp-production-sa@vishnu-sandbox-20250310.iam.gserviceaccount.com
```

### Publishing & Distribution

| Secret               | Required       | Description                                                   |
| -------------------- | -------------- | ------------------------------------------------------------- |
| `PYPI_TOKEN`         | ⚠️ Conditional | PyPI API token for package publishing (required for releases) |
| `MCP_REGISTRY_TOKEN` | No             | MCP registry token for publishing MCP server                  |

### Notifications

| Secret                   | Required | Description                                 |
| ------------------------ | -------- | ------------------------------------------- |
| `SLACK_WEBHOOK`          | No       | Slack webhook URL for general notifications |
| `SLACK_SECURITY_WEBHOOK` | No       | Slack webhook URL for security alerts       |

### Auto-Provided Secrets

These secrets are automatically provided by GitHub Actions (no configuration needed):

| Secret         | Description                             |
| -------------- | --------------------------------------- |
| `GITHUB_TOKEN` | GitHub API access token (auto-provided) |

***

## Setup Instructions

### 1. Configure GCP Workload Identity Federation

Before setting secrets, set up Workload Identity Federation in your GCP project:

```bash theme={null}
# Set your project
gcloud config set project YOUR_PROJECT_ID

# Create workload identity pool
gcloud iam workload-identity-pools create github-actions-pool \
    --location=global \
    --display-name="GitHub Actions Pool"

# Create workload identity provider
gcloud iam workload-identity-pools providers create-oidc github-provider \
    --location=global \
    --workload-identity-pool=github-actions-pool \
    --issuer-uri="https://token.actions.githubusercontent.com" \
    --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
    --attribute-condition="assertion.repository=='YOUR_ORG/YOUR_REPO'"

# Create service accounts
gcloud iam service-accounts create mcp-staging-sa \
    --display-name="MCP Staging Service Account"

gcloud iam service-accounts create mcp-production-sa \
    --display-name="MCP Production Service Account"

# Grant permissions (adjust roles as needed)
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:mcp-staging-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/container.developer"

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="serviceAccount:mcp-production-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/container.developer"

# Bind service accounts to workload identity
gcloud iam service-accounts add-iam-policy-binding mcp-staging-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-actions-pool/attribute.repository/YOUR_ORG/YOUR_REPO"

gcloud iam service-accounts add-iam-policy-binding mcp-production-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-actions-pool/attribute.repository/YOUR_ORG/YOUR_REPO"

# Get the WIF provider path (copy this to GCP_WIF_PROVIDER secret)
gcloud iam workload-identity-pools providers describe github-provider \
    --location=global \
    --workload-identity-pool=github-actions-pool \
    --format="value(name)"
```

### 2. Configure GitHub Secrets

Navigate to your repository: `Settings` → `Secrets and variables` → `Actions`

#### Add Variables:

1. Click **Variables** tab
2. Click **New repository variable**
3. Add each variable from the tables above
4. Click **Add variable**

#### Add Secrets:

1. Click **Secrets** tab
2. Click **New repository secret**
3. Add each secret from the tables above
4. Click **Add secret**

### 3. Verify Configuration

Run this workflow manually to test authentication:

```bash theme={null}
# Navigate to Actions tab in GitHub
# Select "GCP Drift Detection" workflow
# Click "Run workflow"
# Check for successful authentication
```

Or use the GitHub CLI:

```bash theme={null}
gh workflow run gcp-drift-detection.yaml
gh run list --workflow=gcp-drift-detection.yaml --limit=1
```

***

## Workflow-Specific Requirements

### Deployment Workflows

**Required for**:

* `deploy-preview-gke.yaml`
* `deploy-production-gke.yaml`

**Secrets/Variables**:

* `GCP_PROJECT_ID` (variable)
* `GCP_REGION` (variable)
* `GCP_WIF_PROVIDER` (secret)
* `GCP_STAGING_SA_EMAIL` or `GCP_PRODUCTION_SA_EMAIL` (secret)

### Compliance & Security Scanning

**Required for**:

* `gcp-compliance-scan.yaml`
* `security-scan.yaml`

**Secrets/Variables**:

* `GCP_PROJECT_ID` (variable)
* `PROJECT_NUMBER` (variable)
* `GCP_WIF_PROVIDER` (secret)
* `SLACK_SECURITY_WEBHOOK` (secret, optional for notifications)

### Drift Detection

**Required for**:

* `gcp-drift-detection.yaml`

**Secrets/Variables**:

* `GCP_PROJECT_ID` (variable)
* `GCP_WIF_PROVIDER` (secret)

### Release & Publishing

**Required for**:

* `release.yaml`

**Secrets**:

* `PYPI_TOKEN` (required for PyPI publishing)
* `SLACK_WEBHOOK` (optional for notifications)
* `MCP_REGISTRY_TOKEN` (optional for MCP registry)

***

## Security Best Practices

### ✅ DO:

* **Rotate secrets** regularly (recommended: every 90 days)
* **Use least-privilege** IAM roles for service accounts
* **Enable audit logging** for service account usage
* **Review secret access** periodically
* **Use environment-specific** service accounts (separate staging/production)

### ❌ DON'T:

* **Never commit secrets** to git (use `.gitignore`)
* **Never share secrets** in plain text (Slack, email, etc.)
* **Never use production credentials** in non-production workflows
* **Never grant overly broad permissions** to service accounts

***

## Troubleshooting

### Authentication Failures

**Error**: `Failed to authenticate to Google Cloud`

**Solution**:

1. Verify `GCP_WIF_PROVIDER` secret is correctly set
2. Verify service account email is correctly set
3. Check workload identity binding:
   ```bash theme={null}
   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT@PROJECT.iam.gserviceaccount.com
   ```
4. Verify repository attribute in workload identity condition matches your repo

### Missing Secrets/Variables

**Error**: `The secret 'GCP_WIF_PROVIDER' was not found`

**Solution**:

1. Go to `Settings` → `Secrets and variables` → `Actions`
2. Verify secret exists in **Secrets** tab
3. Check spelling matches exactly (case-sensitive)
4. Re-create secret if needed

### Permission Denied Errors

**Error**: `Permission denied` when accessing GCP resources

**Solution**:

1. Verify service account has required IAM roles:
   ```bash theme={null}
   gcloud projects get-iam-policy PROJECT_ID \
       --flatten="bindings[].members" \
       --filter="bindings.members:serviceAccount:SERVICE_ACCOUNT@PROJECT.iam.gserviceaccount.com"
   ```
2. Grant necessary roles:
   ```bash theme={null}
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT@PROJECT.iam.gserviceaccount.com" \
       --role="ROLE_NAME"
   ```

***

## Migration Guide

### Migrating from Hardcoded Values

If you're migrating from workflows with hardcoded project IDs:

1. **Extract current values** from workflows:
   ```bash theme={null}
   grep -r "vishnu-sandbox" .github/workflows/
   ```

2. **Create variables** with those values as defaults (already done in updated workflows)

3. **Add secrets** for sensitive data (WIF provider, service account emails)

4. **Test workflows** in a non-production environment first

5. **Update production** after successful testing

### Fallback Behavior

All updated workflows include fallback defaults:

* If variables/secrets are not set, workflows use the default hardcoded values
* This ensures backward compatibility during migration
* Remove fallbacks after confirming configuration works

**Example**:

```yaml theme={null}
GCP_PROJECT_ID: ${{ vars.GCP_PROJECT_ID || 'vishnu-sandbox-20250310' }}
```

***

## Support

For issues or questions:

* **GitHub Issues**: [https://github.com/vishnu2kmohan/mcp-server-langgraph/issues](https://github.com/vishnu2kmohan/mcp-server-langgraph/issues)
* **Internal Docs**: See `.github/workflows/` for workflow-specific documentation
* **GCP Documentation**: [https://cloud.google.com/iam/docs/workload-identity-federation](https://cloud.google.com/iam/docs/workload-identity-federation)

***

**Last Updated**: 2025-11-03
**Version**: 1.0
**Maintained By**: DevOps Team