Deploy with GitHub Actions

Towbar includes a Deploy release workflow for repeatable control-plane upgrades. The simplest setup uses SSH from a GitHub-hosted runner to an existing Linux server. AWS installations can use Systems Manager instead, without storing an SSH key in GitHub. The workflow deploys only stable published releases. A manual run also requires an existing published tag. It verifies that the tag’s package.json version matches the tag, checks out the exact release commit on the server, builds the API, worker, and dashboard, applies migrations, waits for Compose health checks, and verifies the commit reported by the API. Deployments are serialized with a host lock. A failed replacement restores the previous checkout and Compose images.

Prepare the server once

Install Docker Engine with Compose v2, Git, OpenSSL, an SSH server, GNU base64, and flock from util-linux. Ubuntu includes the last two utilities by default. Use a dedicated server or VM and a dedicated SSH key. The SSH account needs non-interactive sudo because a deployment manages system-owned containers and the checkout while preserving the checkout’s ordinary owner. Create the installation directory as the SSH account, clone Towbar, and create the host-managed environment file:

sudo install -d -m 0755 -o "$USER" -g "$USER" /opt/towbar
git clone https://github.com/avgeek-inc/towbar.git /opt/towbar
cd /opt/towbar
cp .env.example .env
chmod 600 .env

Fill .env using the installation guide, then verify the prerequisites without starting an unreviewed checkout:

docker compose --env-file .env config --quiet
sudo --non-interactive true
git status --short

The final command must be empty. The workflow rejects tracked changes instead of overwriting host edits. Keep .env on the server; it is ignored by Git and is never copied into GitHub Actions.

Create the deployment key

Generate a dedicated Ed25519 key on a trusted workstation. Do not reuse a personal key:

ssh-keygen -t ed25519 -C towbar-github-actions -f towbar-deploy

Add towbar-deploy.pub to the server account’s ~/.ssh/authorized_keys. Store the complete private key as the TOWBAR_DEPLOY_SSH_PRIVATE_KEY secret in a GitHub environment named production.

Configure the production environment

Create a GitHub environment named production, require approval if more than one person can publish releases, and restrict it to the protected default branch and stable release tags. Add these environment variables:

Variable	Value or purpose
`TOWBAR_DEPLOY_ENABLED`	`true` to deploy stable releases automatically
`TOWBAR_DEPLOY_TRANSPORT`	`ssh`
`TOWBAR_DEPLOY_SSH_USER`	SSH account; defaults to `ubuntu`
`TOWBAR_DEPLOY_SSH_PORT`	SSH port; defaults to `22`
`TOWBAR_DEPLOY_PATH`	Existing checkout; defaults to `/opt/towbar`
`TOWBAR_DEPLOY_API_HEALTH_URL`	Optional public API `/health` URL
`TOWBAR_DEPLOY_APP_HEALTH_URL`	Optional public dashboard URL

Add these environment secrets:

Secret	Purpose
`TOWBAR_DEPLOY_SSH_HOST`	Server DNS name or IP address
`TOWBAR_DEPLOY_SSH_PRIVATE_KEY`	Complete dedicated private key

GitHub-hosted runners start with an empty SSH profile. The workflow accepts the host key presented during each run, so no known_hosts secret is required. The deployment key can initiate a root-level release through sudo; protect the environment, restrict who can modify the workflow and default branch, and rotate the key after suspected exposure.

Run the first deployment

Publish a stable release such as v2.0.0, or select Actions → Deploy release → Run workflow and enter an existing stable published tag. Stable releases deploy automatically when TOWBAR_DEPLOY_ENABLED is true. Manual runs remain available without that variable, which lets you test the deployment before enabling automatic releases. Review the workflow summary and then verify:

cd /opt/towbar
sudo docker compose --env-file .env ps
sudo docker compose --env-file .env logs --tail 200 migrate api worker

Complete initial account setup using the one-time setup link from the installation guide. A successful workflow proves that the selected release is running; continue with the public ingress, provider, SMTP, backup, and recovery checks required by your installation.

Use AWS Systems Manager instead

Set TOWBAR_DEPLOY_TRANSPORT=aws-ssm or omit it for the default AWS transport. Configure these production environment variables:

Variable	Purpose
`TOWBAR_DEPLOY_ENABLED`	`true` to deploy stable releases automatically
`TOWBAR_DEPLOY_AWS_ROLE_ARN`	GitHub OIDC role assumed by the workflow
`TOWBAR_DEPLOY_AWS_REGION`	Region containing the managed EC2 instance
`TOWBAR_DEPLOY_INSTANCE_ID`	Only instance the role may command
`TOWBAR_DEPLOY_PATH`	Existing checkout; defaults to `/opt/towbar`
`TOWBAR_DEPLOY_API_HEALTH_URL`	Optional public API `/health` URL
`TOWBAR_DEPLOY_APP_HEALTH_URL`	Optional public dashboard URL

Read the repository’s OIDC subject prefix with:

gh api repos/<owner>/<repository>/actions/oidc/customization/sub --jq .sub_claim_prefix

Trust only <returned-prefix>:environment:production in the AWS role. Grant ssm:SendCommand only for AWS-RunShellScript and the target instance, plus ssm:GetCommandInvocation for reporting. The instance must be online in Systems Manager.

Troubleshoot a failed deployment

A tag validation failure means the release is missing, draft, prerelease, or does not match the package version.
A dirty-checkout error protects host changes from being overwritten. Move the change into a reviewed commit or restore the checkout.
A missing .env or permissive file mode must be fixed on the host. Use mode 600 or 400.
A Compose health failure triggers rollback. Inspect the workflow output and the host’s migrate, api, and worker logs before retrying.

The deployment script does not back up PostgreSQL. Follow the upgrade checklist before publishing or manually dispatching an upgrade.

​Prepare the server once

​Create the deployment key

​Configure the production environment

​Run the first deployment

​Use AWS Systems Manager instead

​Troubleshoot a failed deployment