Skip to main content

CI/CD Usage

Use API keys in CI/CD pipelines to automatically whitelist your test runners' IP addresses before running integration tests.

Workflow Overview​

  1. Start Session: Before running tests, start an EntryGuard session to whitelist the runner's IP
  2. Run Tests: Execute your test suite with access to protected resources
  3. Stop Session: After tests complete, stop the session to revoke the IP

GitHub Actions Example​

Create a workflow that uses EntryGuard API keys to manage session lifecycle.

name: Integration Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Start EntryGuard session
        id: session
        env:
          ENTRYGUARD_API_KEY: ${{ secrets.ENTRYGUARD_API_KEY }}
        run: |
          # Start a session for production database access
          RESPONSE=$(curl -s -X POST https://api.entryguard.io/api/v1/sessions \
            -H "X-API-Key: ${ENTRYGUARD_API_KEY}" \
            -H "Content-Type: application/json" \
            -d '{
              "resourceIds": ["660e8400-e29b-41d4-a716-446655440001"],
              "durationHours": 1
            }')

          # Extract session ID
          SESSION_ID=$(echo $RESPONSE | jq -r '.id')
          echo "session_id=${SESSION_ID}" >> $GITHUB_OUTPUT

          # Wait for session to become active
          echo "Waiting for session to activate..."
          sleep 10

      - name: Run integration tests
        env:
          DB_HOST: prod-db.example.com
        run: |
          npm install
          npm run test:integration

      - name: Stop EntryGuard session
        if: always()
        env:
          ENTRYGUARD_API_KEY: ${{ secrets.ENTRYGUARD_API_KEY }}
          SESSION_ID: ${{ steps.session.outputs.session_id }}
        run: |
          curl -X POST https://api.entryguard.io/api/v1/sessions/${SESSION_ID}/stop \
            -H "X-API-Key: ${ENTRYGUARD_API_KEY}"

Setup Steps​

  1. Create an API key with sessions:write scope:

    curl -X POST https://api.entryguard.io/api/v1/api-keys \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -d '{
        "name": "GitHub Actions CI",
        "scopes": ["sessions:write"]
      }'

  2. Add the key to GitHub Secrets:

    • Go to your repository settings
    • Navigate to Secrets and variables → Actions
    • Add a new secret named ENTRYGUARD_API_KEY
    • Paste the full API key (e.g., eg_live_1234567890abcdef...)

  3. Find your resource ID:

    curl https://api.entryguard.io/api/v1/resources \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Generic Bash Script​

Use this script in any CI/CD platform (GitLab CI, CircleCI, Jenkins, etc.).

#!/bin/bash
set -e

# Configuration
ENTRYGUARD_API_KEY="${ENTRYGUARD_API_KEY}"
RESOURCE_ID="660e8400-e29b-41d4-a716-446655440001"
DURATION_HOURS=1

# Start session
echo "Starting EntryGuard session..."
RESPONSE=$(curl -s -X POST https://api.entryguard.io/api/v1/sessions \
  -H "X-API-Key: ${ENTRYGUARD_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"resourceIds\": [\"${RESOURCE_ID}\"],
    \"durationHours\": ${DURATION_HOURS}
  }")

SESSION_ID=$(echo $RESPONSE | jq -r '.id')

if [ -z "$SESSION_ID" ] || [ "$SESSION_ID" = "null" ]; then
  echo "Failed to start session"
  echo $RESPONSE
  exit 1
fi

echo "Session started: ${SESSION_ID}"

# Cleanup function
cleanup() {
  echo "Stopping EntryGuard session..."
  curl -X POST https://api.entryguard.io/api/v1/sessions/${SESSION_ID}/stop \
    -H "X-API-Key: ${ENTRYGUARD_API_KEY}"
  echo "Session stopped"
}

# Register cleanup on exit
trap cleanup EXIT

# Wait for session to activate
echo "Waiting for IP rules to apply..."
sleep 10

# Run tests
echo "Running integration tests..."
npm run test:integration

echo "Tests completed successfully"

Save this as scripts/run-tests-with-entryguard.sh and use it in your CI:

# GitLab CI example
integration-tests:
  script:
    - chmod +x scripts/run-tests-with-entryguard.sh
    - ./scripts/run-tests-with-entryguard.sh

Multiple Resources​

To whitelist access to multiple resources (e.g., database + API server):

curl -X POST https://api.entryguard.io/api/v1/sessions \
  -H "X-API-Key: ${ENTRYGUARD_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceIds": [
      "660e8400-e29b-41d4-a716-446655440001",
      "660e8400-e29b-41d4-a716-446655440002",
      "660e8400-e29b-41d4-a716-446655440003"
    ],
    "durationHours": 1
  }'

Auto-Detected IP​

EntryGuard automatically detects the runner's public IP address. You don't need to specify the IP in the request.

To verify the detected IP before starting a session:

curl https://api.entryguard.io/api/v1/detect-ip

Response:

{
  "ip": "203.0.113.42",
  "version": "IPv4"
}

Error Handling​

Handle common errors in your CI scripts:

# Start session with error handling
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST https://api.entryguard.io/api/v1/sessions \
  -H "X-API-Key: ${ENTRYGUARD_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"resourceIds\": [\"${RESOURCE_ID}\"], \"durationHours\": 1}")

HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | head -n-1)

if [ "$HTTP_CODE" -ne 200 ]; then
  echo "Failed to start session (HTTP ${HTTP_CODE})"
  echo "$BODY"
  exit 1
fi

SESSION_ID=$(echo "$BODY" | jq -r '.id')

Best Practices​

  1. Always stop sessions: Use trap or if: always() to ensure sessions are stopped even if tests fail
  2. Minimal duration: Set durationHours to the minimum needed for your tests (usually 1 hour)
  3. Wait for activation: Sleep 5-10 seconds after starting a session to allow IP rules to propagate
  4. Separate keys per pipeline: Use different API keys for different CI environments (staging, production)
  5. Rotate keys regularly: Update your CI secrets every 90 days

Next Steps​