CI/CD with Oso Cloud

GitHub Actions Example

Get started with this complete workflow:

name: Oso Cloud CI/CD

on: [push, pull_request]

jobs:
  validate-and-test:
    runs-on: ubuntu-latest
    env:
      OSO_URL: "http://localhost:8080"
      OSO_AUTH: "e_0123456789_12345_osotesttoken01xiIn"
    steps:
      - uses: actions/checkout@v4
      - name: Install Oso Cloud CLI
        run: curl -L https://cloud.osohq.com/install.sh | bash
      - name: Validate policy syntax
        run: oso-cloud validate policy/*.polar
      - name: Test policies
        run: oso-cloud test policy/*.polar
      
  deploy:
    if: github.ref == 'refs/heads/main'
    needs: validate-and-test
    runs-on: ubuntu-latest
    env:
      OSO_AUTH: ${{ secrets.OSO_CLOUD_PRODUCTION_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Install Oso Cloud CLI
        run: curl -L https://cloud.osohq.com/install.sh | bash
      - name: Deploy to production
        run: oso-cloud policy policy/*.polar

Change policy/*.polar to your file paths.
Add your production API key as OSO_CLOUD_PRODUCTION_KEY in GitHub Secrets.

Local Development Integration

Catch policy errors before they reach your CI pipeline with pre-commit validation.

Set Up Pre-Commit Hook

Validate Polar syntax before committing:

#!/bin/sh
# Save this to .git/hooks/pre-commit

# Change this to the paths to your polar files
declare -a POLAR_FILES=(
  "policy/authorization.polar"
  "policy/authorization2.polar"
)

POLAR_FILES_CHANGED=false

# Check if any polar files changed in this commit
for POLAR_FILE in "${POLAR_FILES[@]}" ; do
  if git --no-pager diff --cached --name-status | grep -v "^D" | grep "${POLAR_FILE}" >> /dev/null ; then
    POLAR_FILES_CHANGED=true
    break
  fi
done

# Validate syntax if any Polar file changed
! $POLAR_FILES_CHANGED || oso-cloud validate "${POLAR_FILES[@]}"

Make the hook executable:

chmod 0755 .git/hooks/pre-commit

Pipeline Steps

Validate syntax - oso-cloud validate
Run policy unit tests - oso-cloud test
Run integration tests with updated policies
Deploy to target environment

Testing Configurations

Run fast validation and unit tests on every push to catch errors early.

Syntax Validation

Ensure your Polar policies are syntactically correct:

validate-syntax:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Validate policy syntax
      run: oso-cloud validate policy/*.polar

For multiple policy files: Pass all files in one command - the CLI validates consistency across files.

Unit Testing

Run policy tests to verify authorization logic works correctly. With Oso Dev Server (Recommended):

test-with-dev-server:
  runs-on: ubuntu-latest
  env:
    OSO_URL: "http://localhost:8080"
    OSO_AUTH: "e_0123456789_12345_osotesttoken01xiIn"
  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Install Oso Dev Server
      run: |
        curl https://oso-local-development-binary.s3.amazonaws.com/latest/oso-local-development-binary-linux-x86_64.tar.gz -o oso-dev-server.tar.gz
        tar -xzf oso-dev-server.tar.gz && chmod +x standalone
    - name: Start Dev Server
      run: ./standalone &
    - name: Run policy tests
      run: oso-cloud test policy/*.polar

With Oso Cloud:

test-on-oso-cloud:
  runs-on: ubuntu-latest
  env:
    OSO_AUTH: ${{ secrets.OSO_CLOUD_READ_ONLY_KEY }}
  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Run policy tests
      run: oso-cloud test policy/*.polar

Dev Server removes external dependencies for faster CI runs.

Application Testing

Run integration tests to ensure your application works correctly with updated authorization policies.

Shared Test Environment

deploy-to-test:
  runs-on: ubuntu-latest
  env:
    OSO_AUTH: ${{ secrets.OSO_CLOUD_TEST_KEY }}
  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Deploy to test environment
      run: oso-cloud policy policy/*.polar
    - name: Run application tests
      run: npm test # or your test command

Queue PR jobs to avoid policy conflicts.

Isolated Environments (Dev Server)

test-with-isolation:
  runs-on: ubuntu-latest
  env:
    OSO_URL: "http://localhost:8080"
  steps:
    - uses: actions/checkout@v4
    - name: Install tools
      run: |
        curl -L https://cloud.osohq.com/install.sh | bash
        curl https://oso-local-development-binary.s3.amazonaws.com/latest/oso-local-development-binary-linux-x86_64.tar.gz -o oso-dev-server.tar.gz
        tar -xzf oso-dev-server.tar.gz && chmod +x standalone
    - name: Start Dev Server
      run: ./standalone &
    - name: Create test environment
      run: echo "OSO_AUTH=$(curl -s -X POST http://localhost:8080/test_environment?copy=false | jq -r '.token')" >> "$GITHUB_ENV"
    - name: Deploy policy
      run: oso-cloud policy policy/*.polar
    - name: Run application tests
      run: npm test

Production Deployment

Deploy validated policies to production safely.

deploy-production:
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  needs: [validate-and-test, application-tests]
  runs-on: ubuntu-latest
  env:
    OSO_AUTH: ${{ secrets.OSO_CLOUD_PRODUCTION_KEY }}
  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Deploy to production
      run: oso-cloud policy policy/*.polar

Best practices:

Use separate API keys for test and production
Store keys as encrypted secrets, never in plaintext
Use read-only keys for tests, read-write for deploys

Advanced Configuration

Version pinning

Pin specific tool versions for consistent CI/CD environments:Oso Cloud CLI:

curl -L https://cloud.osohq.com/install.sh | OSO_CLI_VERSION="x.y.z" bash

Oso Dev Server:

curl https://oso-local-development-binary.s3.amazonaws.com/x.y.z/oso-local-development-binary-linux-x86_64.tar.gz -o oso-dev-server.tar.gz

Replace “x.y.z” with your desired version.

Docker-based Dev Server

Deploy the Oso Dev Server as a container for isolated test environments:

# Run the Dev Server with policy files mounted from the host 
# and automatically reload on policy changes
docker run --rm -p 8080:8080 \
  --mount type=bind,src="$(pwd)/policy",dst=/policies \
  public.ecr.aws/osohq/dev-server:latest \
  --watch-for-changes /policies/policy.polar

Local Authorization Validation

Validate Local Authorization configuration against your database schema:

validate-local-auth:
  runs-on: ubuntu-latest
  services:
    postgres:
      image: postgres:13
      env:
        POSTGRES_PASSWORD: password
      options: >-
        --health-cmd pg_isready
        --health-interval 10s
        --health-timeout 5s
        --health-retries 5

  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Validate Local Authorization config
      run: |
        oso-cloud validate-local-authorization-config \
          ./local_authorization_config.yaml \
          -c postgres://postgres:password@localhost:5432/postgres \
          -p policy/*.polar

Requirements: Database access needed to validate queries against current schema.

Managing Facts in CI

Best practices for handling authorization data in CI/CD:Seed Essential Data:

seed-facts:
  runs-on: ubuntu-latest
  env:
    OSO_AUTH: ${{ secrets.OSO_CLOUD_TEST_KEY }}
  steps:
    - uses: actions/checkout@v4
    - name: Install Oso Cloud CLI
      run: curl -L https://cloud.osohq.com/install.sh | bash
    - name: Seed test environment
      run: ./scripts/seed-oso-facts.sh

Recommendations:

Let applications generate facts naturally during tests
Only seed data that’s required on startup (roles, permissions)
Keep fact seeding scripts in sync with database seeding

Troubleshooting

Installation Issues

CLI installation fails:

Check internet connectivity and firewall settings
Verify curl is installed: curl --version

Dev Server won’t start:

Check port 8080 availability: lsof -i :8080
Verify binary permissions: chmod +x standalone
Review startup logs for detailed errors

Authentication Problems

“Authentication failed” errors:

Verify API key is set correctly in environment
Check key has appropriate permissions (read-only vs read-write)
Ensure no extra whitespace in secret values

Wrong environment targeted:

Confirm OSO_URL points to correct environment
Check OSO_AUTH matches the target environment’s key
Verify environment variables are properly scoped to jobs

Policy and Test Failures

Syntax validation fails:

Check policy files for syntax errors locally first
Ensure all referenced policy files are included
Verify file paths are correct in CI configuration

Tests fail in CI but pass locally:

Check environment variable differences
Verify Dev Server is fully started before running tests
Ensure test data is properly seeded

Deployment fails:

Check production API key permissions
Verify policy syntax before deployment
Review Oso Cloud environment status

Next Steps

Set up local development tools for policy authoring
Write comprehensive policies using Polar
Implement authorization checks in your application
Monitor and debug authorization in production

Need help setting up your CI/CD pipeline? Schedule a call with an Oso engineer - we’re happy to help.

Get Started

Develop

Deploy and Manage

GitHub Actions Example

Local Development Integration

Set Up Pre-Commit Hook

Pipeline Steps

Testing Configurations

Syntax Validation

Unit Testing

Application Testing

Shared Test Environment

Isolated Environments (Dev Server)

Production Deployment

Advanced Configuration

Troubleshooting

Next Steps

​GitHub Actions Example

​Local Development Integration

​Set Up Pre-Commit Hook

​Pipeline Steps

​Testing Configurations

​Syntax Validation

​Unit Testing

​Application Testing

​Shared Test Environment

​Isolated Environments (Dev Server)

​Production Deployment

​Advanced Configuration

​Troubleshooting

​Next Steps

GitHub Actions Example

Local Development Integration

Set Up Pre-Commit Hook

Pipeline Steps

Testing Configurations

Syntax Validation

Unit Testing

Application Testing

Shared Test Environment

Isolated Environments (Dev Server)

Production Deployment

Advanced Configuration

Troubleshooting

Next Steps