Compare commits

..

1 Commits

Author SHA1 Message Date
gitea-actions[bot] 082c01fc46 chore(release): build 09.24.00-rc [skip ci] 2026-06-04 22:59:27 +00:00
11 changed files with 326 additions and 501 deletions
-49
View File
@@ -412,12 +412,6 @@ jobs:
if: always()
steps:
- name: Checkout
uses: actions/checkout@v4
with:
sparse-checkout: automation/ci-issue-reporter.sh
sparse-checkout-cone-mode: false
- name: Check gate results
run: |
{
@@ -443,46 +437,3 @@ jobs:
echo "::error::One or more CI gates failed"
exit 1
fi
- name: "File issues for failed gates"
if: >-
always() &&
(needs.code-quality.result == 'failure' ||
needs.tests.result == 'failure' ||
needs.self-health.result == 'failure' ||
needs.governance.result == 'failure' ||
needs.templates.result == 'failure')
env:
GITEA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
run: |
chmod +x automation/ci-issue-reporter.sh
REPORTER="./automation/ci-issue-reporter.sh"
WF="Platform CI"
report_gate() {
local gate="$1" result="$2" details="$3"
if [ "$result" = "failure" ]; then
"$REPORTER" --gate "$gate" --details "$details" --workflow "$WF" --severity error
fi
}
report_gate "Code Quality" \
"${{ needs.code-quality.result }}" \
"PHPCS (PSR-12), PHPStan, or PHP syntax checks failed. Run \`composer check\` locally to reproduce."
report_gate "Unit Tests" \
"${{ needs.tests.result }}" \
"PHPUnit tests failed on one or more PHP versions (8.1, 8.2, 8.3). Run \`vendor/bin/phpunit --testdox\` locally."
report_gate "Self-Health" \
"${{ needs.self-health.result }}" \
"Self-health score fell below the 80% threshold. Run \`php bin/moko health -- --path .\` locally."
report_gate "Governance" \
"${{ needs.governance.result }}" \
"Governance checks failed (license headers, secrets, or version consistency). Check the CI run summary for specifics."
report_gate "Template Integrity" \
"${{ needs.templates.result }}" \
"Workflow or gitignore templates failed YAML validation or are missing required entries."
+3 -7
View File
@@ -10,9 +10,11 @@ BRIEF: Release changelog
-->
# Changelog
## [Unreleased]
## [09.24.00] --- 2026-06-04
## [09.23] --- 2026-05-31
## [09.22] --- 2026-05-31
@@ -30,9 +32,3 @@ BRIEF: Release changelog
## [09.21] --- 2026-05-30
## [09.20] --- 2026-05-30
## [09.19] --- 2026-05-30
## [09.18] --- 2026-05-30
## [09.17] --- 2026-05-30
-237
View File
@@ -1,237 +0,0 @@
#!/usr/bin/env bash
# ============================================================================
# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# FILE INFORMATION
# DEFGROUP: Automation.CI
# INGROUP: moko-platform.Automation
# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
# PATH: /automation/ci-issue-reporter.sh
# VERSION: 09.23.00
# BRIEF: Creates or updates a Gitea issue when a CI gate fails.
# Deduplicates by searching open issues with the "ci-auto" label
# whose title matches the gate. If a matching issue exists, a comment
# is appended instead of opening a duplicate.
# ============================================================================
set -euo pipefail
# ── Defaults ────────────────────────────────────────────────────────────────
GITEA_URL="${GITEA_URL:-https://git.mokoconsulting.tech}"
GITEA_TOKEN="${GITEA_TOKEN:-}"
REPO="${GITHUB_REPOSITORY:-}"
RUN_URL="${GITHUB_SERVER_URL:-${GITEA_URL}}/${REPO}/actions/runs/${GITHUB_RUN_ID:-0}"
LABEL_NAME="ci-auto"
LABEL_COLOR="#e11d48"
GATE=""
DETAILS=""
SEVERITY="error"
WORKFLOW=""
# ── Parse arguments ─────────────────────────────────────────────────────────
usage() {
cat <<EOF
Usage: ci-issue-reporter.sh --gate NAME --details TEXT [OPTIONS]
Required:
--gate CI gate name (e.g. "Code Quality", "Self-Health")
--details Human-readable failure description
Optional:
--severity "error" (default) or "warning"
--workflow Workflow name for the issue title
--repo owner/repo (default: \$GITHUB_REPOSITORY)
--run-url URL to the CI run (auto-detected from env)
--token Gitea API token (default: \$GITEA_TOKEN)
--url Gitea base URL (default: \$GITEA_URL)
EOF
exit 1
}
while [[ $# -gt 0 ]]; do
case "$1" in
--gate) GATE="$2"; shift 2 ;;
--details) DETAILS="$2"; shift 2 ;;
--severity) SEVERITY="$2"; shift 2 ;;
--workflow) WORKFLOW="$2"; shift 2 ;;
--repo) REPO="$2"; shift 2 ;;
--run-url) RUN_URL="$2"; shift 2 ;;
--token) GITEA_TOKEN="$2"; shift 2 ;;
--url) GITEA_URL="$2"; shift 2 ;;
-h|--help) usage ;;
*) echo "Unknown option: $1"; usage ;;
esac
done
[[ -z "$GATE" ]] && { echo "ERROR: --gate is required"; usage; }
[[ -z "$DETAILS" ]] && { echo "ERROR: --details is required"; usage; }
[[ -z "$GITEA_TOKEN" ]] && { echo "ERROR: GITEA_TOKEN not set"; exit 1; }
[[ -z "$REPO" ]] && { echo "ERROR: GITHUB_REPOSITORY not set"; exit 1; }
API="${GITEA_URL}/api/v1/repos/${REPO}"
# ── Build title ─────────────────────────────────────────────────────────────
if [[ -n "$WORKFLOW" ]]; then
TITLE="[CI] ${WORKFLOW}: ${GATE} failed"
else
TITLE="[CI] ${GATE} failed"
fi
# ── Ensure label exists ─────────────────────────────────────────────────────
ensure_label() {
local exists
exists=$(curl -sf -o /dev/null -w '%{http_code}' \
-H "Authorization: token ${GITEA_TOKEN}" \
"${API}/labels" 2>/dev/null || echo "000")
if [[ "$exists" == "200" ]]; then
# Check if label already exists
local found
found=$(curl -sf \
-H "Authorization: token ${GITEA_TOKEN}" \
"${API}/labels" 2>/dev/null \
| grep -o "\"name\":\"${LABEL_NAME}\"" || true)
if [[ -z "$found" ]]; then
curl -sf -X POST \
-H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
"${API}/labels" \
-d "{\"name\":\"${LABEL_NAME}\",\"color\":\"${LABEL_COLOR}\",\"description\":\"Auto-created by CI issue reporter\"}" \
> /dev/null 2>&1 || true
fi
fi
}
# ── Search for existing open issue ──────────────────────────────────────────
find_existing_issue() {
# URL-encode the gate name for the query
local query
query=$(printf '%s' "[CI] ${GATE}" | sed 's/ /%20/g; s/\[/%5B/g; s/\]/%5D/g')
local response
response=$(curl -sf \
-H "Authorization: token ${GITEA_TOKEN}" \
"${API}/issues?type=issues&state=open&labels=${LABEL_NAME}&q=${query}&limit=5" \
2>/dev/null || echo "[]")
# Extract the first matching issue number
echo "$response" \
| grep -oP '"number":\s*\K[0-9]+' \
| head -1
}
# ── Build issue body ────────────────────────────────────────────────────────
build_body() {
local severity_badge
if [[ "$SEVERITY" == "error" ]]; then
severity_badge="**Severity:** Error"
else
severity_badge="**Severity:** Warning"
fi
cat <<BODY
## CI Gate Failure: ${GATE}
${severity_badge}
**Workflow:** ${WORKFLOW:-unknown}
**Branch:** ${GITHUB_REF_NAME:-unknown}
**Commit:** \`${GITHUB_SHA:0:8}\`
**Run:** [View CI run](${RUN_URL})
### Details
${DETAILS}
### Resolution
Fix the issue described above and push a new commit. This issue will be closed automatically when the gate passes, or can be closed manually.
---
*Auto-created by [ci-issue-reporter](${GITEA_URL}/${REPO}/src/branch/main/automation/ci-issue-reporter.sh)*
BODY
}
# ── Build comment body (for existing issues) ────────────────────────────────
build_comment() {
cat <<COMMENT
### CI failure recurrence
**Branch:** ${GITHUB_REF_NAME:-unknown}
**Commit:** \`${GITHUB_SHA:0:8}\`
**Run:** [View CI run](${RUN_URL})
${DETAILS}
COMMENT
}
# ── Main ────────────────────────────────────────────────────────────────────
ensure_label
EXISTING=$(find_existing_issue)
if [[ -n "$EXISTING" ]]; then
# Append comment to existing issue
COMMENT_BODY=$(build_comment)
COMMENT_JSON=$(printf '%s' "$COMMENT_BODY" | python3 -c "
import sys, json
print(json.dumps({'body': sys.stdin.read()}))" 2>/dev/null)
HTTP=$(curl -sf -o /dev/null -w '%{http_code}' -X POST \
-H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
"${API}/issues/${EXISTING}/comments" \
-d "${COMMENT_JSON}" 2>/dev/null || echo "000")
if [[ "$HTTP" == "201" ]]; then
echo "Commented on existing issue #${EXISTING}"
else
echo "WARNING: Failed to comment on issue #${EXISTING} (HTTP ${HTTP})"
fi
else
# Create new issue
ISSUE_BODY=$(build_body)
ISSUE_JSON=$(python3 -c "
import sys, json
body = sys.stdin.read()
print(json.dumps({
'title': sys.argv[1],
'body': body,
'labels': []
}))" "$TITLE" <<< "$ISSUE_BODY" 2>/dev/null)
# Create the issue
RESPONSE=$(curl -sf -X POST \
-H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
"${API}/issues" \
-d "${ISSUE_JSON}" 2>/dev/null || echo "{}")
ISSUE_NUM=$(echo "$RESPONSE" | grep -oP '"number":\s*\K[0-9]+' | head -1)
if [[ -n "$ISSUE_NUM" ]]; then
# Apply label (separate call — more reliable across Gitea versions)
LABEL_ID=$(curl -sf \
-H "Authorization: token ${GITEA_TOKEN}" \
"${API}/labels" 2>/dev/null \
| grep -oP "\"id\":\s*\K[0-9]+(?=[^}]*\"name\":\s*\"${LABEL_NAME}\")" \
| head -1 || true)
if [[ -n "$LABEL_ID" ]]; then
curl -sf -X POST \
-H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
"${API}/issues/${ISSUE_NUM}/labels" \
-d "{\"labels\":[${LABEL_ID}]}" \
> /dev/null 2>&1 || true
fi
echo "Created issue #${ISSUE_NUM}: ${TITLE}"
else
echo "WARNING: Failed to create issue"
echo "Response: ${RESPONSE}"
fi
fi
+1 -2
View File
@@ -230,8 +230,7 @@ class PushFiles extends CliFramework
{
// Read platform from repo's .mokogitea/manifest.xml via API
try {
$fileInfo = $this->adapter->getFileContents($org, $repo, '.mokogitea/manifest.xml', 'main');
$manifestData = isset($fileInfo['content']) ? base64_decode($fileInfo['content']) : '';
$manifestData = $this->adapter->getFileContent($org, $repo, '.mokogitea/manifest.xml', 'main');
if (!empty($manifestData)) {
$xml = @simplexml_load_string($manifestData);
if ($xml !== false) {
+1 -20
View File
@@ -230,31 +230,12 @@ class ReleasePackageCli extends CliFramework
$subName = basename($pkgDir);
$subZipPath = "{$outputDir}/{$subName}.zip";
// If sub-package is a full repo checkout (e.g. git submodule),
// look for a src/ subdirectory containing a Joomla manifest XML
// and zip that instead of the repo root.
$subSourceDir = $pkgDir;
$srcCandidate = "{$pkgDir}/src";
if (is_dir($srcCandidate)) {
$srcManifests = array_merge(
glob("{$srcCandidate}/*.xml") ?: [],
glob("{$srcCandidate}/pkg_*.xml") ?: []
);
foreach ($srcManifests as $mf) {
if (strpos(file_get_contents($mf) ?: '', '<extension') !== false) {
$subSourceDir = $srcCandidate;
echo " Sub-package {$subName}: using src/ entry-point\n";
break;
}
}
}
$subZip = new \ZipArchive();
if ($subZip->open($subZipPath, \ZipArchive::CREATE | \ZipArchive::OVERWRITE) !== true) {
$this->log('ERROR', "Failed to create sub-package ZIP: {$subZipPath}");
continue;
}
$this->addDirToZip($subZip, $subSourceDir, '', $this->excludePatterns);
$this->addDirToZip($subZip, $pkgDir, '', $this->excludePatterns);
$subZip->close();
$zip->addFile($subZipPath, "packages/{$subName}.zip");
+3 -11
View File
@@ -109,18 +109,10 @@ class VersionAutoBumpCli extends CliFramework
echo "{$line}\n";
}
// Step 2: Read version (--quiet suppresses banner so only the version is output)
// Step 2: Read version
$versionOutput = [];
exec("{$php} {$cli}/version_read.php --path " . escapeshellarg($path) . " --quiet 2>&1", $versionOutput, $versionRc);
// Take the last non-empty line — the version is always the final output
$version = '';
foreach (array_reverse($versionOutput) as $line) {
$line = trim($line);
if (preg_match('/^\d{2}\.\d{2}\.\d{2}/', $line)) {
$version = $line;
break;
}
}
exec("{$php} {$cli}/version_read.php --path " . escapeshellarg($path) . " 2>&1", $versionOutput, $versionRc);
$version = trim($versionOutput[0] ?? '');
if (empty($version)) {
echo "No version found — skipping\n";
-6
View File
@@ -53,12 +53,6 @@ class VersionSetPlatformCli extends CliFramework
// Strip any existing suffix(es) before applying the correct one
$version = preg_replace('/(-(dev|alpha|beta|rc))+$/', '', $version);
// Validate version format — must be XX.YY.ZZ to prevent XML corruption
if (!preg_match('/^\d{2}\.\d{2}\.\d{2}$/', $version)) {
$this->log('ERROR', "Invalid version format: '{$version}' — expected XX.YY.ZZ");
return 1;
}
// Append stability suffix for non-stable releases
$stabilitySuffixMap = [
'stable' => '',
+47 -63
View File
@@ -141,26 +141,6 @@ abstract class CliFramework
/** @var float Script start time for elapsed-time reporting. */
private float $startTime;
// =========================================================================
// Display output — all decorative output goes to stderr
// =========================================================================
/**
* Write decorative/diagnostic output to stderr.
*
* All non-data output (banners, progress bars, section headers, status
* lines, log messages) MUST use this method so that stdout is reserved
* for machine-readable data. This ensures that shell captures like
* VERSION=$(php version_read.php --path .)
* only receive the actual data, not decorative text.
*
* @since 04.00.16
*/
protected function display(string $text): void
{
fwrite(STDERR, $text);
}
// =========================================================================
// Constructor
// =========================================================================
@@ -346,14 +326,14 @@ abstract class CliFramework
protected function printHelp(): void
{
$w = $this->termWidth();
$this->display($this->c(self::C_BOLD . self::C_CYAN, $this->scriptName));
echo $this->c(self::C_BOLD . self::C_CYAN, $this->scriptName);
if ($this->description !== '') {
$this->display(' — ' . $this->description);
echo ' — ' . $this->description;
}
$this->display("\n");
$this->display($this->c(self::C_DIM, str_repeat(self::BOX_H, $w)) . "\n\n");
$this->display($this->c(self::C_BOLD, 'Usage:') . " php {$this->scriptName}.php [options]\n\n");
$this->display($this->c(self::C_BOLD, 'Options:') . "\n");
echo "\n";
echo $this->c(self::C_DIM, str_repeat(self::BOX_H, $w)) . "\n\n";
echo $this->c(self::C_BOLD, 'Usage:') . " php {$this->scriptName}.php [options]\n\n";
echo $this->c(self::C_BOLD, 'Options:') . "\n";
$builtIn = [
'--help' => ['desc' => 'Show this help message', 'default' => null],
@@ -368,16 +348,16 @@ abstract class CliFramework
$hint = ($default !== null && $default !== false)
? $this->c(self::C_DIM, " (default: {$default})")
: '';
$this->display(sprintf(
printf(
" %s%-22s%s%s%s\n",
self::C_CYAN,
$name,
self::C_RESET,
$def['desc'],
$hint
));
);
}
$this->display("\n");
echo "\n";
}
// =========================================================================
@@ -398,23 +378,23 @@ abstract class CliFramework
$titleLine = $this->padRight($titleStyled, $inner, strlen($titleRaw));
$descLine = ($desc !== '') ? $this->padRight(" {$desc}", $inner) : null;
$this->display("\n");
$this->display($this->c(
echo "\n";
echo $this->c(
self::C_CYAN,
self::BOX_TL . str_repeat(self::BOX_H, $inner) . self::BOX_TR
) . "\n");
$this->display($this->c(self::C_CYAN, self::BOX_V)
) . "\n";
echo $this->c(self::C_CYAN, self::BOX_V)
. $this->c(self::C_BOLD, $titleLine)
. $this->c(self::C_CYAN, self::BOX_V) . "\n");
. $this->c(self::C_CYAN, self::BOX_V) . "\n";
if ($descLine !== null) {
$this->display($this->c(self::C_CYAN, self::BOX_V)
echo $this->c(self::C_CYAN, self::BOX_V)
. $this->c(self::C_DIM, $descLine)
. $this->c(self::C_CYAN, self::BOX_V) . "\n");
. $this->c(self::C_CYAN, self::BOX_V) . "\n";
}
$this->display($this->c(
echo $this->c(
self::C_CYAN,
self::BOX_BL . str_repeat(self::BOX_H, $inner) . self::BOX_BR
) . "\n\n");
) . "\n\n";
}
/** Print the dry-run notice box. */
@@ -423,18 +403,18 @@ abstract class CliFramework
$w = min($this->termWidth(), 70);
$msg = ' ' . self::ICON_DRY . ' DRY-RUN MODE — no changes will be written ';
$row = $this->padRight($msg, $w - 2);
$this->display($this->c(
echo $this->c(
self::C_YELLOW . self::C_BOLD,
self::BOX_TL . str_repeat(self::BOX_H, $w - 2) . self::BOX_TR
) . "\n");
$this->display($this->c(
) . "\n";
echo $this->c(
self::C_YELLOW . self::C_BOLD,
self::BOX_V . $row . self::BOX_V
) . "\n");
$this->display($this->c(
) . "\n";
echo $this->c(
self::C_YELLOW . self::C_BOLD,
self::BOX_BL . str_repeat(self::BOX_H, $w - 2) . self::BOX_BR
) . "\n\n");
) . "\n\n";
}
// =========================================================================
@@ -455,11 +435,11 @@ abstract class CliFramework
$w = $this->termWidth();
$text = " {$title} ";
$fill = max(0, $w - strlen($text) - 4);
$this->display("\n");
$this->display($this->c(
echo "\n";
echo $this->c(
self::C_CYAN,
str_repeat(self::BOX_H, 2) . $text . str_repeat(self::BOX_H, $fill)
) . "\n\n");
) . "\n\n";
}
/** Print a plain horizontal divider. */
@@ -469,7 +449,7 @@ abstract class CliFramework
return;
}
$this->clearProgress();
$this->display($this->c(self::C_DIM, str_repeat(self::BOX_H, $this->termWidth())) . "\n");
echo $this->c(self::C_DIM, str_repeat(self::BOX_H, $this->termWidth())) . "\n";
}
// =========================================================================
@@ -515,7 +495,11 @@ abstract class CliFramework
$line = "{$ts} {$icon} {$badge} {$text}\n";
$this->display($line);
if ($level === 'ERROR') {
fwrite(STDERR, $line);
} else {
echo $line;
}
}
/** Log a success message. */
@@ -580,7 +564,7 @@ abstract class CliFramework
? ' ' . $this->c(self::C_DIM, "{$detail}")
: '';
$this->display(' ' . $this->c($color . self::C_BOLD, $icon) . ' ' . $label . $suffix . "\n");
echo ' ' . $this->c($color . self::C_BOLD, $icon) . ' ' . $label . $suffix . "\n";
}
// =========================================================================
@@ -617,10 +601,10 @@ abstract class CliFramework
$line = " [{$bar}] {$percent} {$counter}{$suffix}";
if ($newline) {
$this->display("\r{$line}\n");
echo "\r{$line}\n";
$this->progressActive = false;
} else {
$this->display("\r{$line}");
echo "\r{$line}";
$this->progressActive = true;
}
}
@@ -629,7 +613,7 @@ abstract class CliFramework
protected function clearProgress(): void
{
if ($this->progressActive) {
$this->display("\r" . str_repeat(' ', $this->termWidth()) . "\r");
echo "\r" . str_repeat(' ', $this->termWidth()) . "\r";
$this->progressActive = false;
}
}
@@ -660,8 +644,8 @@ abstract class CliFramework
$maxKey = max(array_map('strlen', array_keys($rows)));
$inner = $maxKey + 20;
$this->display("\n");
$this->display($this->c($color, self::BOX_TL . str_repeat(self::BOX_H, $inner) . self::BOX_TR) . "\n");
echo "\n";
echo $this->c($color, self::BOX_TL . str_repeat(self::BOX_H, $inner) . self::BOX_TR) . "\n";
foreach ($rows as $label => $value) {
$valStr = (string) $value;
@@ -669,10 +653,10 @@ abstract class CliFramework
$padding = $inner - strlen($label) - $valVis - 4;
$row = ' ' . $this->c(self::C_BOLD, $label)
. str_repeat(' ', max(1, $padding)) . $valStr . ' ';
$this->display($this->c($color, self::BOX_V) . $row . $this->c($color, self::BOX_V) . "\n");
echo $this->c($color, self::BOX_V) . $row . $this->c($color, self::BOX_V) . "\n";
}
$this->display($this->c($color, self::BOX_BL . str_repeat(self::BOX_H, $inner) . self::BOX_BR) . "\n\n");
echo $this->c($color, self::BOX_BL . str_repeat(self::BOX_H, $inner) . self::BOX_BR) . "\n\n";
}
/**
@@ -718,7 +702,7 @@ abstract class CliFramework
$this->clearProgress();
$badge = $this->c(self::C_BOLD . self::C_MAGENTA, "Step {$current}/{$total}");
$arrow = $this->c(self::C_DIM, self::ICON_INFO);
$this->display("\n{$badge} {$arrow} {$title}\n");
echo "\n{$badge} {$arrow} {$title}\n";
}
// =========================================================================
@@ -980,13 +964,13 @@ abstract class CliFramework
}
// Header.
$this->display($sep . "\n");
echo $sep . "\n";
$headerLine = '|';
foreach ($headers as $i => $h) {
$headerLine .= ' ' . $this->c(self::C_BOLD, str_pad($h, $widths[$i])) . ' |';
}
$this->display($headerLine . "\n");
$this->display($sep . "\n");
echo $headerLine . "\n";
echo $sep . "\n";
// Rows.
foreach ($rows as $row) {
@@ -994,9 +978,9 @@ abstract class CliFramework
foreach ($row as $i => $cell) {
$line .= ' ' . str_pad((string) $cell, $widths[$i]) . ' |';
}
$this->display($line . "\n");
echo $line . "\n";
}
$this->display($sep . "\n");
echo $sep . "\n";
}
}
@@ -1,56 +1,70 @@
# Update Server — Dolibarr Modules
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
## Overview
This file is part of a Moko Consulting project.
MokoGitea provides a built-in Update Server that can serve Dolibarr-compatible JSON update feeds from repository releases. **No static feed file is needed in the repository.**
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: {{REPO_NAME}}.Documentation
INGROUP: MokoPlatform.Templates
REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}
PATH: /docs/update-server.md
VERSION: {{standards_version}}
BRIEF: How this module's update server file (update.txt) is managed
-->
# Dolibarr Update Server
[![moko-platform](https://img.shields.io/badge/moko--platform-{{standards_version}}-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform)
This document explains how `update.txt` is automatically managed for this Dolibarr module.
## How It Works
1. **Enable Update Server** in the repository's Settings > Advanced Settings
2. **Configure metadata** in Settings > Update Server (set platform to `dolibarr`)
3. **Create releases** with tagged module archives
4. MokoGitea serves the update feed at `/{owner}/{repo}/updates/dolibarr.json`
Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline.
## Feed URL
### Automatic Generation
| Event | Workflow | `update.txt` Content | `$this->version` |
|-------|----------|---------------------|-------------------|
| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version |
| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` |
| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version |
### Module Descriptor
The `url_last_version` in your module descriptor should point to:
```
https://git.mokoconsulting.tech/{owner}/{repo}/updates/dolibarr.json
https://raw.githubusercontent.com/mokoconsulting-tech/{{REPO_NAME}}/main/update.txt
```
## Release Naming Convention
This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it.
Release assets should follow:
### Branch Lifecycle
```
{module_name}-{version}.zip
dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX
(development) (release candidate) (stable release) (frozen snapshot)
```
Examples:
- `mokocrm-18.0.1.zip`
- `mokodolisign-3.2.0.zip`
1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development`
2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC
3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch
4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed
## Update Server Settings
### Health Checks
Configure these in Settings > Update Server:
The `repo_health.yml` workflow verifies on every commit:
| Field | Description | Example |
|-------|-------------|---------|
| Platform | Set to `dolibarr` | `dolibarr` |
| Extension Name | Dolibarr module directory name | `mokocrm` |
| Display Name | Human-readable name | `Module - MokoCRM` |
| Extension Type | Usually `module` | `module` |
| Maintainer | Organization name | `Moko Consulting` |
| Support URL | Product support page | `https://mokoconsulting.tech/support/mokocrm` |
- `update.txt` exists in the repository root
- Module descriptor (`mod*.class.php`) exists in `src/core/modules/`
- `$this->numero` is set and non-zero
- `$this->version` is not hardcoded (should be set by workflow)
- `url_last_version` points to `update.txt` (not `update.json`)
- `url_last_version` references `/main/` branch on the main branch
## Download Gating
---
Same three modes as Joomla: `none`, `prerelease`, `all`.
## Status
Dolibarr Update Server support is currently **disabled for all modules except MokoCRM**. Metadata is pre-configured and ready to enable when needed.
## What NOT to Do
- **Do NOT commit static feed files to the repository**
- **Do NOT use legacy update check mechanisms** — use the built-in feed
*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.*
@@ -1,90 +1,122 @@
# Update Server — Joomla Extensions
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
## Overview
This file is part of a Moko Consulting project.
MokoGitea provides a built-in Update Server that dynamically generates Joomla-compatible update XML feeds from repository releases. **No static `updates.xml` file is needed in the repository.**
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: {{REPO_NAME}}.Documentation
INGROUP: MokoPlatform.Templates
REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}
PATH: /docs/update-server.md
VERSION: {{standards_version}}
BRIEF: How this extension's Joomla update server file (updates.xml) is managed
-->
# Joomla Update Server
[![moko-platform](https://img.shields.io/badge/moko--platform-{{standards_version}}-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform)
This document explains how `updates.xml` is automatically managed for this Joomla extension following the [Joomla Update Server specification](https://docs.joomla.org/Deploying_an_Update_Server).
## How It Works
1. **Enable Update Server** in the repository's Settings > Advanced Settings
2. **Configure metadata** in Settings > Update Server (extension name, type, target version, etc.)
3. **Create releases** with tagged assets (e.g. `pkg_mokowaas-02.19.00.zip`)
4. MokoGitea automatically serves the update feed at `/{owner}/{repo}/updates.xml`
Joomla checks for extension updates by fetching an XML file from the URL defined in the `<updateservers>` tag in the extension's XML manifest. moko-platform generates this file automatically.
## Feed URL
### Automatic Generation
```
https://git.mokoconsulting.tech/{owner}/{repo}/updates.xml
```
| Event | Workflow | `<tag>` | `<version>` |
|-------|----------|---------|-------------|
| Merge to `main` | `auto-release.yml` | `stable` | `XX.YY.ZZ` |
| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` |
| Push to `rc/**` | `deploy-dev.yml` | `rc` | `XX.YY.ZZ-rc` |
This URL is what goes into your Joomla extension's `update_server` element in the manifest XML.
## Manifest Configuration
In your extension's manifest XML (`*.xml`), add:
### Generated XML Structure
```xml
<updateservers>
<server type="extension" name="{Extension Name}">
https://git.mokoconsulting.tech/MokoConsulting/{RepoName}/updates.xml
</server>
</updateservers>
<?xml version="1.0" encoding="utf-8"?>
<updates>
<update>
<name>Extension Name</name>
<description>Extension Name update</description>
<element>com_extensionname</element>
<type>component</type>
<version>01.02.03</version>
<client>site</client>
<folder>system</folder> <!-- plugins only -->
<tags>
<tag>stable</tag>
</tags>
<downloads>
<downloadurl type="full" format="zip">https://git.mokoconsulting.tech/.../releases/download/v01.02.03/com_ext-01.02.03.zip</downloadurl>
<downloadurl type="full" format="zip">https://github.com/.../releases/download/v01.02.03/com_ext-01.02.03.zip</downloadurl>
</downloads>
<targetplatform name="joomla" version="((5\.[0-9])|(6\.[0-9]))" />
<php_minimum>8.2</php_minimum> <!-- if present in manifest -->
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
</update>
</updates>
```
## Release Naming Convention
### Metadata Source
Release assets must follow this naming pattern for the feed generator to detect them:
All metadata is extracted from the extension's XML manifest (`src/*.xml`) at build time:
```
{extension_name}-{version}.zip
{extension_name}-{version}.tar.gz
| XML Element | Source | Notes |
|-------------|--------|-------|
| `<name>` | `<name>` in manifest | Extension display name |
| `<element>` | `<element>` in manifest | Must match installed extension identifier |
| `<type>` | `type` attribute on `<extension>` | `component`, `module`, `plugin`, `library`, `package`, `template` |
| `<client>` | `client` attribute on `<extension>` | `site` or `administrator`**required for plugins and modules** |
| `<folder>` | `group` attribute on `<extension>` | Plugin group (e.g., `system`, `content`) — **required for plugins** |
| `<targetplatform>` | `<targetplatform>` in manifest | Falls back to Joomla 5.x / 6.x if not specified |
| `<php_minimum>` | `<php_minimum>` in manifest | Included only if present |
### Extension Manifest Setup
Your XML manifest must include an `<updateservers>` tag pointing to the `updates.xml` on the `main` branch:
```xml
<extension type="component" client="site" method="upgrade">
<name>My Extension</name>
<element>com_myextension</element>
<!-- ... -->
<updateservers>
<server type="extension" priority="1" name="My Extension Update Server (Gitea)">
https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}/raw/branch/main/updates.xml
</server>
<server type="extension" priority="2" name="My Extension Update Server (GitHub)">
https://raw.githubusercontent.com/mokoconsulting-tech/{{REPO_NAME}}/main/updates.xml
</server>
</updateservers>
</extension>
```
Examples:
- `pkg_mokowaas-02.19.00.zip`
- `tpl_mokoonyx-02.19.00.zip`
- `mod_mokojoomhero-01.05.00.zip`
## Update Server Settings
Configure these in Settings > Update Server:
| Field | Description | Example |
|-------|-------------|---------|
| Extension Name | Joomla element name | `pkg_mokowaas` |
| Display Name | Human-readable name | `Package - MokoWaaS` |
| Extension Type | package, plugin, template, module, component | `package` |
| Target Version | Regex for compatible Joomla versions | `(5|6)\..*` |
| PHP Minimum | Minimum PHP version | `8.1` |
| Maintainer | Organization name | `Moko Consulting` |
| Maintainer URL | Organization website | `https://mokoconsulting.tech` |
| Support URL | Product support page | `https://mokoconsulting.tech/products/{alias}` |
| Info URL | Product information page | `https://mokoconsulting.tech/products/{alias}` |
## Download Gating
Three modes control who can download release assets:
| Mode | Behavior |
|------|----------|
| `none` | All downloads are public |
| `prerelease` | Pre-release downloads require a license key; stable releases are public |
| `all` | All downloads require a license key |
The update feed XML is **always public** — only the actual file downloads are gated.
## What NOT to Do
- **Do NOT commit `updates.xml` to the repository** — it is served dynamically
- **Do NOT use static update server workflows** — the old CI-generated approach is deprecated
- **Do NOT hardcode version numbers in feed URLs** — the feed auto-detects from releases
## Changelog Feed
A changelog XML is also served automatically at:
### Branch Lifecycle
```
https://git.mokoconsulting.tech/{owner}/{repo}/changelog.xml
dev/XX.YY.ZZ → rc/XX.YY.ZZ → main → version/XX
(development) (rc) (stable) (frozen snapshot)
```
This is generated from release notes (markdown body of each release).
1. **Development** (`dev/**`): `updates.xml` with `<tag>development</tag>`, download points to branch archive
2. **Release Candidate** (`rc/**`): `updates.xml` with `<tag>rc</tag>`, version set to `XX.YY.ZZ-rc`
3. **Stable Release** (merge to `main`): `updates.xml` with `<tag>stable</tag>`, download points to Gitea Release asset (primary) + GitHub Release asset (mirror)
4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed
### Health Checks
The `repo_health.yml` workflow verifies on every commit:
- `updates.xml` exists in the repository root
- XML manifest exists with `<extension>` tag
- `<version>`, `<name>`, `<author>`, `<namespace>` tags present
- Extension `type` attribute is valid
- Language `.ini` files exist
- `index.html` directory listing protection in `src/`, `src/admin/`, `src/site/`
---
*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.*
+119
View File
@@ -0,0 +1,119 @@
<?xml version='1.0' encoding='UTF-8'?>
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
VERSION: {{VERSION}}
-->
<updates>
<!-- 1. DEVELOPMENT -->
<update>
<name>{{EXTENSION_NAME}}</name>
<description>{{EXTENSION_NAME}} development build — unstable.</description>
<element>{{EXTENSION_ELEMENT}}</element>
<type>{{EXTENSION_TYPE}}</type>
<folder>{{EXTENSION_FOLDER}}</folder>
<client>{{EXTENSION_CLIENT}}</client>
<version>{{VERSION}}</version>
<creationDate>{{DATE}}</creationDate>
<infourl title='{{EXTENSION_NAME}} Dev'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/development</infourl>
<downloads>
<downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/development/{{EXTENSION_ELEMENT}}-{{VERSION}}-dev.zip</downloadurl>
</downloads>
<sha256></sha256>
<tags><tag>development</tag></tags>
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
<targetplatform name='joomla' version='(5|6).*'/>
<php_minimum>8.1</php_minimum>
</update>
<!-- 2. ALPHA -->
<update>
<name>{{EXTENSION_NAME}}</name>
<description>{{EXTENSION_NAME}} alpha build — early testing.</description>
<element>{{EXTENSION_ELEMENT}}</element>
<type>{{EXTENSION_TYPE}}</type>
<folder>{{EXTENSION_FOLDER}}</folder>
<client>{{EXTENSION_CLIENT}}</client>
<version>{{VERSION}}</version>
<creationDate>{{DATE}}</creationDate>
<infourl title='{{EXTENSION_NAME}} Alpha'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/alpha</infourl>
<downloads>
<downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/alpha/{{EXTENSION_ELEMENT}}-{{VERSION}}-alpha.zip</downloadurl>
</downloads>
<sha256></sha256>
<tags><tag>alpha</tag></tags>
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
<targetplatform name='joomla' version='(5|6).*'/>
<php_minimum>8.1</php_minimum>
</update>
<!-- 3. BETA -->
<update>
<name>{{EXTENSION_NAME}}</name>
<description>{{EXTENSION_NAME}} beta build — feature complete, stability testing.</description>
<element>{{EXTENSION_ELEMENT}}</element>
<type>{{EXTENSION_TYPE}}</type>
<folder>{{EXTENSION_FOLDER}}</folder>
<client>{{EXTENSION_CLIENT}}</client>
<version>{{VERSION}}</version>
<creationDate>{{DATE}}</creationDate>
<infourl title='{{EXTENSION_NAME}} Beta'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/beta</infourl>
<downloads>
<downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/beta/{{EXTENSION_ELEMENT}}-{{VERSION}}-beta.zip</downloadurl>
</downloads>
<sha256></sha256>
<tags><tag>beta</tag></tags>
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
<targetplatform name='joomla' version='(5|6).*'/>
<php_minimum>8.1</php_minimum>
</update>
<!-- 4. RC -->
<update>
<name>{{EXTENSION_NAME}}</name>
<description>{{EXTENSION_NAME}} release candidate — testing only.</description>
<element>{{EXTENSION_ELEMENT}}</element>
<type>{{EXTENSION_TYPE}}</type>
<folder>{{EXTENSION_FOLDER}}</folder>
<client>{{EXTENSION_CLIENT}}</client>
<version>{{VERSION}}</version>
<creationDate>{{DATE}}</creationDate>
<infourl title='{{EXTENSION_NAME}} RC'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/release-candidate</infourl>
<downloads>
<downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/release-candidate/{{EXTENSION_ELEMENT}}-{{VERSION}}-rc.zip</downloadurl>
</downloads>
<sha256></sha256>
<tags><tag>rc</tag></tags>
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
<targetplatform name='joomla' version='(5|6).*'/>
<php_minimum>8.1</php_minimum>
</update>
<!-- 5. STABLE -->
<update>
<name>{{EXTENSION_NAME}}</name>
<description>{{EXTENSION_NAME}} — Moko Consulting Joomla extension.</description>
<element>{{EXTENSION_ELEMENT}}</element>
<type>{{EXTENSION_TYPE}}</type>
<folder>{{EXTENSION_FOLDER}}</folder>
<client>{{EXTENSION_CLIENT}}</client>
<version>{{VERSION}}</version>
<creationDate>{{DATE}}</creationDate>
<infourl title='{{EXTENSION_NAME}}'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/stable</infourl>
<downloads>
<downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/stable/{{EXTENSION_ELEMENT}}-{{VERSION}}.zip</downloadurl>
</downloads>
<sha256></sha256>
<tags><tag>stable</tag></tags>
<maintainer>Moko Consulting</maintainer>
<maintainerurl>https://mokoconsulting.tech</maintainerurl>
<targetplatform name='joomla' version='(5|6).*'/>
<php_minimum>8.1</php_minimum>
</update>
</updates>