.github

Centralized documents and information for the Windlass.

This is the organization's special .github repository, a GitHub convention that automatically applies its files across all repositories in the Windlass organization that don't have their own versions.

Repository Contents

Community Health Files

File	Purpose	Scope
CODE_OF_CONDUCT.md	Contributor Covenant 3.0: behavioral expectations for community participation	Organization-wide
CONTRIBUTING.md	Contribution guidelines: scope boundaries, process, RFC path, development expectations	Organization-wide
SECURITY.md	Security policy: vulnerability reporting, SLSA compliance, supply chain integrity	Organization-wide

Translations

The Code of Conduct is available in multiple languages:

Language	File
English (default)	CODE_OF_CONDUCT.md
한국어 (Korean)	docs/CODE_OF_CONDUCT.ko.md
简体中文 (Chinese Simplified)	docs/CODE_OF_CONDUCT.zh-cn.md
日本語 (Japanese)	docs/CODE_OF_CONDUCT.ja.md
Español (Spanish)	docs/CODE_OF_CONDUCT.es.md
Deutsch (German)	docs/CODE_OF_CONDUCT.de.md
Français (French)	docs/CODE_OF_CONDUCT.fr.md
বাংলা (Bengali)	docs/CODE_OF_CONDUCT.bn.md
Magyar (Hungarian)	docs/CODE_OF_CONDUCT.hu.md

Issue and PR Templates

Template	Location	Purpose
Pull Request Template	.github/PULL_REQUEST_TEMPLATE.md	Standardized PR format with summary, change type, changelog decision, and checklists for CI, testing, and security

CI/CD Workflows

Workflow	File	Purpose	Reusable
Lint	.github/workflows/lint.yml	Blocking Markdown and workflow linting checks	No
autofix.ci	.github/workflows/autofix.yml	Applies bun fmt fixes automatically via autofix.ci	No
Dependency Review	.github/workflows/dependency-review-reusable.yml	Reusable workflow for PR dependency vulnerability and license checks	Yes
Scorecard	.github/workflows/scorecard-reusable.yml	Reusable workflow for OpenSSF Scorecard supply-chain security analysis	Yes
OSV Scanner PR	.github/workflows/osv-scanner-pr-reusable.yml	Reusable workflow for PR diff vulnerability scans	Yes
OSV Scanner Full	.github/workflows/osv-scanner-full-reusable.yml	Reusable workflow for full repository vulnerability scans	Yes
OSV Scanner Smoke	.github/workflows/osv-scanner-smoke.yml	Validates the reusable OSV workflows; reference consumer example	No

How Organization-Wide Files Work

GitHub automatically applies files from this repository to all other repositories in the Windlass organization:

• Default behavior: If a repository doesn't have its own CODE_OF_CONDUCT.md, it will inherit the one from this repository.
• Override: Individual repositories can override by adding their own version of any file.
• Visibility: Files in this repository are visible across the organization via GitHub's UI (e.g., when creating issues or PRs).

Reusable Workflows

This repository provides reusable workflows for common security and compliance checks. Consumer repositories can call these workflows with a single uses: line.

Note

Reusable workflows from windlasstech/.github are an exception to the SHA-pinning requirement. Windlass consumer repositories reference them by branch name (e.g., @main) as a deliberate trade-off: centrally reviewed changes propagate to all consumers immediately, without per-consumer version management. This is not a security equivalent of SHA pinning. A change to this repository's default branch can execute in consumer workflow contexts before consumer-specific adoption, so Windlass consumers running high-privilege workflows may pin a full-length commit SHA instead. Callers outside the Windlass organization are outside this trust boundary and must pin a full-length commit SHA. See Workflow Hardening: Internal Reusable Workflows for the full policy.

Which Workflows Are Reusable

Workflow	Reusable	Reason
OSV Scanner PR	Yes	Standard scan behavior across all repositories
OSV Scanner Full	Yes	Standard full repository scan behavior
Dependency Review	Yes	Centralized policy with per-repo overrides
Scorecard	Yes	Standardized supply-chain security analysis
Lint	No	Tightly coupled to this repo's Bun/markdownlint setup
autofix.ci	No	Repository-specific formatting automation
OSV Scanner Smoke	No	Repository-specific validation of the reusable OSV workflows

OSV Scanner Reusable Workflow

Provides reusable workflows for OSV Scanner vulnerability detection.

Available Workflows

