ci-workflows/readme.md

CI Workflows Repository

Dit repository bevat centrale CI/CD workflows voor gebruik met Gitea Actions + runners.
Het doel is om build-, release- en deploylogica één keer te definiëren en vervolgens herbruikbaar te maken voor meerdere repositories.

De workflows in dit repo worden gebruikt via reusable workflows (workflow_call), zodat individuele projecten alleen nog een dunne “wrapper”-workflow nodig hebben.

---

📦 Wat zit er in dit repository?

Momenteel bevat dit repo onder andere:

• WP Plugin Build & Release workflow
  • Leest de pluginversie uit de plugin header
  • Genereert automatisch manifest.json
  • Bouwt een distributie-zip
  • Maakt (indien nodig) een Gitea release
  • Uploadt het zip-bestand als release asset
  • Slaat releases over als de tag al bestaat

De workflows zijn ontworpen om:

• versie-gebaseerd te werken (vX.Y.Z)
• veilig herbruikbaar te zijn
• zonder repo-specifieke aannames te functioneren

---

🧠 Architectuur

Waarom centraal?

• Geen copy-paste CI meer
• Eén plek om fixes en verbeteringen door te voeren
• Consistente releasestructuur
• Minder onderhoud per project

Hoe?

• Dit repo bevat de logica
• Consumer repos bepalen:
  • wanneer een workflow draait (on: push, workflow_dispatch, paths)
  • welke parameters worden doorgegeven (slug, main file, release notes)

---

🔁 Gebruik in andere repositories

1. Voorwaarden

De consumer repo moet:

• Gitea Actions ingeschakeld hebben
• Toegang hebben tot dit repo
• Een RELEASE_TOKEN secret bevatten met repo-rechten

Optioneel kunnen repo-variables gebruikt worden:

• RELEASE_SERVER_URL
• RELEASE_REPOSITORY

---

2. Voorbeeld: WordPress plugin release

In de consumer repo:

.gitea/workflows/release.yml

name: Build & Release Plugin

on:
  workflow_dispatch:
    inputs:
      release_notes:
        description: "Optionele release-opmerkingen"
        required: false
  push:
    branches: [ main ]
    paths:
      - 'plugin-main-file.php'
      - 'includes/**'
      - 'assets/**'
      - 'README.md'

jobs:
  release:
    uses: org/ci-workflows/.gitea/workflows/wp-plugin-release.yml@v1
    with:
      main_file: plugin-main-file.php
      slug: my-plugin-slug
      release_body: "${{ inputs.release_notes }}"
    secrets:
      RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}

De volledige build- en releaseflow wordt hiermee centraal uitgevoerd.

---

🔧 Beschikbare inputs (WP Plugin workflow)

Input	Verplicht	Beschrijving
main_file	✅	Pad naar het hoofd pluginbestand met Version: header
slug	✅	Plugin slug / mapnaam in de zip
release_title	❌	Titel van de release
release_body	❌	Release notes (bijv. via workflow_dispatch)

---

🔐 Secrets & rechten

Vereist

• RELEASE_TOKEN
  Gitea API token met repo-rechten

Optioneel (repo variables)

• RELEASE_SERVER_URL
  Voor self-hosted Gitea (override van server URL)
• RELEASE_REPOSITORY
  Override voor owner/repository

---

🏷️ Versiebeheer van workflows

Gebruik tags in dit repository:

• v1 → stabiele major versie
• v1.0.1 → bugfix / non-breaking wijziging
• v2 → breaking changes

Consumer repositories moeten altijd pinnen op een tag of commit SHA:

uses: org/ci-workflows/.gitea/workflows/wp-plugin-release.yml@v1
Dit voorkomt onverwachte regressies bij wijzigingen in centrale CI-logica.

---

🧪 Ontwikkelen & testen van workflows

Aanpak voor wijzigingen in dit CI-repository:

1. Maak een feature branch in dit repository
2. Pas de workflow(s) aan
3. Test de wijzigingen via een aparte test-repository
4. Merge de branch naar main
5. Tag een nieuwe versie (vX.Y.Z)

Breaking change?
→ verhoog altijd de major versie (v2, v3, …)

---

🚫 Wat hoort niet in dit repository?

Dit repository bevat uitsluitend generieke CI/CD-logica.

Niet opnemen:

• Project- of plugin-specifieke bestandsnamen
• Hardcoded slugs, paden of repository-namen
• Triggers zoals on: push, paths of branch-namen
• Omgevingsspecifieke aannames of secrets

Alles wat per project verschilt hoort in de consumer workflow.

---

📌 Richtlijn

Consumer repositories bepalen wanneer een workflow draait.
Dit repository bepaalt hoe de workflow wordt uitgevoerd.

---

📄 Gebruik & scope

Intern CI/CD repository voor herbruikbare Gitea Actions workflows.
Bedoeld voor gebruik binnen de organisatie en gekoppelde projecten.

---