GitHub Actions

This guide covers automating the deployment of a Kyushu worker to a VPS using GitHub Actions.

Prerequisites

A VPS with Kyushu running as a systemd service (see Deploy on a VPS)

Setup

Generate an SSH key pair

On your local machine, generate a key for the deployment:
Terminal window
```
ssh-keygen -t ed25519 -C "github-actions-myuser" -f ~/.ssh/myuser_key
```
Leave the passphrase empty.

Leaving the passphrase empty makes it easier to automate deployments with GitHub Actions. However, this requires securing the private key by limiting it to this use and storing it securely.
Create a dedicated user on the VPS

Rather than using root, create a user with limited privileges:

Creating one deploy user per app - if you host multiple - is the cleanest approach as it scopes permissions to its own service.
Terminal window
```
useradd -m -s /bin/bash myuser
mkdir -p /home/myuser/.ssh
chown -R myuser:myuser /home/myuser/.ssh
chmod 700 /home/myuser/.ssh
```
Grant the user privileges for deployment

Grant write access to your worker directory:
Terminal window
```
chown -R myuser:myuser /opt/myapp
```
And allow the user to restart Kyushu without a password:
Terminal window
```
echo "myuser ALL=(ALL) NOPASSWD: /bin/systemctl restart myapp" > /etc/sudoers.d/myapp-myuser
```

Add public key to the server

Copy the content of your public key to the user’s authorized_keys file on the VPS.

nano /home/myuser/.ssh/authorized_keys
# Paste the content of your local ~/.ssh/myuser_key.pub
chown myuser:myuser /home/myuser/.ssh/authorized_keys
chmod 600 /home/myuser/.ssh/authorized_keys

Add secrets to your GitHub repository

In your repository on GitHub, go to Settings → Secrets and variables → Actions and add:

Secret Value
KYUSHU_SSH_KEY Contents of ~/.ssh/myuser_key (private key)
KYUSHU_HOST Your VPS IP or hostname
Delete the local private key (optional)

Once added to GitHub Secrets, you can delete the private key from your local machine:
Terminal window
```
 rm ~/.ssh/myuser_key ~/.ssh/myuser_key.pub
```

Secret	Value
`KYUSHU_SSH_KEY`	Contents of `~/.ssh/myuser_key` (private key)
`KYUSHU_HOST`	Your VPS IP or hostname

Create the GitHub Actions workflow

Lastly, setup the deployment pipeline by creating .github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install kyu
        run: |
          curl -fsSL https://kyushu.dev/install | bash
          echo "/root/.kyu/bin" >> $GITHUB_PATH

      - name: Build
        run: kyu build

      - name: Upload artifacts
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: worker
          path: worker/

  deploy:
    needs: build
    runs-on: ubuntu-latest

    steps:
      - name: Download artifacts
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: worker
          path: worker/

      - name: Setup SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.KYUSHU_SSH_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H ${{ secrets.KYUSHU_HOST }} >> ~/.ssh/known_hosts

      - name: Deploy
        run: |
          rsync -avz ./worker myuser@${{ secrets.KYUSHU_HOST }}:/opt/myapp/
          ssh myuser@${{ secrets.KYUSHU_HOST }} "sudo systemctl restart myapp"

Adjust /opt/myapp/ and add any additional resources your project requires.

Verify

Push a change to your main branch, then check the Actions tab in your GitHub repository. Once the workflow completes, verify the deployment:

curl https://yourdomain.com