Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (94 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

127 lines (94 loc) · 4.64 KB
Raw

Contributing

This repo is the central library of reusable GitHub Actions composite actions for the Sparkgeo organisation. All contributions must meet the security standards below before a PR can be merged.

Workflow authoring checklist

Every PR that adds or modifies a workflow or composite action must satisfy all of the following:

[ ] All `uses:` references pinned to a full 40-character commit SHA with a # version comment
    e.g. uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2

[ ] `permissions:` block present at the workflow or job level — minimum: contents: read
    Default GITHUB_TOKEN permissions must never be relied upon implicitly

[ ] `actions/checkout` includes `persist-credentials: false`
    unless a subsequent step explicitly requires git credentials

[ ] No ${{ github.event.* }}, ${{ github.head_ref }}, or other user-controlled context
    variables interpolated directly inside a `run:` block — assign to an env: var first:
      env:
        HEAD_REF: ${{ github.head_ref }}
      run: echo "$HEAD_REF"

[ ] No `pull_request_target` or `workflow_run` triggers without a documented threat model
    in the workflow file header comment explaining why the trigger is safe

[ ] All `run:` steps declare `shell:` explicitly (shell: bash on Linux/macOS, shell: pwsh on Windows)

[ ] actionlint and zizmor pass locally before pushing (see Local setup below)

Local setup

Install pre-commit and the hooks for this repo:

pip install pre-commit
pre-commit install

The hooks run actionlint and zizmor automatically on every commit that touches workflow or action YAML files. To run them manually against all files:

pre-commit run --all-files

SHA pinning

When adding or updating an action reference, always use the commit SHA of the exact version you intend to use — never a mutable tag. To find the SHA for a given tag:

gh api repos/<owner>/<repo>/commits/<tag> --jq '.sha'
# e.g.
gh api repos/actions/checkout/commits/v6 --jq '.sha'

Once configured, Renovate (issue #8) will keep pinned SHAs current automatically via automated PRs — do not update SHAs manually unless fixing a security incident.

Adding a new action

  1. Create a GitHub issue (parent + context sub-issues where applicable)
  2. Assign to the relevant team or individual, type: Feature, labels: security, enhancement, documentation, priority: high
  3. Branch from main: git checkout -b issue-<number>-<short-description>
  4. Create the composite action under .github/actions/<name>/action.yml — satisfy all checklist items above
  5. Add a job for it in .github/workflows/ci.yml with minimum required permissions
  6. Update the composite actions table in README.md with a usage example
  7. Open a PR referencing the issue: Closes #<number>

Migrating from the reusable workflow pattern

Prior to issue #29, this repo exposed an Actions Quality Gate reusable workflow (workflow-lint.yml) callable via workflow_call. That file has been deleted.

If your repo references it:

# OLD — no longer works
jobs:
  lint:
    uses: sparkgeo/github-actions/.github/workflows/workflow-lint.yml@<SHA>

Replace with direct composite action calls:

# NEW
jobs:
  actionlint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      checks: write
    steps:
      - uses: actions/checkout@<SHA>
        with:
          persist-credentials: false
      - uses: sparkgeo/github-actions/.github/actions/github-actionlint@<SHA>

  zizmor:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@<SHA>
        with:
          persist-credentials: false
      - uses: sparkgeo/github-actions/.github/actions/zizmor@<SHA>

The composite actions are individually callable and require explicit job shells with correct permissions (see README for full usage examples).

Security pillars reference

Pillar Issue Summary
Workflow authoring standards #25 This checklist; actionlint/zizmor gate
Supply chain hardening #26 SHA pinning policy; org allowlist; dependency locking
OIDC & secret federation #27 No static credentials; OIDC for cloud auth; environment-scoped secrets
Runner egress control #28 harden-runner audit → block; self-hosted runner isolation policy
Governance & observability #29 Org rulesets; audit log → SIEM; OpenSSF Scorecard

Reporting a security vulnerability

Do not open a public issue for security vulnerabilities. Use the Security Advisory process via the Security tab of this repo.