Build a software factory

Give a GitHub issue to Codex or Claude. The selected agent works inside a fresh Jio VM, runs your tests, and returns a draft pull request for human review.

See the complete software factory example.

Prerequisites

• A public GitHub repository
• JIO_API_KEY and an API key for Codex, Claude, or both

The guest needs Python 3.12, Node.js 24 with npm, Git, Bash, OpenSSH, and the jio user at /home/jio.

Under Settings → Actions → General, allow GitHub Actions to create pull requests. Keep branch protection and human review enabled.

Add the workflow

Create .github/workflows/jio.yml:

name: Jio task

on:
  issues:
    types: [labeled]
  issue_comment:
    types: [created]
  workflow_dispatch:
    inputs:
      issue:
        description: 'Issue number'
        required: true
        type: string
      agent:
        description: 'Coding agent'
        required: true
        type: choice
        options: [codex, claude]

permissions: {}

jobs:
  task:
    if: github.actor == 'saugardev' && github.triggering_actor == 'saugardev'
    permissions:
      contents: write
      issues: write
      pull-requests: write
    # Replace BOTH occurrences with the same reviewed 40-character factory commit.
    uses: jiovannish/software-factory/.github/workflows/factory.yml@REPLACE_WITH_FACTORY_COMMIT
    with:
      factory_ref: REPLACE_WITH_FACTORY_COMMIT
      agent: ${{ inputs.agent || '' }}
      issue: ${{ inputs.issue || '' }}
    secrets:
      JIO_API_KEY: ${{ secrets.JIO_API_KEY }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      CODEX_AUTH_JSON: ${{ secrets.CODEX_AUTH_JSON }}
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

See software-factory issue #1 for a real task example.

Configure the factory

Create factory.toml in the repository root:

# Commands run inside the target repository in Jio, using bash -e -o pipefail.
# Replace these Python examples with your project's setup and checks.
setup = "python3 -m venv .venv && .venv/bin/pip install -r requirements.txt"
test = ".venv/bin/python -m pytest -q"

[models]
codex = "REPLACE_WITH_OPENAI_MODEL_ID"
claude = "REPLACE_WITH_ANTHROPIC_MODEL_ID"

Set the setup command, test command, and model ID for each provider you use. The commands run from the cloned repository with bash -e -o pipefail.

Add the secrets

Add these under Settings → Secrets and variables → Actions:

Only the selected provider key is required for a task. Use dedicated API keys; do not copy personal agent logins into long-running automation.

Assign a task

Open an issue, then approve it by commenting:

/jio codex
Also cover names containing only whitespace.

Use /jio claude to select Claude. The command must be on the first line; following lines add instructions to the issue title and body.

You can also apply jio:codex or jio:claude, or run Actions → Jio task → Run workflow with an open issue number and agent.

Review the result

The workflow freezes the issue, base commit, and configuration before it starts. It creates one VM, clones the public repository, runs setup, starts the selected agent, and runs the configured tests again.

A successful task creates a draft pull request and comments on the issue. Failed tests, an empty patch, or agent failure create no pull request. Artifacts retain the task, test output, result, and successful patch for seven days.

The VM is destroyed after every task. If cleanup cannot reach Jio, the account's one-hour expiry is the fallback. The example does not support private repositories, automatic merging, persistent workspaces, or VM restart recovery.

GitHub and Jio credentials stay on the runner. The selected provider key reaches only the agent invocation inside the VM. The agent has full access to that VM, and the trusted Jio host operator can inspect its contents.

Read the example's docs/README.md for lifecycle, security, and recovery details.