CI/CD Quick Setup

Integrate Oculum into your CI/CD pipeline to automatically scan code for security vulnerabilities. This guide covers the most common setups.

GitHub Actions (Recommended)

The easiest way to integrate Oculum into CI/CD:

# .github/workflows/security-scan.yml
name: Security Scan

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - uses: oculum/scan-action@v1
        with:
          api-key: ${{ secrets.OCULUM_API_KEY }}
          depth: verified
          fail-on: high

See GitHub Action for full configuration options.

---

Setting Up Your API Key

1. Go to your Dashboard Settings
2. Click Create Key
3. Name it "CI/CD"
4. Copy the key
5. Add it to your CI secrets:

GitHub

Settings → Secrets and variables → Actions → New repository secret

• Name: OCULUM_API_KEY
• Value: Your API key

GitLab

Settings → CI/CD → Variables

• Key: OCULUM_API_KEY
• Value: Your API key
• Masked: Yes

Other CI Systems

Set OCULUM_API_KEY as an environment variable.

---

Generic CLI Setup

For any CI system, install and run Oculum:

# Install
npm install -g @oculum/cli

# Authenticate (using environment variable)
export OCULUM_API_KEY=${{ secrets.OCULUM_API_KEY }}

# Run scan
oculum scan --fail-on high --quiet

---

GitLab CI

# .gitlab-ci.yml
security-scan:
  image: node:20
  stage: test
  script:
    - npm install -g @oculum/cli
    - oculum scan --fail-on high --quiet
  variables:
    OCULUM_API_KEY: $OCULUM_API_KEY

---

CircleCI

# .circleci/config.yml
version: 2.1

jobs:
  security-scan:
    docker:
      - image: node:20
    steps:
      - checkout
      - run:
          name: Install Oculum
          command: npm install -g @oculum/cli
      - run:
          name: Run Security Scan
          command: oculum scan --fail-on high --quiet

workflows:
  main:
    jobs:
      - security-scan

---

Jenkins

// Jenkinsfile
pipeline {
    agent any

    environment {
        OCULUM_API_KEY = credentials('oculum-api-key')
    }

    stages {
        stage('Security Scan') {
            steps {
                sh 'npm install -g @oculum/cli'
                sh 'oculum scan --fail-on high --quiet'
            }
        }
    }
}

---

Recommended CI Strategy

On Pull Requests

Fast feedback with incremental scanning:

oculum scan --incremental --fail-on critical

• Only scans changed files
• Blocks on critical issues
• Fast feedback loop

On Main Branch

Thorough scanning with validated depth:

oculum scan --depth verified --fail-on high

• Full codebase scan
• AI-validated for accuracy
• Blocks on high+ severity

Scheduled Audits

Weekly deep scans for comprehensive analysis:

oculum scan --depth deep --format json --output audit.json

---

Fail Thresholds

Control when CI fails:

---

Output for CI

Quiet Mode

Minimal output for cleaner CI logs:

oculum scan --quiet --fail-on high

SARIF for GitHub Security Tab

oculum scan --format sarif --output results.sarif

Upload to GitHub's Security tab for integrated vulnerability tracking.

---

Monorepo Setup

Scan specific packages:

jobs:
  scan:
    strategy:
      matrix:
        package: [api, web, shared]
    steps:
      - uses: actions/checkout@v4
      - uses: oculum/scan-action@v1
        with:
          api-key: ${{ secrets.OCULUM_API_KEY }}
          path: ./packages/${{ matrix.package }}

---

Caching

Speed up CI with caching:

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'

---

Next Steps

• GitHub Action — Full GitHub Action documentation
• Scan Depths — Understand local vs verified vs deep
• Exit Codes — CI exit code reference