docs: README and contributor security guide

[ms280690]

Context

Type: Documentation
Scope: README.md and CONTRIBUTING.md in sparkgeo/github-actions

Contributors and consuming-repo developers need a single entry point that explains what this repo is, how to use its reusable workflows, and the security standards that all contributions must meet. Without this, security standards defined in #25–#29 live only in GitHub issues and are invisible to new contributors.

README.md — required sections

1. What this repo is

A central library of reusable GitHub Actions workflows for the Sparkgeo organisation. All security, linting, scanning, and deployment workflows are maintained here and consumed by other repos via uses: sparkgeo/github-actions/.github/workflows/<name>.yml@main.

2. Available workflows — index table

Workflow	Purpose	Issues
secrets-precommit.yml	gitleaks pre-commit enforcement	#23
secrets-scan.yml	trufflehog PR verification	#24
dep-scan-app.yml	osv-scanner app dependency CVE scan	#5
dep-scan-iac.yml	checkov IaC dependency scan	#6
dep-scan-helm.yml	trivy Helm/Kustomize scan	#7
renovate.yml	Central Renovate runner	#8
lint-precommit.yml	pre-commit framework CI enforcement	#9–#11
lint-app.yml	megalinter PR gate	#9
lint-iac.yml	tflint PR gate	#10
lint-helm.yml	kubeconform PR gate	#11
container-lint.yml	hadolint Dockerfile lint	#13
container-scan.yml	trivy image vulnerability scan	#14
container-sign.yml	cosign image signing	#15
container-verify.yml	cosign image verification	#15
falco-rules-lint.yml	falco rules validation	#16
falco-deploy.yml	falco Helm deploy	#16
sast-precommit.yml	semgrep fast pattern scan	#18
sast-scan.yml	codeql deep semantic scan	#19
sast-gate.yml	sonarqube quality gate	#20
sast-scheduled.yml	sonarqube weekly re-scan	#21
workflow-lint.yml	actionlint + zizmor workflow security	#25

3. Quick-start — consuming a workflow

# .github/workflows/security.yml (in a consuming repo)
name: Security
on: [pull_request]
jobs:
  secrets:
    uses: sparkgeo/github-actions/.github/workflows/secrets-scan.yml@main
    permissions:
      security-events: write

  container-scan:
    uses: sparkgeo/github-actions/.github/workflows/container-scan.yml@main
    with:
      image-ref: ghcr.io/sparkgeo/my-service:${{ github.sha }}
      fail-on-severity: CRITICAL

4. Security standards (summary)

A concise summary of the six-pillar platform security framework — see CONTRIBUTING.md for full details.

CONTRIBUTING.md — required sections

Workflow authoring checklist

Every PR that adds or modifies a workflow must satisfy all of the following before review:

[ ] All `uses:` references pinned to full 40-char commit SHA with # version comment
[ ] `permissions:` block present at workflow or job level (minimum: contents: read)
[ ] `actions/checkout` has `persist-credentials: false`
[ ] No ${{ github.event.* }} or ${{ github.head_ref }} interpolated directly in `run:` blocks
[ ] No `pull_request_target` or `workflow_run` triggers without a documented threat model
[ ] All `run:` steps declare `shell: bash` explicitly
[ ] `actionlint` and `zizmor` pass locally before pushing (see #25)

Security pillars reference

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

Adding a new workflow

1. Create a GitHub issue using the standard template (parent + context sub-issues)
2. Review the available workflow index above — check for overlap with existing workflows
3. Assign to ms280690, add labels: security, enhancement, documentation, priority: high, type: Feature
4. Implementation must satisfy the authoring checklist before the PR is opened
5. All new reusable workflows must be added to the index table in README.md

Reporting a security issue

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

Acceptance criteria

• README.md updated with all sections above, including the full workflow index table
• CONTRIBUTING.md created with authoring checklist and pillar reference
• README references CONTRIBUTING.md prominently in the intro section
• Index table kept up to date as new workflows are added (add as acceptance criterion to all future workflow issues)