project-charlie/docs/automation.md

Automation

Reusable Gitea Actions live in this repo and are consumed by stack/source repos.

flowchart LR
  Push[Stack push] --> Gitea
  Gitea --> Runner[Any runner]
  Runner -->|step-ca SSH cert| Host[Target host]
  Host --> Sync[Git sync]
  Sync --> Secrets[SOPS decrypt]
  Secrets --> Compose[Compose pull/up]

Workflow/action	Online source	Purpose
deploy-stack.yml	https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/.gitea/workflows/deploy-stack.yml	Deploy a stack on a target host.
build-image.yml	https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/.gitea/workflows/build-image.yml	Build and push a source repo image.
charlie-ssh-open	https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/.gitea/actions/charlie-ssh-open	Open a cert-backed SSH session.
charlie-ssh-target	https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/.gitea/actions/charlie-ssh-target	Run a command through that session.
charlie-ssh-close	https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/.gitea/actions/charlie-ssh-close	Close and clean up the session.

Deploy path

Stage	State
Trigger	Push or manual dispatch in Charlie/<stack>.
Runner	Any self-hosted runner can pick up the job.
Auth	step-ca SSH user cert for sys-gitea-runner.
Target	Host from the workflow host input.
Work	Git sync, optional SOPS decrypt, compose pull/up, cleanup.
Registry pull	Built into deploy-stack.yml through an encrypted RO PAT.

Build path

Stage	State
Trigger	Source repo push or manual dispatch.
Runner	Any self-hosted runner.
Build host	Host from workflow host input.
Tags	latest plus UTC timestamp.
Deploy	Stack repos pin the desired image tag.

Gitea constraints kept in mind

Constraint	Current handling
Cross-repo uses needs auth	Absolute Gitea URLs with PAT auth.
Reusable-workflow runner labels unreliable	Use runs-on: self-hosted; route by SSH target.
act caches @main aggressively	Tag workflow/action contracts when stable.
Shared-stack matrix can race on NFS/plaintext	Serialize jobs with needs where required.
Runner stack must not recreate itself mid-job	Charlie/runners cross-deploys with its own workflow.

Workflow inputs are documented in the workflow files themselves.