workflow-templates

This repository is a Forgejo-first CI/CD template system for projects that need consistent build pipelines, deterministic releases, and mandatory GitHub mirroring without relying on GitHub Actions to do the publishing work.

The templates are structured so the workflows stay small and orchestration-only, while the reusable mechanics live in ci/ shell entrypoints. The current templates preserve the repository's required guarantees:

• APT proxy bootstrap happens before any apt-get usage.
• Release tags trigger on both v* and V*.
• GitHub mirroring is mandatory and uses GitHub's API plus git push.
• Release publishing is idempotent and replaces existing assets cleanly.
• Android release publishing keeps the strict single-APK contract.

Structure

.
├── .forgejo/workflows/
│   ├── android-release.yml
│   ├── default-freebsd.yml
│   ├── default-linux.yml
│   └── multi-system.yml
├── ci/
│   ├── bootstrap.sh
│   ├── build.sh
│   ├── migrate_github.sh
│   ├── publish_forgejo.sh
│   └── publish_github.sh
├── docs/
│   ├── README.md
│   └── workflows/
│       ├── android.md
│       └── freebsd.md
├── LICENSE
├── README.md
└── TEMPLATE.md

Philosophy

The repository separates concerns deliberately:

• Workflows decide when jobs run and which runner model they use.
• ci/bootstrap.sh owns Linux package bootstrap and the mandatory APT proxy.
• ci/build.sh owns build-mode validation and execution.
• ci/build.sh also owns the FreeBSD package assembly path for Linux cross-compiles.
• ci/migrate_github.sh owns GitHub repository creation and ref mirroring.
• ci/publish_forgejo.sh and ci/publish_github.sh own idempotent release API behavior.

That split keeps project-specific edits concentrated in the env blocks at the top of each workflow instead of scattered across release logic.

Using The Templates

1. Copy the workflow file that matches the project type into the target repo's .forgejo/workflows/.
2. Copy the ci/ directory into the target repo unchanged unless you are making a deliberate, reviewed platform change.
3. Edit the workflow env values for the target project:
   • build and test commands
   • FreeBSD package metadata and staged install path
   • Android artifact name prefix and APK glob
   • GitHub mirror destination
   • release naming and release body text
4. Add the required secrets described in TEMPLATE.md.
5. Validate the scripts with sh -n ci/*.sh and validate workflow YAML before pushing tags.

For a simple one-shot install, use deploy.sh:

./deploy.sh multi-system.yml /path/to/repo

That command resolves the template from .forgejo/workflows/, creates /path/to/repo/.forgejo/workflows/, and installs the selected template as build.yml.

Safe Extension Rules

• Do not remove the APT proxy bootstrap from Linux container jobs.
• Do not narrow the tag triggers to only lowercase tags.
• Do not make GH_KEY optional.
• Do not move GitHub publication back into GitHub Actions.
• Do not inline release API logic back into workflows.
• If you change release asset selection, keep idempotent delete-and-reupload behavior.
• If you change FreeBSD packaging, keep generating a real pkg-style archive with manifest metadata instead of a generic tarball renamed to .pkg.

When uncertain, preserve the current guarantees and extend the env surface instead of rewriting the scripts.