Krustytoe · Oct 30, 2026 · Oct 30, 2026 · Oct 30, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,45 @@
+name: Bug report
+description: Something doesn't work the way the docs say it should
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Security issue? Don't file it here. Use private vulnerability reporting (see SECURITY.md).
+        Redact credentials, account/subscription/tenant IDs, and hostnames before posting.
+  - type: input
+    id: version
+    attributes:
+      label: Version / ref
+      description: Release tag or commit SHA you're using
+      placeholder: v0.3.0
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Include the exact error output.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest config, input, or command sequence that shows the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Tool and provider versions, cloud and partition (e.g. AWS GovCloud, Azure Government), runner OS.
+      placeholder: |
+        Terraform 1.10.5, hashicorp/aws 6.69.1, us-gov-west-1
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/Krustytoe/platform-workflows/security/advisories/new
+    about: Please report security issues privately, not as a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest a new capability or a change to existing behaviour
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do, and what's getting in the way?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see? Inputs/outputs, defaults, example usage.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: compliance
+    attributes:
+      label: Security / compliance impact
+      description: Does this change a secure default, or affect FedRAMP / NIST 800-53 alignment?
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,15 @@
+## What and why
+
+<!-- What does this change, and what problem does it solve? Link the issue if there is one. -->
+
+## How it was validated
+
+<!-- Commands you ran and their result. See CONTRIBUTING.md for the local checks CI runs. -->
+
+## Checklist
+
+- [ ] PR title is a [Conventional Commit](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `ci:`, `chore:` …). It becomes the squash-merge commit and drives release-please
+- [ ] Breaking changes are marked with `!` (e.g. `feat!:`) and explained above
+- [ ] Local checks from CONTRIBUTING.md pass
+- [ ] Docs/README updated if inputs, outputs, or behaviour changed
+- [ ] No secrets, tokens, account/subscription/tenant IDs, or internal hostnames
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for taking a look. Issues and PRs are welcome. For anything bigger than a small fix, open an issue first so we can agree on the approach before you write code.
+
+## Workflow
+
+1. Branch from `main` (fork first if you don't have write access).
+2. Make the change and run the local checks below. They're the same ones CI runs.
+3. Open a PR using the template. **The PR title must be a [Conventional Commit](https://www.conventionalcommits.org/)** (`feat:`, `fix:`, `docs:`, `ci:`, `chore:`, `feat!:` for breaking changes). PRs are squash-merged, so the title becomes the commit, and [release-please](https://github.com/googleapis/release-please) uses it to pick the next version and write the changelog.
+4. CI must be green and the PR reviewed before merge.
+
+## Local checks
+
+Requires [actionlint](https://github.com/rhysd/actionlint) (bundles shellcheck checks for `run:` blocks when shellcheck is installed).
+
+```bash
+actionlint -color
+```
+
+To try a workflow change end to end, push your branch and call it from a test repo pinned to the branch's commit SHA. Don't pin to `@main`.
+
+## Workflow conventions
+
+- **Least-privilege `permissions:`** at the job level. Only request `id-token: write` where OIDC is actually used.
+- **No long-lived cloud credentials.** Authentication goes through OIDC (`aws-oidc-auth`, `azure-oidc-auth`).
+- **Reusable workflows don't call this repo's own composite actions.** A workflow can't pin its own repo to its own SHA, so inline those steps with third-party actions SHA-pinned (see the README's Versioning section).
+- **Changes to inputs/outputs are part of the public interface.** Update the README tables, and use `!` in the PR title for anything that breaks existing callers.
+
+## Ground rules
+
+- **No secrets in the repo, ever.** That includes tokens, keys, account/subscription/tenant IDs, and internal hostnames in examples or test fixtures. Use obvious placeholders.
+- **Pin third-party GitHub Actions to a full commit SHA** with the version as a trailing comment (`uses: org/action@<sha> # v1.2.3`) so Dependabot can bump them.
+- Keep changes focused: one concern per PR makes review and rollback easy.
+
+## Security issues
+
+Don't open a public issue. See [SECURITY.md](SECURITY.md).
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # platform-workflows
 
+[![CI](https://github.com/Krustytoe/platform-workflows/actions/workflows/ci.yml/badge.svg)](https://github.com/Krustytoe/platform-workflows/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/Krustytoe/platform-workflows)](https://github.com/Krustytoe/platform-workflows/releases/latest) [![License](https://img.shields.io/github/license/Krustytoe/platform-workflows)](LICENSE)
+
 Reusable GitHub Actions workflows and composite actions for Terraform, security scanning, and cloud authentication. Designed for teams running on AWS (commercial + GovCloud) and Azure (commercial + Government).
 
 ## Architecture

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,19 @@
+# Security policy
+
+## Supported versions
+
+Only the latest release gets security fixes. Pin to a release tag (or its commit SHA), and upgrade when a fix ships.
+
+## Reporting a vulnerability
+
+**Please don't open a public issue for security problems.**
+
+Report privately via GitHub's [private vulnerability reporting](https://github.com/Krustytoe/platform-workflows/security/advisories/new). Include:
+
+- the affected file, module, or workflow and the version/ref you're on
+- what an attacker could do, and the conditions they need
+- steps or a minimal config to reproduce
+
+Leave out real credentials, account/subscription/tenant IDs, and any other sensitive environment details. A redacted repro is plenty.
+
+I'll acknowledge the report, agree on a fix and disclosure timeline with you, and credit you in the advisory unless you'd rather not be named.