ivuorinen/actions
1
0
Fork 0
mirror of https://github.com/ivuorinen/actions.git synced 2026-03-01 09:53:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: local references, release workflow (#301)

Browse Source 
* fix: local references, release workflow

* chore: apply cr comments
This commit is contained in:
Ismo Vuorinen
2025-10-23 23:24:20 +03:00
committed by GitHub
parent 020a8fd26c
commit 6ebc5a21d5
51 changed files with 1604 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
.serena/memories/code_style_conventions.md
View File

@@ -22,17 +22,19 @@
- Unquoted variables cause word splitting and globbing
- Example: `"$variable"` not `$variable`, `basename -- "$path"` not `basename $path`
6. **ALWAYS** use local paths (`./action-name`) for intra-repo actions
- Avoids external dependencies and version drift
- Pattern: `uses: ./common-cache` not `uses: ivuorinen/actions/common-cache@main`
6. **ALWAYS** use SHA-pinned references for internal actions in action.yml
- Security: immutable, auditable, portable when used externally
- Pattern: `uses: ivuorinen/actions/common-cache@7061aafd35a2f21b57653e34f2b634b2a19334a9`
- Test workflows use local: `uses: ./common-cache` (within repo only)
7. **ALWAYS** test regex patterns against edge cases
- Include prerelease tags (`1.0.0-rc.1`), build metadata (`1.0.0+build.123`)
- Version validation should support full semver/calver formats
8. **ALWAYS** use `set -euo pipefail` at script start
- `-e`: Exit on error, `-u`: Exit on undefined variable, `-o pipefail`: Exit on pipe failures
- Critical for fail-fast behavior in composite actions
8. **ALWAYS** use POSIX shell (`set -eu`) for all scripts
- Maximum portability: works on Alpine, busybox, all shells
- Use `#!/bin/sh` not `#!/usr/bin/env bash`
- Use `set -eu` not `set -euo pipefail` (pipefail not POSIX)
9. **Avoid** nesting `${{ }}` expressions inside quoted strings in specific contexts
- In `hashFiles()`: `"${{ inputs.value }}"` breaks cache key generation - use unquoted or extract to variable
@@ -92,42 +94,71 @@ Comprehensive linting with 30+ rule categories including:
**Example**: `# ruff: noqa: T201, S603` for action step scripts only
## Shell Script Standards
## Shell Script Standards (POSIX)
### Required Hardening Checklist
**ALL scripts use POSIX shell** (`#!/bin/sh`) for maximum portability.
- ✅ **Shebang**: `#!/usr/bin/env bash` (POSIX-compliant)
- ✅ **Error Handling**: `set -euo pipefail` at script start
- ✅ **Safe IFS**: `IFS=$' \t\n'` (space, tab, newline only)
- ✅ **Exit Trap**: `trap cleanup EXIT` for cleanup operations
- ✅ **Error Trap**: `trap 'echo "Error at line $LINENO" >&2' ERR` for debugging
### Required POSIX Compliance Checklist
- ✅ **Shebang**: `#!/bin/sh` (POSIX-compliant, not bash)
- ✅ **Error Handling**: `set -eu` at script start (no pipefail - not POSIX)
- ✅ **Defensive Expansion**: Use `${var:-default}` or `${var:?message}` patterns
- ✅ **Quote Everything**: Always quote expansions: `"$var"`, `basename -- "$path"`
- ✅ **Tool Availability**: `command -v tool >/dev/null 2>&1 || { echo "Missing tool"; exit 1; }`
- ✅ **Portable Output**: Use `printf` instead of `echo -e`
- ✅ **Portable Sourcing**: Use `. file` instead of `source file`
- ✅ **POSIX Tests**: Use `[ ]` instead of `[[ ]]`
- ✅ **Parsing**: Use `cut`, `grep`, pipes instead of here-strings `<<<`
- ✅ **No Associative Arrays**: Use temp files or line-based processing
### Key POSIX Differences from Bash
| Bash Feature | POSIX Replacement |
| --------------------- | --------------------------------- |
| `#!/usr/bin/env bash` | `#!/bin/sh` |
| `set -euo pipefail` | `set -eu` |
| `[[ condition ]]` | `[ condition ]` |
| `[[ $var =~ regex ]]` | `echo "$var" \| grep -qE 'regex'` |
| `<<<` here-strings | `echo \| cut` or pipes |
| `source file` | `. file` |
| `$BASH_SOURCE` | `$0` |
| `((var++))` | `var=$((var + 1))` |
| `((var < 10))` | `[ "$var" -lt 10 ]` |
| `echo -e` | `printf '%b'` |
| `declare -A map` | temp files + sort/uniq |
| Process substitution | pipes or temp files |
### Examples
```bash
#!/usr/bin/env bash
set -euo pipefail
IFS=$' \t\n'
# Cleanup trap
cleanup() { rm -f /tmp/tempfile; }
trap cleanup EXIT
# Error trap with line number
trap 'echo "Error at line $LINENO" >&2' ERR
```sh
#!/bin/sh
set -eu
# Defensive parameter expansion
config_file="${CONFIG_FILE:-config.yml}" # Use default if unset
required_param="${REQUIRED_PARAM:?Missing value}" # Error if unset
required_param="${REQUIRED_PARAM:?Missing value}" # Error if unset
# Always quote expansions
echo "Processing: $config_file"
printf 'Processing: %s\n' "$config_file"
result=$(basename -- "$file_path")
# POSIX test conditions
if [ -f "$config_file" ]; then
printf 'Found config\n'
fi
# Portable output
printf '%b' "Color: ${GREEN}text${NC}\n"
```
### Why POSIX Shell
- **Portability**: Works on Alpine Linux, busybox, minimal containers, all POSIX shells
- **Performance**: POSIX shells are lighter and faster than bash
- **CI-Friendly**: Minimal dependencies, works everywhere
- **Standards**: Follows POSIX best practices
- **Compatibility**: Works with sh, dash, ash, bash, zsh
### Additional Requirements
- **Security**: All external actions SHA-pinned
@@ -189,48 +220,49 @@ if: github.event_name == 'push'
- Don't quote in `with:`, `env:`, `if:` - GitHub evaluates these
- Never nest expressions: `"${{ inputs.value }}"` inside hashFiles breaks caching
### **Local Action References**
### Internal Action References (SHA-Pinned)
**CRITICAL**: When referencing actions within the same repository:
**CRITICAL**: Action files (`*/action.yml`) use SHA-pinned references for security:
- ✅ **CORRECT**: `uses: ./action-name` (relative to workspace root)
- ❌ **INCORRECT**: `uses: ../action-name` (relative paths that assume directory structure)
- ❌ **INCORRECT**: `uses: owner/repo/action-name@main` (floating branch reference)
- ✅ **CORRECT**: `uses: ivuorinen/actions/action-name@7061aafd35a2f21b57653e34f2b634b2a19334a9`
- ❌ **INCORRECT**: `uses: ./action-name` (security risk, not portable when used externally)
- ❌ **INCORRECT**: `uses: ivuorinen/actions/action-name@main` (floating reference)
**Rationale**:
- Uses GitHub workspace root (`$GITHUB_WORKSPACE`) as reference point
- Clear and unambiguous regardless of where action is called from
- Follows GitHub's recommended pattern for same-repository references
- Avoids issues if action checks out repository to different location
- Eliminates external dependencies and supply chain risks
- **Security**: Immutable, auditable references
- **Reproducibility**: Exact version control
- **Portability**: Works when actions used externally (e.g., `ivuorinen/f2b` using `ivuorinen/actions/pr-lint`)
- **Prevention**: No accidental version drift
**Examples**:
**Test Workflows Exception**:
Test workflows in `_tests/` use local references since they run within the repo:
```yaml
# ✅ Correct - relative to workspace root
- uses: ./validate-inputs
- uses: ./common-cache
- uses: ./node-setup
# ❌ Incorrect - relative directory navigation
- uses: ../validate-inputs
- uses: ../common-cache
- uses: ../node-setup
# ❌ Incorrect - external reference to same repo
- uses: ivuorinen/actions/validate-inputs@main
- uses: ivuorinen/actions/common-cache@v1
# ✅ Test workflows only
uses: ./validate-inputs
```
### **Step Output References**
### External Action References (SHA-Pinned)
```yaml
# ✅ Correct - SHA-pinned
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
# ❌ Incorrect - floating reference
uses: actions/checkout@main
uses: actions/checkout@v4
```
### Step Output References
**CRITICAL**: Steps must have `id:` to reference their outputs:
```yaml
# ❌ INCORRECT - missing id
- name: Detect Version
uses: ./version-detect
uses: ivuorinen/actions/version-detect@<SHA>
- name: Setup
with:
@@ -239,7 +271,7 @@ if: github.event_name == 'push'
# ✅ CORRECT - id present
- name: Detect Version
id: detect-version # Required for output reference
uses: ./version-detect
uses: ivuorinen/actions/version-detect@<SHA>
- name: Setup
with:
@@ -250,7 +282,7 @@ if: github.event_name == 'push'
- **No Secrets**: Never commit secrets or keys to repository
- **No Logging**: Never expose or log secrets/keys in code
- **SHA Pinning**: All external actions use SHA commits, not tags
- **SHA Pinning**: All action references (internal + external) use SHA commits, not tags
- **Input Validation**: All actions import from shared validation library (`validate-inputs/`) - stateless validation functions, no inter-action dependencies
- **Output Sanitization**: Use `printf` or heredoc for `$GITHUB_OUTPUT` writes
- **Injection Prevention**: Validate inputs for command injection patterns (`;`, `&&`, `|`, backticks)
@@ -276,6 +308,7 @@ if: github.event_name == 'push'
- **Convention-Based**: Automatic rule generation based on input naming patterns
- **Error Handling**: Comprehensive error messages and proper exit codes
- **Defensive Programming**: Check tool availability, validate inputs, handle edge cases
- **POSIX Compliance**: All scripts portable across POSIX shells
## Pre-commit and Security Configuration

