Automated EFI workload orchestration

dispatch automates bare-metal testing workflows. It does the following:

1. downloads metadata of dispatch-enabled workloads from GitHub release assets
2. manages the queue of workloads and workload execution state
3. offers workload download over HTTP for HTTP boot clients
4. files GitHub issues with workload execution results

For full details, see below.

# Authenticate with GitHub
gh auth login

# Serve all dispatch-enabled assets from latest release
dispatch --owner AMDEPYC --repo dispatch --tag example

# Filter which dispatch-enabled assets to run by name
dispatch --owner AMDEPYC --repo dispatch --tag example workload-7

See Permissions section for more on authenticating with GitHub.

sequenceDiagram
    participant G as github
    participant D as dispatch
    participant S as server
    participant W as workload
    participant B as beacon

    Note over D: 🚀 MANUAL: Start dispatch
    D->>G: list assets
    G->>D: asset list
    D->>D: filter asset list
    D->>D: create execution queue
    D->>D: start http server
    
    Note over S: ⚙️ MANUAL: Configure HTTP Boot URL
    Note over S: 🔌 MANUAL: Power on server
    S->>S: power on

    loop For each workload
        S->>D: get size of next workload (HTTP HEAD)
        D->>D: workload moves to 📌 state (assigned)
        D->>S: size of next workload
        S->>S: allocate memory

        S->>D: get next workload (HTTP GET)
        alt Workload available
            D->>D: workload moves to 📥 state (downloading)
            D->>S: next workload
            S->>W: boot workload
            
            W->>B: beacon boot
            B->>D: notify that workload has started
            D->>D: workload moves to ⚡ state (booting)

            W->>W: run tests
            W->>W: collect test results
            W->>B: beacon report ...
            B->>D: report test results
            D->>D: workload moves to 📝 state (reported)
            D->>G: create github issue with test results
            D->>D: workload moves to 🏁 state (finished)

            W->>S: reboot
        else No workloads remaining
            D->>S: poweroff.efi (shutdown workload)
            S->>S: power off
        end
    end

• GitHub Integration: Automatically loads assets from GitHub releases
• HTTP Boot Server: Standards-compliant HTTP boot for bare metal
• Job Queue Management: Tracks workload assignment and execution state
• Automated Reporting: Creates GitHub issues from workload results
• Service Discovery: mDNS broadcast for network discoverability
• Opt-in Deployment: Only assets with dispatch content types are deployed

dispatch uses an opt-in deployment model through custom content types. Only assets explicitly tagged with dispatch-specific content types will be deployed, allowing repositories to control which workloads participate in automated testing.

The following content types are recognized by dispatch:

Only files with the application/vnd.dispatch+* content types will be included in the dispatch queue.

Each workload progresses through these states:

1. ⏳ Unassigned → Available for assignment
2. 📌 Assigned → Reserved for specific server IP
3. 📥 Downloading → Server fetching workload
4. ⚡ Booting → Workload is booting (via beacon boot)
5. 📝 Reported → Results submitted (via beacon report)
6. 🏁 Finished/Failed → Final state

dispatch uses GitHub APIs to download Release Assets and to create Issues in the repo specified on the dispatch command line. Certain permissions are needed for this to work.

Before running dispatch, run 'gh auth login' and choose to authenticate via the web browser flow.

Before running dispatch, run 'gh auth login' and choose to authenticate by pasting an authentication token.

If using a fine-grained token (PAT), it must have, at a minimum, the following permissions:

• Contents Read-only access
• Issues Read and write access

If using a classic token (PAT), it must have, at a minimum, the repo permission.

When running dispatch, use the --token option and specify either a fine-grained or a classic PAT as described above.

Before running dispatch, set an environment variable named GITHUB_TOKEN to either a fine-grained or a classic PAT as described above.