Ocuroot can integrate with GitHub Actions to automate your build and deployment workflows without replacing your existing setup. This guide explains how to set up and use GitHub Actions with your Ocuroot projects.

​
Setting Up GitHub Actions

​
Prerequisites

  1. A GitHub repository with GitHub Actions enabled
  2. An Ocuroot API key (stored as a GitHub secret named OCUROOT_API_KEY)
  3. For sync triggers, a GitHub token with repository access (stored as GH_TRIGGER_TOKEN)

​
Workflow Files

You’ll need three workflow files in your .github/workflows directory:

​
1. Review Workflow (review.yml)

This workflow runs on pull requests to review code changes:

name: Review

on:
  pull_request:
    branches: [ "main" ]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2

    - name: Download Ocuroot binary
      run: |
        curl -H "Authorization: Bearer $OCUROOT_API_KEY" -o ./ocuroot.tar.gz https://app.ocuroot.com/downloads/linux/amd64/ocuroot.tar.gz
        tar -xvf ocuroot.tar.gz  -C /usr/local/bin/
        chmod +x /usr/local/bin/ocuroot
        rm ocuroot.tar.gz
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}

    - name: Ocuroot Cache
      uses: actions/cache@v4
      with:
        path: .ocuroot/cache
        key: ${{ runner.os }}-ocuroot-cache

    - name: Ocuroot Review
      run: ocuroot review

​
2. Deliver Workflow (deliver.yml)

This workflow runs when code is merged to main:

name: Deliver

on:
  push:
    branches: [ "main" ]

jobs:
  deliver:
    runs-on: ubuntu-latest
    permissions:
      actions: write  # Required to trigger workflows
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2

    - name: Download Ocuroot binary
      run: |
        curl -H "Authorization: Bearer $OCUROOT_API_KEY" -o ./ocuroot.tar.gz https://app.ocuroot.com/downloads/linux/amd64/ocuroot.tar.gz
        tar -xvf ocuroot.tar.gz  -C /usr/local/bin/
        chmod +x /usr/local/bin/ocuroot
        rm ocuroot.tar.gz
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}

    - name: Ocuroot Cache
      uses: actions/cache@v4
      with:
        path: .ocuroot/cache
        key: ${{ runner.os }}-ocuroot-cache

    - name: Ocuroot Deliver
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}
      run: ocuroot deliver
    
    - name: Trigger Sync
      run: ocuroot trigger-sync
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

​
3. Sync Workflow (sync.yml)

This workflow handles deployments and can be triggered manually or via repository dispatch:

name: Sync

on:
  repository_dispatch:
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      actions: write  # Required to trigger workflows
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2

    - name: Download Ocuroot binary
      run: |
        curl -H "Authorization: Bearer $OCUROOT_API_KEY" -o ./ocuroot.tar.gz https://app.ocuroot.com/downloads/linux/amd64/ocuroot.tar.gz
        tar -xvf ocuroot.tar.gz  -C /usr/local/bin/
        chmod +x /usr/local/bin/ocuroot
        rm ocuroot.tar.gz
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}

    - name: Ocuroot Cache
      uses: actions/cache@v4
      with:
        path: .ocuroot/cache
        key: ${{ runner.os }}-ocuroot-cache

    - name: Ocuroot Sync
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}
      run: ocuroot sync
    
    - name: Trigger Follow-Up Sync
      run: ocuroot trigger-sync
      env:
        OCUROOT_API_KEY: ${{ secrets.OCUROOT_API_KEY }}
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

​
Common Elements

Each workflow includes:

  1. Ocuroot Binary Download: Downloads and installs the Ocuroot CLI
  2. Cache Configuration: Uses GitHub’s cache action to speed up builds
  3. Authentication: Uses the OCUROOT_API_KEY for API authentication

​
Setting Up Secrets

To use Ocuroot with GitHub Actions, you need to configure the OCUROOT_API_KEY as a repository secret. Here’s how:

  1. Navigate to your GitHub repository
  2. Go to Settings > Secrets and variables > Actions
  3. Click New repository secret
  4. Set the name as OCUROOT_API_KEY
  5. Paste your Ocuroot API key as the value
  6. Click Add secret

For more details on managing repository secrets, see GitHub’s official documentation on encrypted secrets.

If you’re setting up secrets for an organization:

  • Organization-wide secrets can be configured at Organization Settings > Secrets and variables > Actions
  • Environment-specific secrets can be configured in Repository Settings > Environments

​
Setting Up Sync Triggers

The ocuroot trigger-sync command is used to automatically trigger the sync workflow after a successful delivery. This command uses GitHub’s API to trigger the sync workflow.

​
Configure Sync Trigger Logic

In your repo.ocu.star file, define the trigger_sync function that will be called by the ocuroot trigger-sync command:

def trigger_sync():
    owner="your-org"
    repo="your-repo"
    workflow_id="sync.yml"

    response = http.post(
        url="https://api.github.com/repos/{}/{}/actions/workflows/{}/dispatches".format(owner, repo, workflow_id),
        headers={
            "Accept": "application/vnd.github+json",
            "Authorization": "Bearer {}".format(env.get("GH_TOKEN")),
            "X-GitHub-Api-Version": "2022-11-28",
        },
        body="{\"ref\": \"main\", \"inputs\": {}}",
    )
    if response.status_code != 204:
        fail("Failed to trigger workflow:" + response.body)

This setup allows your delivery workflow to automatically trigger the sync workflow when needed, creating a seamless deployment pipeline.

​
Next Steps

Integrating with your CI PlatformThe Ocuroot CLI