Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions .github/workflows/conventional-commits.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Same pinned Conventional Commits validator used by LibreSign.
name: Conventional commits
on:
pull_request:
types: [opened, edited, ready_for_review, reopened, synchronize]

permissions:
contents: read

jobs:
validate:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Validate squash merge title
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: node scripts/plan-desktop-release.mjs --validate-title "$PR_TITLE"
- uses: webiny/action-conventional-commits@7f91b1595ca1951cdb671ddc9f07a49081ec5b69 # v1.4.2
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
114 changes: 90 additions & 24 deletions .github/workflows/desktop-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,55 @@ on:
- 'composer.*'
- 'README.md'
push:
branches:
- main
tags:
- 'v*'
workflow_dispatch:
inputs:
release_tag:
description: 'Existing tag to rebuild and publish; leave empty for preview.'
required: false
type: string

permissions:
contents: read

concurrency:
group: desktop-installers-${{ github.ref }}
group: desktop-installers-${{ github.event_name == 'pull_request' && github.ref || 'release-serialization' }}
cancel-in-progress: false

jobs:
plan:
name: Determine release from Conventional Commits
runs-on: ubuntu-24.04
timeout-minutes: 10
outputs:
publish: ${{ steps.plan.outputs.publish }}
version: ${{ steps.plan.outputs.version }}
tag: ${{ steps.plan.outputs.tag }}
base_sha: ${{ steps.plan.outputs.base_sha }}
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
ref: ${{ inputs.release_tag || github.sha }}
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Plan release or preview
id: plan
env:
RELEASE_TAG_INPUT: ${{ inputs.release_tag || '' }}
run: node scripts/plan-desktop-release.mjs --github-output

