# Automation

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

```mermaid
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.