GitHub Actions Security Headers Check (Fail the PR)

August 19, 2026

You want CI to block merges when HSTS or CSP regresses — without standing up a scanner or buying a paid scanner. This guide adds a single GitHub Actions job that calls the free httpsornot public API and fails on HTTP 422 when headersMinGrade is not met.

Key takeaways

Use headersMinGrade for a SecurityHeaders-style gate; use minGrade only if you want the full HTTPS composite score.
curl -f exits non-zero on 422 — no bash grade parsing required.
One check per job: public limit is 120/hour/IP and GHA runners share egress. Hitting 429? Create a free account and an API key at /api-docs#api-keys.
422 = policy fail; 429 = our rate limit — treat them differently.

Workflow file

Create .github/workflows/security-headers.yml and set DOMAIN:

name: Security headers (httpsornot)
on:
  push:
  schedule:
    - cron: "0 8 * * 1"   # weekly smoke

jobs:
  headers:
    runs-on: ubuntu-latest
    steps:
      - name: Fail if headers grade below B
        env:
          DOMAIN: example.com   # ← change this
        run: |
          set -euo pipefail
          # One check per job — public API is 120 req/hour/IP; GHA runners share egress IPs.
          # Optional: create a free account, Dashboard → API keys, then:
          #   -H "X-API-Key: hsn_…"
          # headersMinGrade: A+|A|B|C|D|F (not sslGrade A-/B+).
          # Policy fail / bot block → HTTP 422. Our rate limit → 429 (different!).
          curl -fsS \
            "https://httpsornot.com/api/v1/check?domain=${DOMAIN}&headersMinGrade=B" \
            -o result.json
          jq '{ grade: .securityHeaders.grade, policyOk, gradingVersion: .sslGrade.gradingVersion }' result.json
          # Optional composite HTTPS gate:
          # curl -fsS "https://httpsornot.com/api/v1/check?domain=${DOMAIN}&minGrade=A-&requireHsts=true"

Same snippet lives on the SecurityHeaders migration page with a one-click copy button.

What gets graded

The headers letter covers HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and Permissions-Policy — same six as classic SecurityHeaders.com. How we score weak vs missing values: grading methodology. How-to fix missing headers: security headers guide.

CI is not continuous monitoring

Actions run on push/schedule. Production can still lose a header between deploys. Pair the workflow with domain monitoring (free for one host) or read the CSP regression case study.

CI policy docs Migrating from api.securityheaders.com