trigger-qc #4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # ============================================================================== | |
| # WORKFLOW: Build Ontology (Quality Control) | |
| # ============================================================================== | |
| # Purpose: Builds ontology release assets and performs quality control checks | |
| # | |
| # This workflow: | |
| # 1. Refreshes imports to ensure consistency | |
| # 2. Generates release artifacts (OWL, JSON-LD, Turtle, etc.) | |
| # 3. Runs quality control checks (syntax, consistency, etc.) | |
| # 4. Commits generated assets back to the repository | |
| # 5. Triggers the documentation workflow to continue the chain | |
| # | |
| # This is the core build workflow that transforms the edit file | |
| # (*-edit.owl) into production-ready ontology releases in multiple formats. | |
| # | |
| # Execution Chain Position: | |
| # setup-repo → refresh-imports → [BUILD/QC] → docs | |
| # | |
| # Read more about ODK builds: | |
| # https://github.com/INCATools/ontology-development-kit#building-the-ontology | |
| # ============================================================================== | |
| name: Build Ontology | |
| # ============================================================================== | |
| # WORKFLOW TRIGGERS | |
| # ============================================================================== | |
| # This workflow can be triggered in three ways: | |
| # 1. Via repository_dispatch from refresh-imports workflow (after imports refresh) | |
| # 2. Automatically on pushes that modify ontology source files | |
| # 3. Manually via workflow_dispatch for forced builds | |
| # | |
| # Path filters ensure the workflow only runs when ontology files change, | |
| # preventing unnecessary builds on unrelated commits (README, docs, etc.). | |
| # | |
| # IMPORTANT: Push triggers skip commits made by github-actions[bot] to prevent | |
| # duplicate runs when the workflow chain is triggered via repository_dispatch. | |
| # ============================================================================== | |
| on: | |
| # ============================================================================ | |
| # TRIGGER 1: Repository Dispatch (from refresh-imports workflow) | |
| # ============================================================================ | |
| # Listens for 'trigger-qc' event dispatched by refresh-imports.yml | |
| # This ensures build runs immediately after imports are refreshed | |
| # ============================================================================ | |
| repository_dispatch: | |
| types: [trigger-qc] | |
| # ============================================================================ | |
| # TRIGGER 2: Push Events (for regular development) | |
| # ============================================================================ | |
| # Triggers when any file in src/ontology/ is modified and pushed | |
| # | |
| # Why src/ontology/**? | |
| # - Catches changes to edit files, components, imports, metadata | |
| # - Ensures builds run after ontology content updates | |
| # - Excludes unrelated changes (documentation, root README, etc.) | |
| # | |
| # Examples of files that trigger: | |
| # - src/ontology/myonto-edit.owl (main edit file) | |
| # - src/ontology/components/*.owl (component modules) | |
| # - src/ontology/imports/*.owl (import modules) | |
| # - src/ontology/Makefile (build configuration) | |
| # | |
| # Note: This trigger is skipped for commits made by github-actions[bot] | |
| # to prevent duplicate runs when triggered via repository_dispatch | |
| # ============================================================================ | |
| # push: | |
| # branches: ["*"] # Triggers on any branch | |
| # paths: | |
| # - 'src/ontology/**' | |
| # ============================================================================ | |
| # TRIGGER 3: Pull Request Events (for PR validation) | |
| # ============================================================================ | |
| # Same as push trigger, but for pull requests | |
| # Runs QC checks on PR branches to validate changes before merge | |
| # Note: Commits are skipped for PRs (see commit step conditions) | |
| # ============================================================================ | |
| # pull_request: | |
| # branches: ["*"] | |
| # paths: | |
| # - 'src/ontology/**' | |
| # ============================================================================ | |
| # TRIGGER 4: Manual Trigger (for forced builds) | |
| # ============================================================================ | |
| # Allows manual execution via GitHub UI | |
| # Useful for: | |
| # - Testing build process without code changes | |
| # - Forcing rebuild after external changes | |
| # - Troubleshooting build issues | |
| # ============================================================================ | |
| workflow_dispatch: | |
| # ============================================================================== | |
| # ENVIRONMENT VARIABLES | |
| # ============================================================================== | |
| # Global variables available to all jobs in this workflow | |
| # ============================================================================== | |
| env: | |
| # Default branch for git operations (used in some ODK make targets) | |
| DEFAULT_BRANCH: main | |
| # ============================================================================== | |
| # JOBS | |
| # ============================================================================== | |
| jobs: | |
| # ============================================================================ | |
| # JOB: ontology_qc | |
| # ============================================================================ | |
| # Main job that performs the complete build and QC process | |
| # | |
| # Process Flow: | |
| # 1. Checkout repository with full history | |
| # 2. Refresh imports (ensures consistency) | |
| # 3. Build all release assets (OWL, JSON-LD, Turtle, etc.) | |
| # 4. Commit generated files back to repository | |
| # 5. Trigger documentation workflow | |
| # | |
| # Container: ODK full image with all build tools | |
| # | |
| # CRITICAL: Skips workflow for commits made by github-actions[bot] on push | |
| # to prevent duplicate runs when triggered via repository_dispatch | |
| # ============================================================================ | |
| ontology_qc: | |
| # Use latest Ubuntu runner for stability | |
| runs-on: ubuntu-latest | |
| # CRITICAL: Skip this workflow if triggered by push from github-actions[bot] | |
| # This prevents duplicate runs in the workflow chain | |
| # The chain uses repository_dispatch, so push triggers from bot commits are redundant | |
| # if: | | |
| # github.event_name != 'push' || | |
| # github.event.head_commit.author.name != 'github-actions[bot]' | |
| # Grant write permissions for committing generated assets | |
| permissions: | |
| contents: write | |
| # Use ODK container for consistent build environment | |
| # Version v1.6 pinned for reproducibility | |
| # Includes: ROBOT, OWLTools, make, Java, Python, reasoning tools | |
| container: obolibrary/odkfull:v1.6 | |
| steps: | |
| # ======================================================================== | |
| # STEP 1: Checkout Repository | |
| # ======================================================================== | |
| # Fetch complete repository with full git history | |
| # | |
| # Why fetch-depth: 0? | |
| # - Full history may be needed for ODK make targets | |
| # - Allows git operations that reference commits/branches | |
| # - Required for accurate versioning in releases | |
| # ======================================================================== | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # Full history | |
| # ======================================================================== | |
| # STEP 2: Build Ontology | |
| # ======================================================================== | |
| # Runs ODK make targets to build complete ontology release | |
| # | |
| # Make Targets: | |
| # 1. refresh-imports: Updates external ontology modules (ensures consistency) | |
| # 2. all_assets: Generates all release artifacts | |
| # | |
| # What all_assets generates: | |
| # - {id}-full.owl : Complete ontology with all imports merged | |
| # - {id}-base.owl : Core ontology without imports | |
| # - {id}.owl : Main release file (typically same as -full) | |
| # - {id}.json : JSON-LD serialization | |
| # - {id}.ttl : Turtle serialization | |
| # - {id}-simple.owl : Simplified version (if configured) | |
| # - {id}-non-classified.owl : Pre-reasoning version (if configured) | |
| # - Component files : Individual module builds | |
| # - Report files : QC reports and statistics | |
| # | |
| # Environment Variables: | |
| # - ROBOT_ENV: Sets Java heap size for ROBOT tool | |
| # - ROBOT_JAVA_ARGS=-Xmx6G: Allocates 6GB RAM for reasoning/validation | |
| # | |
| # Why 6GB? | |
| # - Large ontologies require significant memory for reasoning | |
| # - Prevents OutOfMemory errors during classification | |
| # - Adjust if builds fail with OOM errors (increase) or if builds | |
| # are fast and memory-constrained (decrease) | |
| # ======================================================================== | |
| - name: Build ontology | |
| env: | |
| # Configure ROBOT tool memory allocation | |
| # Increase if builds fail with OutOfMemory errors | |
| ROBOT_ENV: 'ROBOT_JAVA_ARGS=-Xmx6G' | |
| run: | | |
| # Navigate to ontology source directory | |
| cd src/ontology | |
| # Run ODK build targets | |
| # - refresh-imports: Update external imports first | |
| # - all_assets: Generate all release files | |
| make refresh-imports all_assets | |
| # ======================================================================== | |
| # STEP 3: Commit Ontology Assets | |
| # ======================================================================== | |
| # Commits generated release files back to the repository | |
| # | |
| # Conditions: | |
| # - Only runs for push/dispatch events (not pull requests) | |
| # - Only commits if changes detected (action skips empty commits) | |
| # | |
| # What gets committed: | |
| # - src/ontology/*.owl : All OWL release files | |
| # - src/ontology/*.json : JSON-LD serializations | |
| # - src/ontology/*.ttl : Turtle serializations | |
| # - src/ontology/imports/*.owl : Updated import modules | |
| # | |
| # Why --force flag? | |
| # - Generated files are often in .gitignore | |
| # - --force overrides gitignore rules for these specific files | |
| # - Ensures release assets are tracked in version control | |
| # | |
| # Git History Note: | |
| # - Author: github-actions[bot] (distinguishes from human commits) | |
| # - Message: Clearly indicates automated build | |
| # - Allows easy filtering of bot commits in git log | |
| # ======================================================================== | |
| - name: Commit ontology assets | |
| # Skip commits for pull requests (review changes manually in PR) | |
| if: github.event_name != 'pull_request' | |
| uses: EndBug/add-and-commit@v9 | |
| with: | |
| # Descriptive commit message for git history | |
| message: "Building the ontology from the edits" | |
| # Working directory (repository root) | |
| cwd: "." | |
| # Add generated files, forcing inclusion despite .gitignore | |
| # Pattern breakdown: | |
| # - src/ontology/*.owl : All OWL files (base, full, simple, etc.) | |
| # - src/ontology/*.json : JSON-LD serializations | |
| # - src/ontology/*.ttl : Turtle serializations | |
| # - src/ontology/imports/*.owl : Import modules | |
| add: "src/ontology/*.owl src/ontology/*.json src/ontology/*.ttl src/ontology/imports/*.owl --force" | |
| # Use GitHub Actions bot as commit author | |
| default_author: github_actions | |
| # Push to current branch | |
| push: true | |
| # ======================================================================== | |
| # STEP 4: Trigger Documentation Workflow | |
| # ======================================================================== | |
| # Dispatches repository event to start the documentation generation workflow | |
| # | |
| # Workflow Chain: | |
| # setup-repo → refresh-imports → qc → [DOCS] | |
| # | |
| # Why trigger docs after QC? | |
| # - Documentation is generated from release assets (*-full.owl) | |
| # - Ensures docs reflect the latest built ontology | |
| # - Keeps documentation synchronized with ontology content | |
| # | |
| # Why repository_dispatch? | |
| # - Allows explicit workflow chaining | |
| # - Maintains clear separation between workflow stages | |
| # - Prevents race conditions with concurrent triggers | |
| # | |
| # Condition: Only trigger for non-PR events | |
| # - PRs get preview docs via push trigger after merge | |
| # - Prevents duplicate doc builds during PR review | |
| # | |
| # Event type: trigger-docs | |
| # Listened for by: docs.yml | |
| # ======================================================================== | |
| - name: Trigger Documentation Workflow | |
| # Skip for pull requests (docs will build via push trigger after PR merge) | |
| if: github.event_name != 'pull_request' | |
| uses: peter-evans/repository-dispatch@v3 | |
| with: | |
| # Use default GitHub token (automatically available) | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| # Event name that docs.yml listens for | |
| event-type: trigger-docs |