104
.serena/memories/development_standards.md
View File

@@ -44,6 +44,17 @@ make generate-tests # Create missing tests
make generate-tests-dry # Preview test generation
```
### Version Management
```bash
make release [VERSION=vYYYY.MM.DD] # Create new release (auto-generates version from date if omitted)
make update-version-refs MAJOR=vYYYY # Update refs to version
make bump-major-version OLD=vYYYY NEW=vYYYY # Annual bump
make check-version-refs # Verify current refs
```
See `versioning_system` memory for complete details.
## Code Style
### EditorConfig (BLOCKING ERRORS)
@@ -55,18 +66,36 @@ make generate-tests-dry # Preview test generation
- **Final Newline**: Required
- **Trailing Whitespace**: Trimmed
### Shell Scripts (REQUIRED)
### Shell Scripts (POSIX REQUIRED)
**ALL scripts use POSIX shell** (`#!/bin/sh`) for maximum portability:
```bash
#!/usr/bin/env bash
set -euo pipefail # MANDATORY
IFS=$' \t\n'
trap cleanup EXIT
trap 'echo "Error at line $LINENO" >&2' ERR
# Always quote: "$variable", basename -- "$path"
#!/bin/sh
set -eu # MANDATORY (no pipefail - not POSIX)
# Quote everything: "$variable", basename -- "$path"
# Check tools: command -v jq >/dev/null 2>&1
# Use printf instead of echo -e for portability
```
**Why POSIX:**
- Works on Alpine Linux, busybox, minimal containers
- Faster than bash
- Maximum compatibility (sh, dash, ash, bash, zsh)
- CI-friendly, minimal dependencies
**Key Differences from Bash:**
- Use `#!/bin/sh` not `#!/usr/bin/env bash`
- Use `set -eu` not `set -euo pipefail` (pipefail not POSIX)
- Use `[ ]` not `[[ ]]`
- Use `printf` not `echo -e`
- Use `. file` not `source file`
- Use `cut`/`grep` for parsing, not here-strings `<<<`
- Use temp files instead of associative arrays
- Use `$0` not `$BASH_SOURCE`
### Python (Ruff)
- **Line Length**: 100 chars
@@ -78,15 +107,68 @@ trap 'echo "Error at line $LINENO" >&2' ERR
### YAML/Actions
- **Indent**: 2 spaces
- **Local Actions**: `uses: ./action-name` (never `../` or `@main`)
- **Internal Actions (action.yml)**: `ivuorinen/actions/action-name@<SHA>` (SHA-pinned, security)
- **Test Workflows**: `./action-name` (local reference, runs within repo)
- **Internal Workflows**: `./action-name` (local reference for sync-labels.yml etc)
- **External Actions**: SHA-pinned (not `@main`/`@v1`)
- **Step IDs**: Required when outputs referenced
- **Permissions**: Minimal scope (contents: read default)
- **Output Sanitization**: Use `printf`, never `echo` for `$GITHUB_OUTPUT`
## Versioning System
### Internal References (SHA-Pinned)
All `*/action.yml` files use SHA-pinned references for security and reproducibility:
```yaml
uses: ivuorinen/actions/validate-inputs@7061aafd35a2f21b57653e34f2b634b2a19334a9
```
**Why SHA-pinned internally:**
- Security: immutable, auditable references
- Reproducibility: exact version control
- Portability: works when actions used externally
- Prevention: no accidental version drift
### Test Workflows (Local References)
Test workflows in `_tests/` use local references:
```yaml
uses: ./validate-inputs
```
**Why local in tests:** Tests run within the repo, faster, simpler
### External User References
Users reference with version tags:
```yaml
uses: ivuorinen/actions/validate-inputs@v2025
```
### Version Format (CalVer)
- Major: `v2025` (year)
- Minor: `v2025.10` (year.month)
- Patch: `v2025.10.18` (year.month.day)
All three tags point to the same commit SHA.
### Creating Releases
```bash
make release # Auto-generates vYYYY.MM.DD from today's date
make release VERSION=v2025.10.18 # Specific version
git push origin main --tags --force-with-lease
```
## Security Requirements
1. **SHA Pinning**: All external actions use commit SHAs
1. **SHA Pinning**: All action references use commit SHAs (not moving tags)
2. **Token Safety**: `${{ github.token }}`, never hardcoded
3. **Input Validation**: All inputs validated via centralized system
4. **Output Sanitization**: `printf '%s\n' "$value" >> $GITHUB_OUTPUT`
@@ -104,9 +186,13 @@ trap 'echo "Error at line $LINENO" >&2' ERR
- Never skip testing after changes
- Never create files unless absolutely necessary
- Never nest `${{ }}` in quoted YAML strings (breaks hashFiles)
- Never use `@main` for internal action references (use SHA-pinned)
- Never use bash-specific features (scripts must be POSIX sh)
## Preferred Patterns
- POSIX shell for all scripts (not bash)
- SHA-pinned internal action references (security)
- Edit existing files over creating new ones
- Use centralized validation for all input handling
- Follow existing conventions in codebase

