Skip to content

About

Lerian's public reusable GitHub Actions workflows and composite actions, consumed through tier channels.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Lerian

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:
  helm-update:
    uses: LerianStudio/shared-workflows-public/.github/workflows/helm-update-chart.yml@tier-1

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

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

Runner variables

Runners are chosen only by organization variables, so moving CI to another runner type is a variable change, not a PR per repository. No workflow holds a literal label or reads a runner input. Step-by-step guide for a repository: Runner Variables — Agent Guide.

Job Resolves
With a job variable (test, lint, coverage, integration_test, build, security_scan, publish) vars.<JOB>_RUNNERS → vars.GENERAL_RUNNERS → vars.FALLBACK_RUNNERS
Light job with a job variable (gate, pr_checks_summary) vars.<JOB>_RUNNERS → vars.LIGHT_RUNNERS (private repositories only) → vars.GENERAL_RUNNERS → vars.FALLBACK_RUNNERS
Light job vars.LIGHT_RUNNERS (private repositories only) → vars.GENERAL_RUNNERS → vars.FALLBACK_RUNNERS
Every other job vars.GENERAL_RUNNERS → vars.FALLBACK_RUNNERS
GitOps (ArgoCD sync) vars.GITOPS_RUNNERS → vars.FALLBACK_RUNNERS

Light jobs are the ones that need little CPU: notifications, change detection, gates and verdicts, PR metadata checks (title, description, labels, size, breaking-change guard), summaries and reports, and maintenance (stale, labels, branch and run cleanup).

The caller's organization must define GENERAL_RUNNERS or FALLBACK_RUNNERS (LerianStudio defines both). A caller with neither gets an empty runs-on and the job is refused. The same applies to the runs-on examples in the composite READMEs.

This repository's own CI (self-* workflows) reads vars.PUBLIC_RUNNERS || vars.FALLBACK_RUNNERS and never GENERAL_RUNNERS.

Public repositories. Every chain except GitOps starts with (github.event.repository.visibility == 'public' && vars.PUBLIC_RUNNERS). When the calling repository is public and PUBLIC_RUNNERS is set, the job runs there. Otherwise the chain continues as listed. GitHub-hosted runners are free on public repositories, and a public repository must never run on a self-hosted runner. The check reads visibility, not private, because a payload without repository makes !private true and would send private repositories to the public runner.

An unset variable falls through to the next one. A repository variable with the same name overrides the organization one, and keeps that repository out of an organization-wide switch.

runner_type and every *_runner_type input are deprecated and ignored. They stay declared, so a caller that still passes one does not fail; remove them from callers.

In a repository's own workflows:

runs-on: ${{ vars.GENERAL_RUNNERS || vars.FALLBACK_RUNNERS }}
runs-on: ${{ vars.LARGE_RUNNERS || vars.FALLBACK_RUNNERS }}

src/lint/runner-labels fails on a literal label, an inputs.* read or a chain without vars.FALLBACK_RUNNERS in runs-on, and on a *_runner_type value passed under with:. Callers of pr-validation.yml turn it on with runner_labels_check: true.

Versioning

Releases follow Semantic Versioning via semantic-release:

  • Pull requests target main, the only long-lived branch — there is no develop and no beta channel
  • Before merging, test a change by pinning the pull request branch: uses: LerianStudio/shared-workflows-public/.github/workflows/<workflow>.yml@<pr-branch>. Every pull request gets a comment naming its branch and the modules it changes
  • Merges to main → stable release (v1.2.3), then promoted through tier-0 → tier-1 → tier-2

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, 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

The rules AI assistants follow here live in Lerian's Ring ring-dev-team plugin, not in this repository, so every Lerian repository and both shared-workflow repositories read one copy:

Skill Covers
ring-dev-team:authoring-github-actions Entry point: where a new workflow lives (shared internal, shared public, or the repository itself)
ring-dev-team:authoring-reusable-workflows A new reusable workflow or self-* entrypoint
ring-dev-team:authoring-composite-actions A new composite under src/
ring-dev-team:refactoring-shared-workflows Any change to an existing workflow or composite

With Ring installed, Claude Code loads them automatically; invoke one explicitly with /ring-dev-team:refactoring-shared-workflows and so on. AGENTS.md points agents at them.

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.

About

Lerian's public reusable GitHub Actions workflows and composite actions, consumed through tier channels.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages