GitHub Actions Setup Guide - MCP Server with LangGraph

Complete guide for setting up and configuring GitHub Actions for the MCP Server with LangGraph.

Overview
Required Secrets
Workflows
Branch Protection
Environment Configuration
Troubleshooting

Overview

This repository includes comprehensive GitHub Actions workflows for:

CI/CD Pipeline (ci.yaml) - Test, build, and deploy
Pull Request Checks (pr-checks.yaml) - Automated PR validation
Security Scanning (security-scan.yaml) - Daily security scans
Release Automation (release.yaml) - Automated releases
Stale Issues (stale.yaml) - Issue/PR management

Required Secrets

GitHub Repository Secrets

Navigate to: Settings → Secrets and variables → Actions

Application Secrets

## Anthropic API Key (required for tests)
ANTHROPIC_API_KEY=sk-ant-...

## JWT Secret (for authentication)
JWT_SECRET_KEY=$(openssl rand -base64 32)

## OpenFGA Configuration (from scripts/setup_openfga.py)
OPENFGA_STORE_ID=01HXXX...
OPENFGA_MODEL_ID=01HYYY...

Infrastructure Secrets (Optional)

## Kubernetes Configuration (base64 encoded)
KUBECONFIG_DEV=$(cat ~/.kube/config | base64)
KUBECONFIG_STAGING=$(cat ~/.kube/config | base64)
KUBECONFIG_PROD=$(cat ~/.kube/config | base64)

## MCP Registry Token (for publishing)
MCP_REGISTRY_TOKEN=your-registry-token

## PyPI Token (for package publishing)
PYPI_TOKEN=pypi-...

## Slack Webhooks (for notifications)
SLACK_WEBHOOK=https://hooks.slack.com/services/...
SLACK_SECURITY_WEBHOOK=https://hooks.slack.com/services/...

Container Registry

GitHub Container Registry (ghcr.io) uses GITHUB_TOKEN automatically - no setup needed.

Environment Secrets

For deployment environments: Settings → Environments

Development Environment

Create environment: development Secrets:

KUBECONFIG_DEV
ANTHROPIC_API_KEY
JWT_SECRET_KEY
OPENFGA_STORE_ID
OPENFGA_MODEL_ID

Protection rules: None (auto-deploy)

Staging Environment

Create environment: staging Secrets:

KUBECONFIG_STAGING
ANTHROPIC_API_KEY
JWT_SECRET_KEY
OPENFGA_STORE_ID
OPENFGA_MODEL_ID

Protection rules:

Required reviewers: 1
Deployment branches: main only

Production Environment

Create environment: production Secrets:

KUBECONFIG_PROD
ANTHROPIC_API_KEY
JWT_SECRET_KEY
OPENFGA_STORE_ID
OPENFGA_MODEL_ID

Protection rules:

Required reviewers: 2+ (security team)
Deployment branches: Tags only (v*.*.*)
Wait timer: 5 minutes

Workflows

1. CI/CD Pipeline (`ci.yaml`)

Triggers:

Push to main or develop
Pull requests to main
Release creation

Jobs:

Test - Run unit and integration tests
Lint - Code quality checks
Build - Docker image build and push
Deploy Dev - Auto-deploy to development (on develop)
Deploy Staging - Auto-deploy to staging (on main)
Deploy Prod - Manual deploy to production (on release)

Badge:

