GitHub Actions for OSSA Validation in CI/CD Pipelines

Objective

Create reusable GitHub Actions that enable teams to validate OSSA manifests automatically in their CI/CD pipelines.

Scope

Build GitHub Actions for:

1. validate-ossa - Validate manifest files against OSSA schema
2. check-ossa-versions - Verify agent dependency versions are compatible
3. generate-ossa-docs - Auto-generate documentation from manifests
4. publish-ossa-registry - Publish validated agents to registry

Technical Approach

Action 1: validate-ossa

# .github/actions/validate-ossa/action.yml
name: 'Validate OSSA Manifest'
description: 'Validates OSSA agent manifests against the specification schema'
author: 'OSSA Standards Team'

inputs:
  manifest-path:
    description: 'Path to OSSA manifest file or directory'
    required: true
    default: '.ossa.yml'
  schema-version:
    description: 'OSSA schema version to validate against'
    required: false
    default: '1.0'
  fail-on-warning:
    description: 'Fail the action on validation warnings'
    required: false
    default: 'false'

outputs:
  valid:
    description: 'Whether the manifest is valid'
  errors:
    description: 'JSON array of validation errors'
  
runs:
  using: 'node20'
  main: 'dist/index.js'

// .github/actions/validate-ossa/src/index.ts
import * as core from '@actions/core';
import * as github from '@actions/github';
import Ajv from 'ajv';
import * as fs from 'fs';
import * as path from 'path';
import * as yaml from 'yaml';

async function run() {
  try {
    const manifestPath = core.getInput('manifest-path');
    const schemaVersion = core.getInput('schema-version');
    const failOnWarning = core.getInput('fail-on-warning') === 'true';

    // Load schema
    const schemaUrl = `https://raw.githubusercontent.com/ossa-ai/specification/v${schemaVersion}/spec/ossa-${schemaVersion}.schema.json`;
    const schema = await fetch(schemaUrl).then(r => r.json());

    // Load manifest(s)
    const manifests = loadManifests(manifestPath);
    
    const ajv = new Ajv({ allErrors: true, verbose: true });
    const validate = ajv.compile(schema);

    let allValid = true;
    const allErrors = [];

    for (const [file, content] of manifests) {
      const manifest = yaml.parse(content);
      const valid = validate(manifest);

      if (\!valid) {
        allValid = false;
        core.error(`❌ ${file}: Validation failed`);
        
        validate.errors.forEach(error => {
          const message = `  ${error.instancePath}: ${error.message}`;
          core.error(message);
          allErrors.push({ file, error });

          // Add annotations
          core.error(message, {
            title: 'OSSA Validation Error',
            file: file,
            startLine: 1 // Would need line number detection
          });
        });
      } else {
        core.info(`✅ ${file}: Valid OSSA manifest`);
      }
    }

    core.setOutput('valid', allValid);
    core.setOutput('errors', JSON.stringify(allErrors));

    if (\!allValid) {
      core.setFailed('OSSA manifest validation failed');
    }
  } catch (error) {
    core.setFailed(error.message);
  }
}

function loadManifests(manifestPath: string): Map<string, string> {
  const manifests = new Map();
  
  if (fs.statSync(manifestPath).isDirectory()) {
    const files = fs.readdirSync(manifestPath, { recursive: true });
    for (const file of files) {
      if (file.endsWith('.ossa.yml') || file.endsWith('.ossa.yaml')) {
        const fullPath = path.join(manifestPath, file);
        manifests.set(file, fs.readFileSync(fullPath, 'utf-8'));
      }
    }
  } else {
    manifests.set(manifestPath, fs.readFileSync(manifestPath, 'utf-8'));
  }

  return manifests;
}

run();

Action 2: check-ossa-versions

# .github/actions/check-ossa-versions/action.yml
name: 'Check OSSA Dependency Versions'
description: 'Verifies agent dependency versions are compatible'

inputs:
  manifest-path:
    required: true
  registry-url:
    description: 'OSSA registry URL to check versions'
    required: false
    default: 'https://registry.ossa.ai'

runs:
  using: 'node20'
  main: 'dist/index.js'

Usage Example

# .github/workflows/validate.yml
name: Validate OSSA Manifests

on:
  pull_request:
    paths:
      - '**.ossa.yml'
      - '**.ossa.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate OSSA Manifests
        uses: ossa-ai/validate-ossa@v1
        with:
          manifest-path: './agents'
          schema-version: '1.0'
          fail-on-warning: true
      
      - name: Check Dependency Versions
        uses: ossa-ai/check-ossa-versions@v1
        with:
          manifest-path: './agents'
      
      - name: Generate Documentation
        uses: ossa-ai/generate-ossa-docs@v1
        with:
          manifest-path: './agents'
          output-path: './docs/agents'
      
      - name: Publish to Registry
        if: github.ref == 'refs/heads/main'
        uses: ossa-ai/publish-ossa-registry@v1
        with:
          manifest-path: './agents'
          registry-url: ${{ secrets.OSSA_REGISTRY_URL }}
          api-key: ${{ secrets.OSSA_API_KEY }}

Acceptance Criteria

• validate-ossa action with Ajv validation
• check-ossa-versions action with registry integration
• generate-ossa-docs action with markdown output
• publish-ossa-registry action with authentication
• All actions published to GitHub Marketplace
• Comprehensive README for each action
• Example workflows in documentation
• Error annotations in PR checks
• Support for multiple manifest files
• Caching for performance

Files to Create

• .github/actions/validate-ossa/action.yml
• .github/actions/validate-ossa/src/index.ts
• .github/actions/check-ossa-versions/action.yml
• .github/actions/generate-ossa-docs/action.yml
• .github/actions/publish-ossa-registry/action.yml

Similar Projects

• OpenAPI Validator Action
• Helm Chart Testing Action
• Kubernetes Manifest Validator