219
.serena/memories/versioning_system.md Normal file
View File

@@ -0,0 +1,219 @@
# Version System Architecture
## Overview
This repository uses a CalVer-based SHA-pinned versioning system for all internal action references.
## Version Format
### CalVer: vYYYY.MM.DD
- **Major**: `v2025` (year, updated annually)
- **Minor**: `v2025.10` (year.month)
- **Patch**: `v2025.10.18` (year.month.day)
Example: Release `v2025.10.18` creates three tags pointing to the same commit:
- `v2025.10.18` (patch - specific release)
- `v2025.10` (minor - latest October 2025 release)
- `v2025` (major - latest 2025 release)
## Internal vs External References
### Internal (action.yml files)
- **Format**: `ivuorinen/actions/validate-inputs@<40-char-SHA>`
- **Purpose**: Security, reproducibility, precise control
- **Example**: `ivuorinen/actions/validate-inputs@7061aafd35a2f21b57653e34f2b634b2a19334a9`
### External (user consumption)
- **Format**: `ivuorinen/actions/validate-inputs@v2025`
- **Purpose**: Convenience, always gets latest release
- **Options**: `@v2025`, `@v2025.10`, or `@v2025.10.18`
### Test Workflows
- **Format**: `uses: ./action-name` (local reference)
- **Location**: `_tests/integration/workflows/*.yml`
- **Reason**: Tests run within the actions repo context
### Internal Workflows
- **Format**: `uses: ./sync-labels` (local reference)
- **Location**: `.github/workflows/sync-labels.yml`
- **Reason**: Runs within the actions repo, local is sufficient
## Release Process
### Creating a Release
```bash
# 1. Create release with version tags
make release VERSION=v2025.10.18
# This automatically:
# - Updates all action.yml SHA refs to current HEAD
# - Commits the changes
# - Creates tags: v2025.10.18, v2025.10, v2025
# - All tags point to the same commit SHA
# 2. Push to remote
git push origin main --tags --force-with-lease
```
### After Each Release
Tags are force-pushed to ensure `v2025` and `v2025.10` always point to latest:
```bash
git push origin v2025 --force
git push origin v2025.10 --force
git push origin v2025.10.18
```
Or use `--tags --force-with-lease` to push all at once.
## Makefile Targets
### `make release VERSION=v2025.10.18`
Creates new release with version tags and updates all action references.
### `make update-version-refs MAJOR=v2025`
Updates all action.yml files to reference the SHA of the specified major version tag.
### `make bump-major-version OLD=v2025 NEW=v2026`
Annual version bump - replaces all references from one major version to another.
### `make check-version-refs`
Lists all current SHA-pinned references grouped by SHA. Useful for verification.
## Helper Scripts (\_tools/)
### release.sh
Main release script - validates version, updates refs, creates tags.
### validate-version.sh
Validates CalVer format (vYYYY.MM.DD, vYYYY.MM, vYYYY).
### update-action-refs.sh
Updates all action references to a specific SHA or version tag.
### bump-major-version.sh
Handles annual version bumps with commit creation.
### check-version-refs.sh
Displays current SHA-pinned references with tag information.
### get-action-sha.sh
Retrieves SHA for a specific version tag.
## Action Versioning Action
**Location**: `action-versioning/action.yml`
Automatically checks if major version tag has moved and updates all action references.
**Usage in CI**:
```yaml
- uses: ./action-versioning
with:
major-version: v2025
```
**Outputs**:
- `updated`: true/false
- `commit-sha`: SHA of created commit (if any)
- `needs-annual-bump`: true/false (year mismatch)
## CI Workflow
**File**: `.github/workflows/version-maintenance.yml`
**Triggers**:
- Weekly (Monday 9 AM UTC)
- Manual (workflow_dispatch)
**Actions**:
1. Checks if `v2025` tag has moved
2. Updates action references if needed
3. Creates PR with changes
4. Creates issue if annual bump needed
## Annual Version Bump
**When**: Start of each new year
**Process**:
```bash
# 1. Create new major version tag
git tag -a v2026 -m "Major version v2026"
git push origin v2026
# 2. Bump all references
make bump-major-version OLD=v2025 NEW=v2026
# 3. Update documentation
make docs
# 4. Push changes
git push origin main
```
## Verification
### Check Current Refs
```bash
make check-version-refs
```
### Verify All Refs Match
All action references should point to the same SHA after a release.
### Test External Usage
Create a test repo and use:
```yaml
uses: ivuorinen/actions/pr-lint@v2025
```
## Migration from @main
All action.yml files have been migrated from:
- `uses: ./action-name`
- `uses: ivuorinen/actions/action-name@main`
To:
- `uses: ivuorinen/actions/action-name@<SHA>`
Test workflows still use `./action-name` for local testing.
## Security Considerations
**SHA Pinning**: Prevents supply chain attacks by ensuring exact commit is used.
**Version Tags**: Provide user-friendly references while maintaining security internally.
**Tag Verification**: Always verify tags point to expected commits before force-pushing.
**Annual Review**: Each year requires conscious version bump, preventing accidental drift.