Workflow	File	Trigger	Behavior
PR Diff Scan	osv-scanner-pr-reusable.yml	pull_request, merge_group	Compares base vs head branch, reports only newly introduced vulnerabilities
Full Scan	osv-scanner-full-reusable.yml	push, schedule, workflow_dispatch	Reports all known vulnerabilities in the repository

Standard Defaults

• scan-args defaults to --recursive ./: OSV Scanner auto-detects supported lockfiles across ecosystems
• upload-sarif defaults to true: set to false for repositories where SARIF upload is not available
• fail-on-vuln defaults to true: the workflow fails when vulnerabilities are found
• egress-policy defaults to audit: audit is the minimum floor; callers may pass block together with allowed-endpoints to enforce an egress allow-list
• allowed-endpoints defaults to empty: one endpoint per line (e.g., api.github.com:443); only takes effect when egress-policy is block

Consumer Usage

name: OSV Scanner PR
on:
  pull_request:
  merge_group:
permissions:
  contents: read
jobs:
  osv:
    permissions:
      actions: read
      contents: read
      security-events: write
    uses: windlasstech/.github/.github/workflows/osv-scanner-pr-reusable.yml@main

name: OSV Scanner Full
on:
  schedule:
    - cron: "30 12 * * 1"
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  osv:
    permissions:
      actions: read
      contents: read
      security-events: write
    uses: windlasstech/.github/.github/workflows/osv-scanner-full-reusable.yml@main

Reference Consumer

This repository dogfoods both reusable workflows in .github/workflows/osv-scanner-smoke.yml. Consult the smoke workflow as a working reference when wiring the PR diff scan and full scan into your own repository, including the required job permissions and scan-args overrides.

Multi-Ecosystem Support

These workflows support all ecosystems that OSV Scanner recognizes, including JavaScript, Python, Go, Rust, Java, .NET, PHP, and others. Standard lockfiles are auto-detected when scanning recursively from the repository root.

Repositories with nonstandard layouts may override scan-args:

• Explicit lockfile targeting: --lockfile=./path/to/custom.lock
• Path exclusions: --experimental-exclude=./vendor

Rollout Notes

• For initial calibration, a repository may temporarily set fail-on-vuln: false for the first 1-2 runs
• After calibration, revert to the standard default of true
• Reference the workflow by @main under the internal reusable workflow exception; high-privilege consumers may pin a full-length commit SHA instead

Dependency Review Reusable Workflow

Provides standardized dependency vulnerability and license checking across all repositories with a centralized configuration.

Available Inputs

Input	Required	Default	Description
config-file	No	windlasstech/.github/.github/dependency-review-config.yml@main	Path to dependency review configuration file
fail-on-severity	No	(from config)	Minimum severity to fail (low, moderate, high, critical)
comment-summary-in-pr	No	on-failure	Post summary comment to PR (always, on-failure, never)
warn-only	No	false	Report only, never fail
external-repo-token	No	(empty)	Token for accessing external repository configs
egress-policy	No	audit	Harden Runner egress policy; block requires allowed-endpoints
allowed-endpoints	No	(empty)	Allowed outbound endpoints, one per line; only used with egress-policy: block

Consumer Usage

name: Dependency Review
on:
  pull_request:
  merge_group:
permissions:
  contents: read
jobs:
  dependency-review:
    permissions:
      contents: read
      pull-requests: write
    uses: windlasstech/.github/.github/workflows/dependency-review-reusable.yml@main

With Custom Configuration

name: Dependency Review
on:
  pull_request:
permissions:
  contents: read
jobs:
  dependency-review:
    permissions:
      contents: read
      pull-requests: write
    uses: windlasstech/.github/.github/workflows/dependency-review-reusable.yml@main
    with:
      fail-on-severity: moderate
      warn-only: false

Dependency Review Configuration

The reusable workflow references a centralized configuration file that defines organization-wide policies for dependency vulnerability and license checking.

Policy Area	Default Setting	Description
Vulnerability	moderate	Minimum severity that fails the check (low, moderate, high, critical)
Scopes	development + runtime	Both dev and runtime dependencies are checked
License	Allow-list	Only permissive licenses (MIT, Apache-2.0, BSD, ISC, CC0, etc.) are permitted
OpenSSF Scorecard	true	Displays Scorecard information for dependencies
GHSA Allow-list	(empty)	Security advisories can be temporarily exempted with approval

Configuration file location: .github/dependency-review-config.yml

