Skip to main content
In this lesson you’ll create a repository security policy that tells contributors and users how to report vulnerabilities and which product versions receive security updates. A clear SECURITY.md improves trust, reduces noisy reports, and helps coordinate responsible disclosure.

​
Where to place the security policy

The security policy should be a file named SECURITY.md. It can live at the repository root or inside the .github directory. Best practice is to place it at .github/SECURITY.md so it’s grouped with other repository metadata (issue templates, CODEOWNERS, etc.).
Place SECURITY.md in .github/SECURITY.md (or at the repo root). If you want stricter workflow control, require pull requests to add or modify it instead of committing directly to the default branch.

​
What to include in SECURITY.md

A good security policy typically covers:
  • Supported versions and how long security fixes are provided for each release.
  • Clear reporting channels (email address, issue template, or third-party platform).
  • Expected confidentiality (e.g., “do not post details publicly before a fix”).
  • Triage and response timelines (acknowledgement, initial triage, and remediation windows).
  • Whether you accept encrypted reports (PGP/GPG) and how to obtain the public key.
  • The disclosure process (coordinated disclosure, CVE issuance, public advisory).
Example SECURITY.md content you can adapt:

​
Recommended content and examples

You can expand the Reporting section with specifics. For example, provide:
  • One primary contact method (email or private issue reporter).
  • Whether encrypted emails are accepted (PGP/GPG key fingerprint and instructions).
  • A short timeline (acknowledge, initial triage timeframe, and estimated fix period).
  • How to request or track a CVE.
Use a short, scannable table for supported versions and a clear step-by-step for reporting.

​
Example: Reporting options (table)

Do not include sensitive details (exploit code, POCs, or victim data) in public issues. If you accept encrypted reports, publish your PGP/GPG key fingerprint and instructions in SECURITY.md.
These are sample timelines you can adapt for your project:
  • Acknowledge receipt: within 48 hours.
  • Initial triage (assess severity and reproduction): within 7 days.
  • Fix or mitigation plan: within 30–90 days depending on severity.
  • Public advisory/CVE issuance: coordinated with reporter after fix is available.
State your project’s actual timelines in SECURITY.md so reporters know what to expect.

​
Creating and committing the policy

You can create SECURITY.md directly in GitHub’s web editor (commit to the default branch or create a pull request), or manage it locally and push:
After committing, the .github folder with SECURITY.md will appear in the repository’s file list alongside README and other metadata.
A dark-mode GitHub repository page displaying the .github folder and a list of files (ISSUE_TEMPLATE, CODEOWNERS, PULL_REQUEST_TEMPLATE.md, SECURITY.md, dependabot.yml) with recent commit messages. The left sidebar shows other repo files like README.md, app.js, and package.json.
The security policy will be visible to contributors and visitors alongside other repository files. GitHub also surfaces this policy in the repository’s Security tab to make it easier for reporters to find guidance.
A dark-mode screenshot of a GitHub repository's Security tab displaying a "Security Policy" page with a "Supported Versions" table and a "Reporting a Vulnerability" section. The right sidebar shows repo details like contributors, releases, and language statistics.

​
Best practices

  • Keep the policy concise and actionable.
  • Provide only one or two clear reporting channels.
  • Offer encrypted-report options and publish your public key if you accept them.
  • Keep the supported-versions table up to date with each release.
  • Use PRs to update SECURITY.md so changes are reviewed and auditable.
Creating a clear SECURITY.md reduces friction for reporters, helps maintainers triage faster, and protects your users by ensuring a coordinated disclosure process.

Watch Video