shared-workflows/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This repository contains reusable Gitea Actions workflows for Unbound Software repositories. These workflows are called from other repositories using Gitea's `workflow_call` trigger.

## Architecture

- **Location**: Workflows are stored in `.gitea/workflows/` (not `.github/workflows/`)
- **Platform**: Gitea Actions (compatible with GitHub Actions syntax but runs on Gitea)
- **Runner**: Uses `ubuntu-latest` runner directly (no containers)
- **git-cliff**: Downloaded as binary from GitHub releases, version controlled via `GIT_CLIFF_VERSION` env var

### Release.yml Workflow

The main workflow automates semantic versioning releases using git-cliff for changelog generation:

1. **preconditions**: Validates release token exists at `/runner-secrets/release-token`
2. **changelog**: Generates changelog, determines version bump, checks for changes
3. **handle-pr**: Creates/updates a `next-release` branch and PR with CHANGELOG.md and .version
4. **prepare-release**: Prepares release artifacts when triggered
5. **create-release** or **create-tag**: Creates Gitea release or tag based on `tag_only` input

Version tracking uses a `.version` JSON file containing `{"version":"vX.Y.Z"}`.

## Development Notes

- No build/test commands exist - this is a workflow-only repository
- Workflows use Gitea API directly via curl (not gh CLI)
- Authentication reads from file-based token at `/runner-secrets/release-token`