worldhopper/scripts

CI/CD Scripts

This directory contains scripts used by the Woodpecker CI pipeline and for local development.

version.sh

Extracts version information from git tags. Outputs two lines: a version name and a version code (for Android).

Usage

sh scripts/version.sh

Output (two lines):

1. Version name — X.Y.Z if the current commit is tagged vX.Y.Z, X.Y.Z-rc.N if tagged vX.Y.Z-rc.N, otherwise X.Y.Z-dev-<short sha> based on the latest version tag (or 0.0.0-dev-<sha> if no tags exist)
2. Version code — total git commit count (monotonically increasing integer required by Android)

Examples

Use in a Flutter build:

VERSION_NAME=$(sh scripts/version.sh | head -1)
VERSION_CODE=$(sh scripts/version.sh | tail -1)
flutter build apk --release --build-name="$VERSION_NAME" --build-number="$VERSION_CODE"

Quick check:

$ sh scripts/version.sh
1.2.3
42

Notes

• Uses /bin/sh for portability (works in Alpine CI images)
• Handles shallow clones by fetching tags if needed
• When no version tag exists, falls back to 0.0.0-dev-<sha>

generate-changelog.sh

Generates a formatted changelog from git history by grouping commits by type.

Usage

./scripts/generate-changelog.sh <tag> [output-file]

Arguments:

• tag (required): Git tag to generate changelog for (e.g., v1.0.0)
• output-file (optional): Output file path (default: CHANGELOG.md)

Environment Variables:

• CI_FORGE_URL: Base URL of git forge (used for comparison links)
• CI_REPO: Repository path (used for comparison links)

Examples

Generate changelog for a specific tag:

./scripts/generate-changelog.sh v1.0.0

Generate changelog with custom output file:

./scripts/generate-changelog.sh v1.2.3 release-notes.md

Test changelog generation locally:

# Create a test tag (don't push)
git tag v0.0.1-test

# Generate changelog
./scripts/generate-changelog.sh v0.0.1-test

# Review output
cat CHANGELOG.md

# Clean up test tag
git tag -d v0.0.1-test

Commit Format

The script recognizes conventional commit prefixes:

• feat: or feat(scope): → Features section
• fix: or fix(scope): → Bug Fixes section
• chore: or chore(scope): → Chores section
• refactor: or refactor(scope): → Refactoring section
• All other commits → Other Changes section

Output Format

The generated changelog includes:

• Release title
• Commits grouped by type with emoji headers
• Short commit hashes for reference
• Full changelog comparison link (when in CI)

Example output:

# Release v1.0.0

## ✨ Features
- add user authentication (abc1234)
- implement dark mode (def5678)

## 🐛 Bug Fixes
- fix crash on startup (ghi9012)

## 📝 Other Changes
- update README (jkl3456)

---
**Full Changelog**: https://forgejo.example.com/user/repo/compare/v0.9.0...v1.0.0

create-release.sh

Creates a Forgejo release using the tea CLI tool with changelog and APK attachment.

Usage

./scripts/create-release.sh <tag> <apk-file> <changelog-file>

Arguments:

• tag (required): Git tag for the release (e.g., v1.0.0)
• apk-file (required): Path to the APK file to attach as release asset
• changelog-file (required): Path to the changelog file to use as release notes

Required Environment Variables:

• FORGEJO_TOKEN: Personal access token with repo permissions
• CI_FORGE_URL: Base URL of Forgejo instance (e.g., https://forgejo.example.com)
• CI_REPO_OWNER: Repository owner/organization name
• CI_REPO_NAME: Repository name

Examples

Create a release (requires valid Forgejo credentials):

export FORGEJO_TOKEN="your-token-here"
export CI_FORGE_URL="https://forgejo.example.com"
export CI_REPO_OWNER="username"
export CI_REPO_NAME="worldhopper"

./scripts/create-release.sh v1.0.0 worldhopper-v1.0.0.apk CHANGELOG.md

Prerequisites

The tea CLI must be installed:

# Install tea CLI
# See: https://gitea.com/gitea/tea

# On macOS with Homebrew
brew install tea

# On Linux
wget https://dl.gitea.io/tea/latest/tea-linux-amd64
chmod +x tea-linux-amd64
sudo mv tea-linux-amd64 /usr/local/bin/tea

Output

The script will:

1. Configure tea with Forgejo credentials
2. Create a release with the specified tag (tags matching *-rc.* are marked as pre-releases)
3. Set the release title to "Worldhopper {TAG}"
4. Use the changelog file content as release description
5. Attach the APK file as a downloadable release asset
6. Print the release URL on success

CI/CD Integration

These scripts are used by .woodpecker.yml for automated releases. The pipeline:

1. Build Stage: Builds the Flutter APK
2. Changelog Stage: Runs generate-changelog.sh to create release notes
3. Release Stage: Runs create-release.sh to publish to Forgejo

See the root .woodpecker.yml file for the complete integration example.