brainwave/docs/superpowers/specs/2026-04-24-ansible-arm-deploy-design.md

ARM Deploy to OrangePi via Ansible — Design Spec

Overview

After a successful Gitea release, a separate workflow automatically deploys the ARM64 Docker image to an OrangePi using Ansible. The Gitea runner acts as the Ansible controller and SSHes into the OrangePi to copy artifacts and restart the container.

Trigger

A new deploy.yml workflow triggers via workflow_run when the Release Pipeline workflow completes successfully. This keeps deployment concerns separate from the build/release workflow.

New Files

• .gitea/workflows/deploy.yml — deployment workflow
• ansible/inventory.ini — Ansible inventory for the OrangePi
• ansible/deploy.yml — Ansible playbook

Workflow Steps (deploy.yml)

1. Checkout the repository (to access ansible files)
2. Install Ansible on the runner
3. Write ANSIBLE_SSH_KEY secret to a temp file (/tmp/ansible_key) with chmod 600
4. Resolve the release tag from github.event.workflow_run.head_branch
5. Download brainwave-arm64.tar.gz and docker-compose.arm64.yml from the Gitea release using wget against the Gitea release download URL
6. Run ansible-playbook ansible/deploy.yml -i ansible/inventory.ini
7. Clean up the SSH key temp file

Playbook Tasks (ansible/deploy.yml)

Runs against the orangepi host group. Tasks in order:

1. Ensure /home/user/brainwave directory exists
2. Copy brainwave-arm64.tar.gz to /home/user/brainwave/
3. Copy docker-compose.arm64.yml to /home/user/brainwave/docker-compose.yml
4. Load the Docker image: docker load -i /home/user/brainwave/brainwave-arm64.tar.gz
5. Run docker compose up -d in /home/user/brainwave

Inventory (ansible/inventory.ini)

[orangepi]
orangepi ansible_host={{ ANSIBLE_HOST }} ansible_user={{ ANSIBLE_USER }} ansible_ssh_private_key_file=/tmp/ansible_key

Host and user are injected at runtime from Gitea secrets via environment variables or extra-vars.

Secrets Required

Secret	Description
ANSIBLE_HOST	OrangePi IP address or hostname
ANSIBLE_USER	SSH username on the OrangePi
ANSIBLE_SSH_KEY	Full content of the SSH private key

These must be added to the Gitea repository settings under Settings → Secrets.

Deploy Directory

All files are deployed to /home/user/brainwave on the OrangePi. The docker-compose file is renamed to docker-compose.yml so docker compose commands work without specifying a filename.

Error Handling

• The workflow only runs if github.event.workflow_run.conclusion == 'success', preventing deploys from failed releases.
• The SSH key temp file is always cleaned up in a final step regardless of success or failure.