From 16b865347da1c2138eb834146efe914b145e3523 Mon Sep 17 00:00:00 2001 From: Tony Le <27826928+Krustytoe@users.noreply.github.com> Date: Fri, 30 Oct 2026 08:48:09 -0500 Subject: [PATCH 1/2] docs: add contributing guide, security policy, and issue/PR templates Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/bug_report.yml | 45 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 27 +++++++++++++ .github/pull_request_template.md | 15 ++++++++ CONTRIBUTING.md | 45 ++++++++++++++++++++++ SECURITY.md | 19 +++++++++ 6 files changed, 156 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..b21495e --- /dev/null +++ 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 new file mode 100644 index 0000000..54769eb --- /dev/null +++ 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/observability-as-code/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 new file mode 100644 index 0000000..f608888 --- /dev/null +++ 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 new file mode 100644 index 0000000..0caaf6d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## What and why + + + +## How it was validated + + + +## 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 new file mode 100644 index 0000000..88f84ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# 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 `promtool`, go-jsonnet (`jsonnet`, `jsonnetfmt`), `jb`, and Python 3. CI installs pinned versions; see [`.github/workflows/ci.yml`](.github/workflows/ci.yml). + +```bash +make vendor # first time only: jb install (pinned in grafana/jsonnetfile.lock.json) +make ci # fmt-check → promtool check rules → promtool test rules → build dashboards → policy checks +make fmt # auto-format Jsonnet +``` + +If you touched `deploy/terraform`: + +```bash +cd deploy/terraform +terraform fmt -check +terraform init -backend=false -input=false +terraform validate +``` + +## Content conventions + +- **Every alert has a test with both a firing and a non-firing case** in `prometheus/tests/`. A rule PR without a test won't be merged. +- **Severity follows the repo convention:** `warning` is informational/awareness, `critical` means service interruption or needs immediate attention. Every alert carries a `summary` and a `runbook_url` pointing at its anchor in [`runbooks/README.md`](runbooks/README.md). +- **Dashboards are Jsonnet only.** Don't commit hand-edited JSON. Everything in `build/` is generated. Dashboards must use the `$datasource` variable, a stable `uid` of 40 characters or fewer, and `editable: false`. `scripts/check_dashboards.py` enforces all of this. + +## 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@ # 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/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..56afd8d --- /dev/null +++ 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/observability-as-code/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. From d978e8e09423b7767bee5b1630920d2e496322ef Mon Sep 17 00:00:00 2001 From: Tony Le <27826928+Krustytoe@users.noreply.github.com> Date: Fri, 30 Oct 2026 08:48:09 -0500 Subject: [PATCH 2/2] docs: add CI, release, and license badges Co-Authored-By: Claude Opus 5.5 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 4949478..645029a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # observability-as-code +[![CI](https://github.com/Krustytoe/observability-as-code/actions/workflows/ci.yml/badge.svg)](https://github.com/Krustytoe/observability-as-code/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/Krustytoe/observability-as-code)](https://github.com/Krustytoe/observability-as-code/releases/latest) [![License](https://img.shields.io/github/license/Krustytoe/observability-as-code)](LICENSE) + Prometheus alerting rules, Grafana dashboards, and the deploy pipeline for both, all version-controlled, unit-tested, and generated from code instead of being clicked together in a UI. ```