packages:
needs: plan
if: >-
needs.plan.outputs.publish == 'true' ||
github.event_name == 'pull_request' ||
github.event_name == 'workflow_dispatch'
name: ${{ matrix.target }} / ${{ matrix.arch }}
runs-on: ${{ matrix.runner }}
timeout-minutes: 80
Expand All @@ -48,20 +84,22 @@ jobs:
env:
CI: 'true'
NODE_ENV: 'development'
NATIVEPHP_APP_VERSION: ${{ needs.plan.outputs.version }}
CSC_IDENTITY_AUTO_DISCOVERY: 'false'
# No signing credentials are available to untrusted pull requests.
CSC_LINK: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_CSC_LINK || '' }}
CSC_KEY_PASSWORD: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_CSC_KEY_PASSWORD || '' }}
NATIVEPHP_APPLE_ID: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_APPLE_ID || '' }}
NATIVEPHP_APPLE_ID_PASS: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_APPLE_ID_PASS || '' }}
NATIVEPHP_APPLE_TEAM_ID: ${{ github.ref_type == 'tag' && matrix.target == 'mac' && secrets.MAC_APPLE_TEAM_ID || '' }}
WIN_CSC_LINK: ${{ github.ref_type == 'tag' && matrix.target == 'win' && secrets.WIN_CSC_LINK || '' }}
WIN_CSC_KEY_PASSWORD: ${{ github.ref_type == 'tag' && matrix.target == 'win' && secrets.WIN_CSC_KEY_PASSWORD || '' }}
CSC_LINK: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_CSC_LINK || '' }}
CSC_KEY_PASSWORD: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_CSC_KEY_PASSWORD || '' }}
NATIVEPHP_APPLE_ID: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_APPLE_ID || '' }}
NATIVEPHP_APPLE_ID_PASS: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_APPLE_ID_PASS || '' }}
NATIVEPHP_APPLE_TEAM_ID: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'mac' && secrets.MAC_APPLE_TEAM_ID || '' }}
WIN_CSC_LINK: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'win' && secrets.WIN_CSC_LINK || '' }}
WIN_CSC_KEY_PASSWORD: ${{ (needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request') && matrix.target == 'win' && secrets.WIN_CSC_KEY_PASSWORD || '' }}

steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
ref: ${{ inputs.release_tag || github.sha }}
- uses: shivammathur/setup-php@v2
with:
php-version: '8.4'
Expand All @@ -73,12 +111,19 @@ jobs:
node-version: '22'
cache: npm
cache-dependency-path: nativephp/electron/package-lock.json
- name: Resolve and validate desktop version
- name: Stamp planned version into the packaging workspace
shell: bash
run: node scripts/desktop-version.mjs --github-env
env:
RELEASE_VERSION: ${{ needs.plan.outputs.version }}
run: |
set -euo pipefail
if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then
(cd nativephp/electron && npm version "$RELEASE_VERSION" --no-git-tag-version --ignore-scripts --allow-same-version)
fi
node scripts/desktop-version.mjs --github-env
- name: Test versioning and release preparation without publishing
shell: bash
run: node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs
run: node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs scripts/plan-desktop-release.test.mjs scripts/finalize-desktop-release.test.mjs
- name: Install PHP dependencies
shell: bash
run: |
Expand Down Expand Up @@ -164,15 +209,17 @@ jobs:
retention-days: 7

publish:
if: startsWith(github.ref, 'refs/tags/v')
needs: packages
if: needs.plan.outputs.publish == 'true' && github.event_name != 'pull_request'
needs: [plan, packages]
runs-on: ubuntu-24.04
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
persist-credentials: true
fetch-depth: 0
ref: ${{ inputs.release_tag || github.sha }}
- uses: actions/setup-node@v4
with:
node-version: '22'
Expand All @@ -181,23 +228,42 @@ jobs:
pattern: installer-*
path: release-output
merge-multiple: true
- name: Stamp and validate release version
shell: bash
env:
RELEASE_VERSION: ${{ needs.plan.outputs.version }}
run: |
set -euo pipefail
if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then
(cd nativephp/electron && npm version "$RELEASE_VERSION" --no-git-tag-version --ignore-scripts --allow-same-version)
fi
node scripts/desktop-version.mjs
- name: Prepare and test release assets
shell: bash
run: node scripts/prepare-desktop-release.mjs release-output "$GITHUB_REF_NAME"
- name: Publish public desktop release
env:
RELEASE_TAG: ${{ needs.plan.outputs.tag }}
run: node scripts/prepare-desktop-release.mjs release-output "$RELEASE_TAG"
- name: Prepare release notes
shell: bash
env:
RELEASE_TAG: ${{ needs.plan.outputs.tag }}
BASE_SHA: ${{ needs.plan.outputs.base_sha }}
run: |
set -euo pipefail
cp .github/RELEASE_NOTES.md release-notes.md
if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then
node scripts/plan-desktop-release.mjs --notes "$BASE_SHA" "$GITHUB_SHA" "$RELEASE_TAG" > release-notes.md
fi
- name: Finalize versioned tag and publish verified assets
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GH_REPO: ${{ github.repository }}
RELEASE_TAG: ${{ needs.plan.outputs.tag }}
shell: bash
run: |
set -euo pipefail
mapfile -d '' files < <(find release-output -maxdepth 1 -type f -print0)
if [[ "$GITHUB_REF_NAME" == *-* ]]; then
gh release create "$GITHUB_REF_NAME" "${files[@]}" --target "$GITHUB_SHA" \
--title "Automatic Kimai $GITHUB_REF_NAME (prévia)" \
--prerelease --notes-file .github/RELEASE_NOTES.md
if [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then
node scripts/finalize-desktop-release.mjs release-output "$RELEASE_TAG" --main-source "$GITHUB_SHA"
else
gh release create "$GITHUB_REF_NAME" "${files[@]}" --target "$GITHUB_SHA" \
--title "Automatic Kimai $GITHUB_REF_NAME" \
--latest --notes-file .github/RELEASE_NOTES.md
node scripts/finalize-desktop-release.mjs release-output "$RELEASE_TAG"
fi
2 changes: 1 addition & 1 deletion .github/workflows/php-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ jobs:
- name: Check build dependency security and compatibility
run: node --test build/dependency-compat.test.mjs
- name: Test desktop update flow and metadata
run: node --test src/main/updates.test.mjs ../../scripts/create-update-manifests.test.mjs ../../scripts/desktop-version.test.mjs ../../scripts/prepare-desktop-release.test.mjs
run: node --test src/main/updates.test.mjs ../../scripts/create-update-manifests.test.mjs ../../scripts/desktop-version.test.mjs ../../scripts/prepare-desktop-release.test.mjs ../../scripts/plan-desktop-release.test.mjs ../../scripts/finalize-desktop-release.test.mjs
- name: Validate canonical desktop version and lockfile
run: node ../../scripts/desktop-version.mjs
- name: Compile NativePHP Electron plugin (required for #plugin import)
Expand Down
65 changes: 42 additions & 23 deletions docs/DISTRIBUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,23 @@ project at the repository root; NativePHP/Electron lives under
- macOS Intel x64 → `.dmg`
- macOS Apple Silicon arm64 → `.dmg`

The workflow runs on PRs affecting packaging and on signed release tags
matching the version in `nativephp/electron/package.json` (the single canonical
application version). npm maintains `package-lock.json`, which is checked for
consistency. CI resolves `NATIVEPHP_APP_VERSION` from this package; do not set
release versions in the workflow or PHP configuration. A tag triggers
GitHub release upload only after all four package jobs succeed and their
installer checks verify the files and embedded PHP runtime.
The workflow builds pull-request previews and evaluates each push to `main`
for a stable release based on Conventional Commits since the previous stable
tag. `fix:` and `perf:` mean PATCH, `feat:` means MINOR; the `!` marker
or a `BREAKING CHANGE:` footer means MAJOR. The highest increment wins.
`docs:`, `test:`, `chore:` and non-conventional commits alone do not
cause a release. A documentation-only merge skips installers entirely.

The version is calculated from Git history, not hardcoded in the workflow.
The release build updates `nativephp/electron/package.json` and its
npm-generated lockfile in the packaging workspace. After all four OS jobs
and package validation pass, it tags the exact sources with updated version
metadata. This version-only release commit is attached to the tag, **not**
merged into `main`; the application code remains identical to the merged
commit. Future release planning compares `main` against the previous
release tag or its main parent, preventing duplicate releases. The package
version is canonical for a checkout or installed release; no independent
manually managed version belongs in PHP or GitHub Actions.

PR builds produce temporary workflow artifacts only. A tag containing
a prerelease suffix is labeled **pre-release**; normal version tags are
Expand Down Expand Up @@ -87,19 +97,28 @@ Never describe a successful cross-platform *build* as a verified user installati

## Releasing

1. Set the intended version with `npm version <version> --no-git-tag-version`
inside `nativephp/electron/`; commit both npm metadata files together.
`node scripts/desktop-version.mjs` validates their consistency.
2. Run the release preparation tests without a release:
`node --test scripts/desktop-version.test.mjs scripts/create-update-manifests.test.mjs scripts/prepare-desktop-release.test.mjs`.
The preparation function can be exercised using fixture artifacts and
does not call GitHub or publish anything.
3. Merge the tested PR; create a tag corresponding to the package version.
Four package jobs produce six archives. A dedicated script
(`scripts/prepare-desktop-release.mjs`) checks every artifact, renames
installers, generates update manifests and SHA256 checksums. The short
workflow publishes these assets with `.github/RELEASE_NOTES.md`.
4. Verify the published installers, macOS archives, update manifests,
checksums and release notes. Configure signing/notarization and
homologate upgrade, rollback and encrypted settings on real devices.
Unsigned macOS releases must not advertise automatic installation.
1. Merge PRs with Conventional Commits into `main`. The desktop workflow
calculates a version from the last stable `vX.Y.Z` tag. Documentation-only
and test-only changes do not cause a release.
2. For releasable commits, the same run stamps the calculated version into
npm metadata and compiles Linux, Windows and macOS packages. All four
builds and tests must pass before assets can be published.
3. The publish job validates canonical assets, update manifests and checksums,
generates notes from relevant commits, pushes the release tag and uploads
all packages to a **draft** GitHub release. It publishes the draft only
once the uploads have completed.
4. Do not manually bump the package version or create stable tags during
ordinary merges. The publishing job needs repository `contents: write`.
Tags pushed by the default `GITHUB_TOKEN` will not trigger another run;
build and publication intentionally happen in the same workflow.
5. If a tag was pushed but publication failed, manually run
`.github/workflows/desktop-release.yml` using its `release_tag` input
to rebuild that exact version. Never force-update a release tag or delete
a published release to hide failed publication.
6. Validate installation, automatic upgrades, rollback and preservation
of encrypted settings on physical Windows, macOS and Linux devices.
Successful automated builds are not a substitute for this verification.

The tag source records the actual published package version; `main` does
not receive an automated version-only commit. Prerelease tags may still be
pushed manually when preparing a preview.
2 changes: 1 addition & 1 deletion scripts/desktop-version.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env node
// SPDX-License-Identifier: GPL-3.0-or-later
// The Electron package is the single manually maintained desktop version.
// The Electron package is the single version source; release builds stamp it automatically.
import { appendFileSync, readFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
Expand Down
Loading
Loading