platform-deployments/.forgejo/actions

Forgejo Actions

Reusable composite actions for CI/CD workflows.

Service Actions

Generic actions for deploying services. Located in services/.

python-service

Deploys Python/FastAPI services via systemd.

- uses: ./.forgejo/actions/services/python-service
  with:
    mode: reconcile
    host: apricot
    ssh_alias: apricot-ssh
    service_name: my-service        # systemd service name
    deploy_path: /opt/my-service    # target directory
    source_path: features/x/y       # relative to codebase
    codebase_path: ./codebase       # local codebase checkout
    port: '8100'                    # health check port

What it does:

1. Syncs source code via rsync
2. Creates/updates Python venv
3. Installs dependencies from requirements.txt or pyproject.toml
4. Configures Forgejo PyPI registry for @lilith/* packages
5. Manages systemd service (enable, start, restart)
6. Waits for health check

node-service

Deploys Node.js services (static frontends or API backends).

# Static frontend
- uses: ./.forgejo/actions/services/node-service
  with:
    mode: reconcile
    host: black
    ssh_alias: black-ssh
    service_type: static
    deploy_path: /var/www/my-app
    artifacts_path: ./dist

# API backend
- uses: ./.forgejo/actions/services/node-service
  with:
    mode: reconcile
    host: black
    ssh_alias: black-ssh
    service_type: api
    service_name: my-api            # systemd service name
    deploy_path: /opt/my-api
    artifacts_path: ./dist
    port: '3000'
    health_endpoint: '/api/health'

What it does:

1. Syncs built artifacts via rsync
2. For API type: manages systemd service
3. Waits for health check (API type)

Infrastructure Actions

Located in services/ alongside service actions.

Action	Purpose	Hosts
host-status-monitor	System monitoring agent	all
health-monitor	Service health checks	0
ssl-certificate	SSL cert management	0
nginx-config-sync	Nginx configuration	0
devops-stack	Forgejo, registry	black
feature-databases	PostgreSQL, Redis	apricot
kernel-tuning	System optimization	VPN hosts

Utility Actions

Action	Purpose
setup-ssh	Configure SSH for host access
snapshot	Capture/verify host state

Adding a New Service

Python Service

1. Create systemd service file in deployments/systemd/:

   # my-service.service
   [Unit]
   Description=My Python Service
   After=network-online.target
   
   [Service]
   Type=simple
   User=lilith
   WorkingDirectory=/opt/my-service
   ExecStart=/opt/my-service/venv/bin/uvicorn src.main:app --port 8100
   Restart=always
   
   [Install]
   WantedBy=multi-user.target
   

2. Add to reconcile.yml:

   - name: Reconcile my-service
     if: contains(env.CHANGED_FEATURES, 'my-feature')
     uses: ./.forgejo/actions/services/python-service
     with:
       mode: reconcile
       host: apricot
       ssh_alias: apricot-ssh
       service_name: my-service
       deploy_path: /opt/my-service
       source_path: features/my-feature/my-service
       codebase_path: ./codebase
       port: '8100'
   

Node.js Service

1. Ensure turbo builds the package (it auto-detects from package.json)

2. For API services, create systemd file in deployments/systemd/

3. Add to reconcile.yml:

   - name: Reconcile my-frontend
     if: contains(env.CHANGED_FEATURES, 'my-feature')
     uses: ./.forgejo/actions/services/node-service
     with:
       mode: reconcile
       host: black
       ssh_alias: black-ssh
       service_type: static
       deploy_path: /var/www/my-app
       artifacts_path: ./artifacts/features/my-feature/frontend/dist
   

Modes

All service actions support three modes:

Mode	Purpose
status	Check current state
reconcile	Deploy/update to desired state
restore	Stop/rollback service