Skip to content

Fix auto-detection of latest package version #245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stracker-phil wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Fix auto-detection of latest package version #245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a273478
Exclude non-version tags from release detection
stracker-phil May 6, 2026
8bee325
Extract version tags with optional "v" prefix
stracker-phil May 6, 2026
df04f73
Prefer GH release API for latest release
stracker-phil May 6, 2026
37fbc05
Remove fallback logic for LATEST_RELEASE lookup
stracker-phil May 13, 2026
1304d5c
Document change in LATEST_RELEASE detection
stracker-phil May 21, 2026
057b338
Document semver requirement and format samples
stracker-phil May 21, 2026
77b623e
Lint the updated Markdown file
stracker-phil May 21, 2026
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
2 changes: 1 addition & 1 deletion .github/workflows/build-and-distribute.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ jobs:
GITHUB_TOKEN: ${{ secrets.GITHUB_USER_SSH_KEY }}
run: |
# Fetch latest public release
LATEST_RELEASE=$(git for-each-ref --sort=-creatordate --count=1 --format='%(refname:short)' refs/tags || echo "")
LATEST_RELEASE=$(gh release list --limit 1 --json tagName --jq '.[0].tagName' || echo "")

if [ -z "$LATEST_RELEASE" ]; then
echo "No releases found, using default version 0.0.0."
Expand Down
61 changes: 45 additions & 16 deletions docs/build-and-distribute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,10 @@ This approach keeps source code separate from build artifacts while maintaining

If no `PACKAGE_VERSION` is provided, the workflow automatically:

1. Fetches the latest tag from the repository
1. Fetches the latest GitHub Release from the repository
2. Strips the `dev/` prefix from the branch name and normalizes it to be semver-compatible
3. Creates a pre-release version like `1.2.3-main` or `2.0.0-abc-123`
4. Falls back to `0.0.0-{branch}` if no tags exist
4. Falls back to `0.0.0-{branch}` if no published release exists

**Examples:**

Expand All @@ -42,6 +42,36 @@ If no `PACKAGE_VERSION` is provided, the workflow automatically:

This ensures every build has a unique, meaningful version identifier that traces back to both the base release and the source branch.

### GitHub Release tag format

The latest GitHub Release tag is used as the base for `PACKAGE_VERSION` and is validated by `npm version` against semver. Release tags must therefore exactly match this pattern:

```
[v]MAJOR.MINOR.PATCH[-IDENTIFIER]
```

<details>
<summary>Valid and invalid samples</summary>

**Valid:**

- `1.2.3`
- `v1.2.3`
- `1.2.3-alpha`
- `1.2.3-feature.1`
- `1.2.3-2026-05-21`

**Invalid:**

- `1.2` → missing PATCH
- `1.2.3.4` → too many segments
- `1.2.3-` → empty identifier
- `v.1.2.3` → dot after `v`
- `a.b.c` → non-numeric segments
- `release/1.2.3` → contains a slash

</details>

## Simple usage example

### WordPress Plugin/Theme or PHP Library
Expand Down Expand Up @@ -111,20 +141,19 @@ jobs:

### Inputs

| Name | Default | Description |
|-----------------------|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| `NODE_OPTIONS` | `''` | Space-separated list of command-line Node options |
| `NODE_VERSION` | `18` | Node version with which the assets will be compiled |
| `NPM_REGISTRY_DOMAIN` | `'https://npm.pkg.github.com/'` | Domain of the private npm registry |
| `PHP_VERSION` | `'8.2'` | PHP version with which the PHP tools are to be executed |
| `PHP_EXTENSIONS` | `''` | PHP extensions supported by shivammathur/setup-php to be installed or disabled |
| `PHP_TOOLS` | `''` | PHP tools supported by shivammathur/setup-php to be installed |
| `COMPOSER_ARGS` | `'--no-dev --prefer-dist --optimize-autoloader'` | Set of arguments passed to Composer when gathering production dependencies |
| `PACKAGE_NAME` | `''` | The name of the package (falls back to the repository name) |
| `PACKAGE_VERSION` | `''` | The new package version. If not provided, will use latest tag version with branch name as pre-release identifier |
| `PRE_SCRIPT` | `''` | Run custom shell code before creating the release archive |
| `BUILT_BRANCH_NAME` | `''` | Override the automatic build branch naming (defaults to stripping `dev/` prefix from origin branch) |

| Name | Default | Description |
|-----------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `NODE_OPTIONS` | `''` | Space-separated list of command-line Node options |
| `NODE_VERSION` | `18` | Node version with which the assets will be compiled |
| `NPM_REGISTRY_DOMAIN` | `'https://npm.pkg.github.com/'` | Domain of the private npm registry |
| `PHP_VERSION` | `'8.2'` | PHP version with which the PHP tools are to be executed |
| `PHP_EXTENSIONS` | `''` | PHP extensions supported by shivammathur/setup-php to be installed or disabled |
| `PHP_TOOLS` | `''` | PHP tools supported by shivammathur/setup-php to be installed |
| `COMPOSER_ARGS` | `'--no-dev --prefer-dist --optimize-autoloader'` | Set of arguments passed to Composer when gathering production dependencies |
| `PACKAGE_NAME` | `''` | The name of the package (falls back to the repository name) |
| `PACKAGE_VERSION` | `''` | The new package version. If not provided, will use the latest GitHub Release version with branch name as pre-release identifier |
| `PRE_SCRIPT` | `''` | Run custom shell code before creating the release archive |
| `BUILT_BRANCH_NAME` | `''` | Override the automatic build branch naming (defaults to stripping `dev/` prefix from origin branch) |

#### A note on `BUILT_BRANCH_NAME`

Expand Down
Loading