From GitHub Actions to OSOP: Convert Your Existing Workflows

You do not need to start from scratch. OSOP's format converter (osop-interop) imports existing workflows from 6 popular formats — and exports back to 4 of them. This guide shows you how to convert your GitHub Actions, Airflow DAGs, and BPMN processes into OSOP.

Installation

install.sh
pip install osop-interop

Supported Formats

Format	Import	Export
GitHub Actions	Yes	Yes
BPMN	Yes	Yes
Apache Airflow	Yes	Yes
Temporal	Yes	Yes
Postman Collections	Yes	—
OpenAPI 3.x	Yes	—

Example: GitHub Actions to OSOP

Suppose you have a CI/CD workflow in .github/workflows/deploy.yml:

.github/workflows/deploy.yml
# .github/workflows/deploy.yml
name: Deploy
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
  deploy:
    needs: build
    environment: production
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Convert it to OSOP:

terminal
$ osop import .github/workflows/deploy.yml --from github-actions -o deploy.osop.yaml

The result:

deploy.osop.yaml

Testcicd

↓sequential→ Build

Buildcli

↓sequential→ Deploy

Deployinfra

Open in Editor

Notice how the converter automatically detected the environment: production declaration and converted it to an approval_gate. Job dependencies (needs:) become sequential edges.

Conversion Mapping

GitHub Actions to OSOP

GitHub Actions	OSOP
`workflow`	OsopWorkflow
`job`	node (step/fork/join)
`step`	step node
`if:` condition	decision node
`needs:` dependency	edge ordering
`on: schedule`	timer node
`environment: production`	approval node

Airflow to OSOP

Airflow	OSOP
`DAG`	OsopWorkflow
`BashOperator`	cli step
`PythonOperator`	step node
`BranchPythonOperator`	decision node
`>>` dependencies	edge
`schedule_interval`	timer node

BPMN to OSOP

BPMN	OSOP
Start Event	start node
Service Task	step node
User Task	approval node
Exclusive Gateway	decision node
Parallel Gateway	fork/join
Timer Event	timer node
Sub-Process	subprocess

Exporting Back

OSOP is not a one-way street. Export back to your runtime's format:

export.sh
# Export to GitHub Actions
$ osop export deploy.osop.yaml --to github-actions -o .github/workflows/deploy.yml

# Export to Airflow DAG
$ osop export pipeline.osop.yaml --to airflow -o dags/pipeline.py

# Export to BPMN
$ osop export process.osop.yaml --to bpmn -o process.bpmn

Using the Python API

python-api.py
from osop_interop import GitHubActionsImporter, AirflowExporter

# Import
importer = GitHubActionsImporter()
osop_workflow = importer.convert("path/to/workflow.yml")

# Export
exporter = AirflowExporter()
airflow_dag = exporter.convert("path/to/workflow.osop.yaml")

Using via MCP

If you have the OSOP MCP server installed, your AI agent can convert workflows with a single tool call:

mcp-call.json
// Agent calls osop.import
{
  "tool": "osop.import",
  "arguments": {
    "file_path": ".github/workflows/deploy.yml",
    "source_format": "github-actions"
  }
}
// Returns valid OSOP YAML

Why Convert?

Converting to OSOP gives you:

Portability — Your workflow works across 18 AI coding agents and multiple runtimes
Execution records — .osoplog captures what actually happened, which your current format does not
Risk analysis — Built-in security scanning that GitHub Actions YAML does not provide
Visual editing — Drag and drop your workflow in the OSOP editor
Optimization — Compare multiple executions to find what to improve

And you can always export back. OSOP is an upgrade, not a migration.