Repository-specific overrides: Individual repositories can override the centralized policy by passing different values to the reusable workflow inputs (e.g., fail-on-severity: high for stricter or warn-only: true for observation mode).

Scorecard Reusable Workflow

Provides standardized OpenSSF Scorecard supply-chain security analysis with configurable publishing and artifact options.

Available Inputs

Input	Required	Default	Description
results-file	No	results.sarif	Path to the SARIF results file
results-format	No	sarif	Results format (sarif, json, csv)
publish-results	No	true	Publish results to OpenSSF REST API
repo-token	No	(empty)	Fine-grained PAT for Branch-Protection check
file-mode	No	(empty)	File mode for .gitattributes export-ignore
retention-days	No	5	Artifact retention days
upload-artifact	No	true	Upload results as artifact
upload-code-scanning	No	true	Upload results to GitHub code scanning dashboard
egress-policy	No	audit	Harden Runner egress policy; block requires allowed-endpoints
allowed-endpoints	No	(empty)	Allowed outbound endpoints, one per line; only used with egress-policy: block

Consumer Usage

name: Scorecard supply-chain security
on:
  branch_protection_rule:
  schedule:
    - cron: "20 7 * * 2"
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  analysis:
    permissions:
      contents: read
      issues: read
      pull-requests: read
      checks: read
      security-events: write
      id-token: write
    uses: windlasstech/.github/.github/workflows/scorecard-reusable.yml@main

Private Repository Usage

name: Scorecard supply-chain security
on:
  schedule:
    - cron: "20 7 * * 2"
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  analysis:
    permissions:
      contents: read
      issues: read
      pull-requests: read
      checks: read
      security-events: write
      id-token: write
    uses: windlasstech/.github/.github/workflows/scorecard-reusable.yml@main
    with:
      publish-results: false
      upload-code-scanning: false
      repo-token: ${{ secrets.SCORECARD_TOKEN }}

Why the Lint and autofix.ci Workflows Are Not Reusable

The lint.yml and autofix.yml workflows are intentionally not provided as reusable workflows because they are tightly coupled to this repository's specific tooling stack:

• Package manager: Uses bun with bun.lock
• Linting tools: Assumes markdownlint-cli2 and Bun's built-in formatter (bun fmt)
• Configuration files: Expects .markdownlint-cli2.jsonc and bunfig.toml to exist at repository root
• Scripts: autofix.yml calls bun run format from this repo's package.json; lint.yml uses the markdownlint-cli2 and actionlint actions directly
• GitHub App: autofix.yml additionally requires the autofix.ci GitHub App to be installed on the repository

Consumer repositories using different package managers (npm, yarn, pnpm) or different linting configurations should implement their own repository linting workflow tailored to their stack.

That said, consumer repositories rarely need to start from a blank page: in many cases this repository's two workflows are a good starting point. Copy lint.yml and autofix.yml and adapt the tool installation, scripts, and trigger paths to your own stack.

Development

Linting and Formatting

This repository uses markdownlint-cli2 and Bun's built-in formatter (bun fmt) for consistent Markdown, YAML, and JSON/JSONC style.

Setup

bun install

Available Scripts

Script	Description
bun run lint:md	Lint all Markdown files
bun run lint:md:fix	Lint and auto-fix issues
bun run format	Format Markdown, YAML, and JSON/JSONC files with bun fmt
bun run format:check	Check formatting without modifying files

Configuration

• markdownlint (.markdownlint-cli2.jsonc): Configured to avoid conflicts with the formatter
• bun fmt (bunfig.toml [fmt]): printWidth 100 with prose always wrapped; .editorconfig mirrors these defaults for editors

Pre-commit Hooks

This repository uses Lefthook to automatically lint and format Markdown files before each commit.

When you commit changes:

1. Staged .md and .mdx files are automatically linted with markdownlint-cli2 --fix
2. Staged Markdown, YAML, JSON, and JSONC files are formatted with bun fmt
3. Fixed files are re-staged automatically
4. If there are unfixable errors, the commit is blocked

The hooks are installed automatically when you run bun install via the prepare script.

To manually run the pre-commit hook:

bunx lefthook run pre-commit

CI/CD

Pull requests and pushes to main that modify Markdown or workflow files trigger blocking lint checks via the Lint workflow. autofix.ci automatically applies bun fmt formatting fixes to Markdown, YAML, JSON/JSONC, lockfile, and tooling configuration files.