GitHub Actions Shared Workflows

Centralized reusable GitHub Actions workflows and composite actions for the Lerian organization.

How it works

Your repository workflow
         ↓
Reusable workflow (.github/workflows/*.yml)   ← orchestrates jobs
         ↓
Composite action  (src/<capability>/<name>/)  ← encapsulates steps

Workflows are called via workflow_call. Consumers pin a tier channel — @tier-0, @tier-1 or @tier-2 — never a version and never @main. The tier a repository pins is its declaration of how fast it wants to receive; releases reach it when that tier is promoted. See Tier channels.

All YAML files in this repository use the .yml extension — never .yaml.

Available workflows

See the docs/ directory for the full list, inputs, outputs, and usage examples for each workflow.

Quick Start

jobs:
  security:
    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/pr-security-scan.yml@tier-1

  release:
    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/release.yml@tier-1

  gitops:
    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/gitops-update.yml@tier-1

Versioning

Releases follow Semantic Versioning via semantic-release:

• Merges to develop → beta pre-release (v1.2.3-beta.1)
• Merges to main → stable release (v1.2.3)

Repository Routines

This repository runs a consolidated weekly routine (.github/workflows/self-routine.yml) that keeps issues, pull requests, branches, labels, and workflow runs tidy. All scheduled jobs run in a single workflow run on Mondays at 03:00 UTC.

Schedule

Trigger	When	What it runs
schedule	Mondays 03:00 UTC	Branch cleanup, stale PRs, stale issues, labels sync, workflow runs cleanup
pull_request: closed	On every PR merge	Delete the merged feature branch
push to main (.github/labels.yml)	On label config change	Sync labels to the repo
workflow_dispatch	Manual	Run any single routine or all of them, with a dry_run toggle

Jobs

Branch cleanup (branch_cleanup_stale)

Deletes branches with no commits for 20 days. Protected patterns (main, master, develop, release/*, hotfix/*, tier-*) are never touched. A separate job (branch_cleanup_merged) deletes feature branches the moment a PR is merged.

Stale PRs (stale_pr)

• A PR with no activity for 20 days receives a comment and the stale label.
• After 7 more days of inactivity, it is closed with a closing comment.
• Any new activity (commit, comment, edit) removes the stale label and resets the clock.
• Exempt labels: no-stale, security, work-in-progress, pinned. Drafts are also exempt.

Stale issues (stale_issue)

• An issue with no activity for 30 days receives a comment and the stale label.
• After 7 more days of inactivity, it is closed.
• Exempt labels: no-stale, security, pinned.

Labels sync (labels_sync)

Reconciles the repository's labels against .github/labels.yml. Also fires immediately when that file changes on main.

Workflow runs cleanup (workflow_runs_cleanup)

Deletes old workflow runs from the Actions tab to keep history navigable. Two guards must both be satisfied for a run to be deleted:

• The run is older than 45 days (retention_days).
• After deletion, the workflow still has at least 10 runs retained (keep_minimum_runs).

The minimum-runs floor protects rarely-triggered workflows (e.g. release backmerges) from having their entire history wiped. By default all workflows, all conclusions (success, failure, cancelled), and all states (active, disabled) are eligible — adjust via delete_workflow_pattern, delete_run_by_conclusion_pattern, and delete_workflow_by_state_pattern if you call the reusable workflow directly.

Effective windows

Because the cron runs weekly, items pass through the windows with up to one cron cycle of jitter. The 7-day close window aligns with the cron cadence so items are reliably picked up on the next run.

Item	Threshold	Effective time to close (best / worst)
PR	20 stale + 7 close	27 / 34 days
Issue	30 stale + 7 close	37 / 44 days
Branch	20 days inactivity	20 / 27 days

Manual runs and dry_run

# Actions → Self — Repository Routines → Run workflow
# Pick a routine and toggle dry_run (default: true)
routine: stale-pr | stale-issue | branch-cleanup-stale | labels-sync | workflow-runs-cleanup | all
dry_run: true | false

In dry_run: true mode no labels, comments, branches, or runs are touched — the per-item log under "actions/stale per-item log" shows exactly what would happen on a real run.

Opting out

Add the no-stale label to any issue or PR you want to keep open indefinitely. The routine skips it on every scan.

AI Assistant Support

Built-in guidance for AI assistants is included so they understand the architecture before making changes.

The rules live in .agents/skills/, one directory per skill, in the format agents read directly:

Skill	Covers
workflow	Reusable workflow architecture, runners, dry_run, secrets
composite	Composite action layout, action.yml, README and label checklists
refactor	The protocol for changing an existing workflow or composite
gha	All three at once

In Claude Code, invoke one by name:

claude
> /workflow    # reusable workflow rules
> /composite   # composite action rules
> /gha         # everything at once

Example:

claude
> /gha
> Add a helm-deploy composite under src/deploy/ and wire it into release.yml

Contributing

Read CONTRIBUTING.md for branch strategy, commit conventions, and the PR process.

Security

Report vulnerabilities privately — see SECURITY.md. Do not open public issues.

License

Apache License 2.0 — see LICENSE.