AeThex-OS/.github/GITHUB_ACTIONS_ISO_BUILD.md

GitHub Actions - ISO Build Automation

How It Works

The build-iso.yml workflow automatically builds the AeThex Linux ISO whenever you:

1. Push changes to main branch (if relevant files changed)
2. Manually trigger it from GitHub Actions tab

Automatic Triggers

The workflow runs automatically when changes are pushed to:

• client/** - React frontend
• server/** - Node.js backend
• shared/** - Shared schema
• src-tauri/** - Tauri desktop app
• script/build-linux-iso.sh - Build script itself
• configs/** - System configuration
• .github/workflows/build-iso.yml - This workflow file

Manual Trigger

1. Go to GitHub → Actions tab
2. Select "Build AeThex Linux ISO" workflow
3. Click "Run workflow" button
4. Optionally check "Create a GitHub release" to publish the ISO

Outputs

Artifacts

• ISO file: Available as artifact for 90 days
• Checksum: SHA256 verification file
• Download from: Actions → Workflow run → Artifacts

Releases (Optional)

If you check "Create a GitHub release":

• Creates a GitHub Release with the ISO
• Makes it publicly downloadable
• Includes SHA256 checksum for verification
• Pre-release tag for testing builds

Usage Examples

Download Built ISO

# Via GitHub Actions artifacts
1. Go to Actions tab
2. Select latest "Build AeThex Linux ISO" run
3. Download "AeThex-Linux-ISO" artifact

# Via GitHub CLI
gh run list --workflow=build-iso.yml --branch=main
gh run download <RUN_ID> -n AeThex-Linux-ISO

Create Bootable USB from Downloaded ISO

# Verify integrity
sha256sum -c AeThex-Linux-*.sha256

# Write to USB
sudo dd if=AeThex-Linux-*.iso of=/dev/sdX bs=4M status=progress

# Eject
sudo eject /dev/sdX

Automate Releases on Tags

Edit the workflow to release on git tags:

on:
  push:
    tags:
      - 'v*'  # Trigger on version tags like v1.0.0

Then:

git tag v1.0.0
git push origin v1.0.0

Build Status Badge

Add to your README:

[![Build AeThex Linux ISO](https://github.com/AeThex-Corporation/AeThex-OS/actions/workflows/build-iso.yml/badge.svg)](https://github.com/AeThex-Corporation/AeThex-OS/actions/workflows/build-iso.yml)

Monitoring Builds

Check Recent Builds

1. GitHub UI: Actions tab → Select workflow
2. GitHub CLI:

   gh run list --workflow=build-iso.yml
   gh run view <RUN_ID> --log
   

3. Terminal:

   gh workflow list
   gh run list -w build-iso.yml -L 5
   

Get Build Logs

# Download full logs
gh run download <RUN_ID> --dir ./logs

# View in terminal
gh run view <RUN_ID> --log

Customization

Change Trigger Conditions

Edit .github/workflows/build-iso.yml:

on:
  push:
    branches:
      - main
      - develop  # Also build on develop branch
    paths:
      - 'src-tauri/**'  # Only rebuild when Tauri changes

Add Slack Notifications

- name: Notify Slack
  if: always()
  uses: slackapi/slack-github-action@v1
  with:
    webhook-url: ${{ secrets.SLACK_WEBHOOK }}
    payload: |
      {
        "text": "AeThex Linux ISO Build: ${{ job.status }}"
      }      

Upload to S3 or CDN

- name: Upload to S3
  uses: jakejarvis/s3-sync-action@master
  with:
    args: --acl public-read
  env:
    AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    AWS_REGION: 'us-east-1'
    SOURCE_DIR: '~/aethex-linux-build'

Troubleshooting

Build Timeout (60 minutes)

If builds take too long, try:

• Pre-compile dependencies
• Cache Docker layers
• Use GitHub-hosted larger runners (if available)

Out of Disk Space on Runner

The workflow runs on Ubuntu Latest with ~14GB free (enough for this build). If it fails:

1. Check workflow logs
2. Remove unnecessary steps
3. Use disk-usage-cleanup action

Artifacts Not Uploading

• Check artifact path is correct
• Verify file was actually created
• Check artifact retention settings

Security

Best Practices

1. Limit artifact access:

   permissions:
     contents: read
   

2. Sign releases:

   - name: Create signed release
     with:
      gpg_key: ${{ secrets.GPG_KEY }}
   

3. Restrict workflow to trusted users:

   • Only allow manual runs from specific users
   • Use branch protection rules

Next Steps

1. Push changes to trigger build:

   git add .
   git commit -m "Add AeThex Linux build automation"
   git push origin main
   

2. Monitor first build:

   • Go to Actions tab
   • Watch build progress
   • Download artifact when complete

3. Set up releases (optional):

   • Modify workflow to create releases
   • Distribute ISOs publicly
   • Track versions

4. Add to README:

   ## Download AeThex Linux
   
   Get the latest bootable ISO:
   - [![Build Status](badge-url)](actions-url)
   - Download from [Releases](releases)
   

---

Total build time: ~30-45 minutes on GitHub Actions runners No local storage required: Building happens in the cloud