[![CI/CD](https://github.com/vishnu2kmohan/mcp-server-langgraph/actions/workflows/ci.yaml/badge.svg)](https://github.com/vishnu2kmohan/mcp-server-langgraph/actions/workflows/ci.yaml)

2. Pull Request Checks (`pr-checks.yaml`)

Triggers:

Pull request opened/updated/reopened

Jobs:

PR Metadata - Validate PR title (Conventional Commits)
Test Matrix - Test on Python 3.10, 3.11, 3.12
Lint - Code quality and formatting
Security - Security scans
Docker - Build test
Size Check - Large file detection
Dependency Review - Scan for vulnerable dependencies
Auto Label - Apply labels based on changed files
Comment - Post check results

Setup:

## Create labeler configuration (already exists)
cat .github/labeler.yml

3. Security Scan (`security-scan.yaml`)

Triggers:

Daily at 2 AM UTC
Push to main
Pull requests
Manual dispatch

Jobs:

Trivy - Container vulnerability scanning
Dependency Check - Python package vulnerabilities
CodeQL - Static code analysis
Secrets Scan - TruffleHog secrets detection
License Check - License compliance

Required:

Enable CodeQL in repository settings
Configure Security tab for SARIF uploads

4. Release Automation (`release.yaml`)

Triggers:

Git tags matching v*.*.*

Jobs:

Create Release - Generate changelog and GitHub release
Build Images - Multi-arch Docker images (amd64, arm64)
Publish Helm - Push Helm chart to OCI registry
Publish PyPI - Publish Python package (stable only)
Update MCP Registry - Update MCP registry entry
Notify - Send Slack notifications

Usage:

## Create and push tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

## Or create release via GitHub UI

5. Quality Tests (`quality-tests.yaml`)

Triggers:

Pull requests to main
Push to main
Weekly schedule (Sunday at midnight)
Manual dispatch

Jobs:

Property Tests - Hypothesis-based edge case discovery (27+ tests)
Contract Tests - MCP protocol compliance validation (20+ tests)
Regression Tests - Performance baseline tracking
Benchmark Tests - Performance monitoring with alerts
Mutation Tests - Test effectiveness measurement (weekly only)
Quality Summary - Aggregate results reporting

Badge:

[![Quality Tests](https://github.com/vishnu2kmohan/mcp-server-langgraph/actions/workflows/quality-tests.yaml/badge.svg)](https://github.com/vishnu2kmohan/mcp-server-langgraph/actions/workflows/quality-tests.yaml)

6. Stale Issue Management (`stale.yaml`)

Triggers:

Daily at midnight

Configuration:

Issues: 60 days inactive → stale, 7 days → close
PRs: 30 days inactive → stale, 7 days → close
Exempt labels: pinned, security, bug, critical

Branch Protection

Main Branch Protection

Navigate to: Settings → Branches → Branch protection rules Create rule for main:

Branch name pattern: main

Protection rules:
☑ Require a pull request before merging
  ☑ Require approvals: 2
  ☑ Dismiss stale pull request approvals when new commits are pushed
  ☑ Require review from Code Owners

☑ Require status checks to pass before merging
  ☑ Require branches to be up to date before merging
  Required checks:
    - Test
    - Lint
    - Security Scan
    - Docker Build Test

☑ Require conversation resolution before merging
☑ Require signed commits
☑ Include administrators
☑ Restrict who can push to matching branches
  - @vishnu2kmohan/maintainers

Develop Branch Protection

Create rule for develop:

Branch name pattern: develop

Protection rules:
☑ Require a pull request before merging
  ☑ Require approvals: 1

☑ Require status checks to pass before merging
  Required checks:
    - Test
    - Lint

☑ Require conversation resolution before merging

Environment Configuration

Setting Up Kubeconfig

## Encode kubeconfig for GitHub Actions
cat ~/.kube/config | base64 > kubeconfig.b64

## Create secret
gh secret set KUBECONFIG_PROD < kubeconfig.b64

## Clean up
rm kubeconfig.b64

Testing Secrets Locally

## Install GitHub CLI
brew install gh  # macOS
## or
apt install gh   # Linux

## Login
gh auth login

## Test secrets
gh secret list

## Run workflow locally with act
brew install act
act -j test -s ANTHROPIC_API_KEY=your-key

Codecov Integration

Setup Codecov

Sign up at https://codecov.io with GitHub
Enable repository in Codecov dashboard
Get upload token (optional - GITHUB_TOKEN works)
Add badge to README:

[![codecov](https://codecov.io/gh/vishnu2kmohan/mcp-server-langgraph/branch/main/graph/badge.svg)](https://codecov.io/gh/vishnu2kmohan/mcp-server-langgraph)

Codecov Configuration

Create .codecov.yml:

coverage:
  status:
    project:
      default:
        target: 70%
        threshold: 5%
    patch:
      default:
        target: 80%

comment:
  layout: "header, diff, files"
  behavior: default

Troubleshooting

Common Issues

1. Tests Failing - Missing API Key

Error: ANTHROPIC_API_KEY not set Solution:

gh secret set ANTHROPIC_API_KEY -b"sk-ant-..."

2. Kubeconfig Not Working

Error: Unable to connect to cluster Solution:

## Ensure base64 encoded
cat ~/.kube/config | base64 -w 0 | gh secret set KUBECONFIG_PROD

## Test decode
echo "$KUBECONFIG_PROD" | base64 -d > test-kubeconfig
kubectl --kubeconfig=test-kubeconfig get nodes

3. Docker Build Fails

Error: buildx not found Solution: Already handled in workflow with docker/setup-buildx-action@v3

4. CodeQL Initialization Fails

Error: CodeQL not initialized Solution:

Go to Settings → Code security and analysis
Enable CodeQL analysis
Re-run workflow

5. Dependabot PRs Not Auto-Merging

Setup auto-merge:

## Enable auto-merge in repository settings
## Settings → General → Pull Requests → Allow auto-merge

## Or via CLI
gh repo edit --enable-auto-merge

Debugging Workflows

View Logs

## List workflow runs
gh run list --workflow=ci.yaml

## View specific run
gh run view <run-id>

## Download logs
gh run download <run-id>

Re-run Failed Jobs

## Re-run specific workflow
gh run rerun <run-id>

## Re-run only failed jobs
gh run rerun <run-id> --failed

Enable Debug Logging

Add secrets:

gh secret set ACTIONS_STEP_DEBUG -b"true"
gh secret set ACTIONS_RUNNER_DEBUG -b"true"

Common Issues

1. Workflow Concurrency Issues

Issue: Workflows not canceling as expected Solution:

Check concurrency group configuration
Verify event type (pull_request vs push)
Review workflow run logs for cancellation messages

2. Cache Miss Issues

Issue: Cache not restoring, builds slow Solution:

Verify cache key matches across runs
Check if dependencies changed (invalidates cache)
Review cache size limits (10GB per repo)

3. Artifact Storage Full

Issue: Unable to upload artifacts Solution:

Review artifact retention policies
Clean up old workflow runs: Settings → Actions → General → Artifact retention
Manually delete old artifacts if needed

Workflow Concurrency Controls

All workflows now include concurrency controls to prevent duplicate runs and save CI minutes:

CI/CD Pipeline

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Cancels duplicate PR builds
Allows main/develop builds to complete

Pull Request Checks

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

Uses PR number for better grouping
Always cancels previous runs

Benefits:

~30% reduction in CI minutes
Faster feedback on latest commits
Prevents resource waste

Manual Workflow Triggering

All workflows support manual triggering via workflow_dispatch:

## Via GitHub UI
## Go to Actions → Select workflow → Run workflow

## Via GitHub CLI
gh workflow run ci.yaml
gh workflow run pr-checks.yaml --ref feature-branch
gh workflow run quality-tests.yaml
gh workflow run security-scan.yaml
gh workflow run release.yaml

Use cases:

Test workflow changes without creating PRs
Run security scans on demand
Trigger releases manually
Debug workflow issues

Build Optimization with Caching

Workflows use GitHub Actions cache to improve performance:

Python Dependencies

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
    cache-dependency-path: |
      requirements-pinned.txt
      requirements-test.txt

Helm Charts

- name: Cache Helm
  uses: actions/cache@v4
  with:
    path: |
      ~/.cache/helm
      ~/.local/share/helm
    key: ${{ runner.os }}-helm-${{ hashFiles('deployments/helm/**/Chart.yaml') }}

kubectl Binary

- name: Cache kubectl
  uses: actions/cache@v4
  with:
    path: /usr/local/bin/kubectl
    key: ${{ runner.os }}-kubectl-${{ hashFiles('.github/workflows/ci.yaml') }}

Performance Impact:

20-30% faster builds
Reduced network usage
Better reliability

Artifact Retention Policies

All workflows include retention policies to manage storage costs:

Artifact Type	Retention	Workflow
Test Results	7 days	pr-checks.yaml
Security Reports	30 days	security-scan.yaml, pr-checks.yaml
License Reports	90 days	security-scan.yaml
SBOM Files	90 days	release.yaml
Quality Test Results	30 days	quality-tests.yaml
Benchmark Results	90 days	quality-tests.yaml
Mutation Test Results	30 days	quality-tests.yaml

Best Practices

1. Secret Rotation

## Rotate secrets regularly
gh secret set JWT_SECRET_KEY -b"$(openssl rand -base64 32)"

## Update in environments too
gh secret set JWT_SECRET_KEY -e production -b"new-secret"

2. Workflow Optimization

Use cache: 'pip' for faster Python setup
Use cache-from: type=gha for Docker builds
Run independent jobs in parallel
Use if conditions to skip unnecessary jobs
Leverage concurrency controls to prevent duplicate runs
Set appropriate artifact retention policies

3. Security

Never log secrets
Use secrets.GITHUB_TOKEN instead of PAT when possible
Limit secret access with environments
Review Dependabot PRs before merging
Generate and review SBOM files for releases
Run security scans regularly

Additional Resources

Support

For GitHub Actions issues:

Check workflow logs
Review this documentation
Search GitHub Community
Open an issue with ci-cd label

Last Updated: 2025-01-10

Quick Reference

Configuration

Tools & Compatibility

Authoring Guides

CI/CD Reference

​Table of Contents

​Overview

​Required Secrets

​GitHub Repository Secrets

Application Secrets

Infrastructure Secrets (Optional)

Container Registry

​Environment Secrets

Development Environment

Staging Environment

Production Environment

​Workflows

​1. CI/CD Pipeline (ci.yaml)

​2. Pull Request Checks (pr-checks.yaml)

​3. Security Scan (security-scan.yaml)

​4. Release Automation (release.yaml)

​5. Quality Tests (quality-tests.yaml)

​6. Stale Issue Management (stale.yaml)

​Branch Protection

​Main Branch Protection

​Develop Branch Protection

​Environment Configuration

​Setting Up Kubeconfig

​Testing Secrets Locally

​Codecov Integration

​Setup Codecov

​Codecov Configuration

​Troubleshooting

​Common Issues

1. Tests Failing - Missing API Key

2. Kubeconfig Not Working

3. Docker Build Fails

4. CodeQL Initialization Fails

5. Dependabot PRs Not Auto-Merging

​Debugging Workflows

View Logs

Re-run Failed Jobs

Enable Debug Logging

​Common Issues

1. Workflow Concurrency Issues

2. Cache Miss Issues

3. Artifact Storage Full

​Workflow Concurrency Controls

​CI/CD Pipeline

​Pull Request Checks

​Manual Workflow Triggering

​Build Optimization with Caching

​Python Dependencies

​Helm Charts

​kubectl Binary

​Artifact Retention Policies

​Best Practices

​1. Secret Rotation

​2. Workflow Optimization

​3. Security

​Additional Resources

​Support

Table of Contents

Overview

Required Secrets

GitHub Repository Secrets

Environment Secrets

Workflows

1. CI/CD Pipeline (`ci.yaml`)

2. Pull Request Checks (`pr-checks.yaml`)

3. Security Scan (`security-scan.yaml`)

4. Release Automation (`release.yaml`)

5. Quality Tests (`quality-tests.yaml`)

6. Stale Issue Management (`stale.yaml`)

Branch Protection

Main Branch Protection

Develop Branch Protection

Environment Configuration

Setting Up Kubeconfig

Testing Secrets Locally

Codecov Integration

Setup Codecov

Codecov Configuration

Troubleshooting

Common Issues

Debugging Workflows

Common Issues

Workflow Concurrency Controls

CI/CD Pipeline

Pull Request Checks

Manual Workflow Triggering

Build Optimization with Caching

Python Dependencies

Helm Charts

kubectl Binary

Artifact Retention Policies

Best Practices

1. Secret Rotation

2. Workflow Optimization

3. Security

Additional Resources

Support