Skip to main content

Repository Audit Checklist: [repo-name]

Template Instructions

Replace all text in [brackets] with your content. Delete this callout when done. This checklist ensures repositories meet standards for security, quality, and maintainability.

Audit Overview​

Repository: [organization/repo-name]

Repository URL: [https://github.com/org/repo]

Primary Language: [TypeScript, Python, etc.]

Type: [Web app, API, Library, CLI tool, etc.]

Status: [Active, Maintenance, Deprecated]

Audit Date: [YYYY-MM-DD]

Auditor: [Name]

Previous Audit: [YYYY-MM-DD or "First audit"]

Repository Information​

Basic Information​

FieldValue
Repository Name[repo-name]
Owner/Organization[owner]
Primary Language[Language]
Framework[Framework/Stack]
VisibilityPublic / Private
Created[YYYY-MM-DD]
Last Updated[YYYY-MM-DD]
Stars[Number (if public)]
Forks[Number (if public)]

Team & Ownership​

RoleNameGitHub Handle
Owner[Name]@[handle]
Maintainers[Name]@[handle]
Contributors[Count] active
  • Repository ownership is clear
  • Owner is documented in README
  • CODEOWNERS file exists
  • CODEOWNERS file is accurate

Documentation​

README Quality​

  • README.md exists
  • README has clear project description
  • README has installation instructions
  • README has usage examples
  • README has dependencies listed
  • README has contribution guidelines link
  • README has license information
  • README has contact/support information
  • README badges are functional (build status, coverage, etc.)

README Score: [X/10]

Issues:

  • [Issue 1]
  • [Issue 2]

Additional Documentation​

  • CONTRIBUTING.md exists

    • Clear contribution process
    • Code style guidelines
    • PR requirements
    • Development setup

  • CHANGELOG.md exists and is current

    • Follows Keep a Changelog format
    • Up to date with recent releases
    • Includes version numbers and dates

  • LICENSE file exists

    • License type: [MIT, Apache, GPL, etc.]
    • Copyright holder correct
    • Year current

  • CODE_OF_CONDUCT.md exists (for public repos)

  • SECURITY.md exists

    • Security policy defined
    • Vulnerability reporting process
    • Supported versions listed

  • API documentation exists

    • Inline code documentation
    • API reference docs
    • Examples provided
    • Documentation is current

Technical Documentation​

  • Architecture documentation exists

    • High-level architecture described
    • Key components documented
    • Data flow diagrams (if applicable)

  • Setup/Installation docs are accurate

    • Tested recently: [Date]
    • Works for new developers
    • Prerequisites clearly listed

  • Deployment documentation exists

    • Deployment process documented
    • Environment variables documented
    • Rollback procedures documented

Code Quality​

Code Structure​

  • Logical folder structure
  • Consistent naming conventions
  • No dead/unused code
  • No commented-out code blocks
  • Appropriate file sizes (not too large)
  • Modular design

Issues:

  • [Issue 1]
  • [Issue 2]

Code Standards​

  • Linter configured

    • Linter: [ESLint, Pylint, etc.]
    • Config file present: [.eslintrc, etc.]
    • No linter errors: ✅/❌

  • Formatter configured

    • Formatter: [Prettier, Black, etc.]
    • Config file present: [.prettierrc, etc.]
    • Code is formatted: ✅/❌

  • Editor config present

    • .editorconfig file exists
    • Consistent indentation
    • Consistent line endings

  • Type checking (if applicable)

    • TypeScript configured
    • Strict mode enabled
    • No type errors

Code Review​

  • Code follows language best practices
  • No obvious security vulnerabilities
  • Error handling is comprehensive
  • Logging is appropriate
  • No hard-coded secrets or credentials
  • Environment variables used correctly

Code Quality Score: [X/10]

Testing​

Test Coverage​

  • Tests exist

    • Test framework: [Jest, Pytest, etc.]
    • Tests are runnable
    • Tests pass: ✅/❌

  • Test coverage measured

    • Coverage tool: [Jest, Coverage.py, etc.]
    • Current coverage: [X%]
    • Coverage target: [Y%]
    • Meets target: ✅/❌

  • Coverage badge in README

    • Badge present: ✅/❌
    • Badge is current: ✅/❌

Test Types​

  • Unit tests present

    • Count: [N tests]
    • Coverage: [X%]
    • Quality: [Good/Fair/Poor]

  • Integration tests present

    • Count: [N tests]
    • Coverage: [Key integrations covered]
    • Quality: [Good/Fair/Poor]

  • E2E tests present (if applicable)

    • Framework: [Playwright, Cypress, etc.]
    • Critical paths covered
    • Tests run in CI

  • Performance tests (if applicable)

    • Benchmarks defined
    • Performance regression testing

Test Quality​

  • Tests are maintainable
  • Tests have clear descriptions
  • Tests are deterministic (no flaky tests)
  • Test data is managed properly
  • Mocks/stubs used appropriately

Testing Score: [X/10]

Issues:

  • [Issue 1]
  • [Issue 2]

CI/CD​

Continuous Integration​

  • CI configured

    • CI Platform: [GitHub Actions, CircleCI, etc.]
    • CI config file: [.github/workflows/, etc.]

  • CI runs on

    • Pull requests
    • Pushes to main/master
    • Scheduled runs

  • CI includes

    • Linting
    • Tests
    • Build verification
    • Security scanning
    • Dependency checks

  • CI status

    • Current status: ✅ Passing / ❌ Failing
    • Badge in README: ✅/❌
    • Failures investigated promptly

Continuous Deployment​

  • CD configured (if applicable)

    • Deployment target: [Vercel, AWS, etc.]
    • Auto-deploy configured
    • Deploy on: [Merge to main, tags, manual]

  • Deployment environments

    • Production
    • Staging
    • Preview/PR environments

  • Deployment checks

    • Pre-deployment tests
    • Post-deployment verification
    • Rollback capability

CI/CD Score: [X/10]

Security​

Dependency Security​

  • Dependency scanning enabled

    • Tool: [Dependabot, Snyk, etc.]
    • Scan frequency: [Daily, Weekly]
    • Alerts configured

  • Security alerts

    • No critical vulnerabilities: ✅/❌
    • High severity count: [N]
    • Medium severity count: [N]
    • Low severity count: [N]

  • Dependencies up to date

    • Outdated dependencies: [N]
    • Major updates available: [N]
    • Update strategy defined

Secret Management​

  • No secrets in code

    • No API keys
    • No passwords
    • No tokens
    • No certificates

  • Secret scanning enabled

    • Tool: [GitHub secret scanning, GitGuardian, etc.]
    • No secrets detected: ✅/❌

  • .gitignore configured correctly

    • .env files ignored
    • Credential files ignored
    • Build artifacts ignored
    • IDE files ignored

  • Environment variables documented

    • .env.example exists
    • All variables documented
    • Secure storage method documented

Access Control​

  • Branch protection enabled

    • Protected branch: [main, master, etc.]
    • Require pull request reviews
    • Require status checks
    • No force push allowed
    • Admin enforcement

  • Repository access appropriate

    • Team access reviewed
    • Minimum necessary permissions
    • No unnecessary admin access
    • Access audit date: [Date]

Code Security​

  • Security linting enabled

    • Tool: [ESLint security plugin, Bandit, etc.]
    • Rules configured
    • No security warnings: ✅/❌

  • Static analysis (if applicable)

    • Tool: [SonarQube, CodeQL, etc.]
    • Security issues: [N]
    • Quality issues: [N]

Security Score: [X/10]

Critical Issues:

  • [Issue 1]
  • [Issue 2]

Dependencies​

Dependency Health​

  • package.json / requirements.txt / etc. exists
  • Lock file present (package-lock.json, Pipfile.lock, etc.)
  • Lock file up to date
  • No unused dependencies

Dependency Analysis​

MetricValue
Total Dependencies[N]
Direct Dependencies[N]
Outdated Dependencies[N]
Deprecated Dependencies[N]
Security Vulnerabilities[N]

Notable Dependencies​

DependencyVersionLatestNotes
[dep1][1.0.0][2.0.0][Major update available]
[dep2][3.2.1][3.2.1][Up to date]
  • Critical dependencies pinned
  • Dependency update strategy documented
  • Breaking changes monitored

Dependencies Score: [X/10]

Git Practices​

Commit Quality​

  • Commit messages are clear
  • Conventional commits used (if applicable)
  • Atomic commits (single purpose per commit)
  • No large binary files committed

Branch Strategy​

  • Branch strategy documented

    • Strategy: [Git Flow, GitHub Flow, etc.]
    • Main branch: [main, master]
    • Development branch: [develop, staging]

  • Branch naming convention

    • Convention documented
    • Convention followed
    • Examples: [feature/, bugfix/, etc.]

Pull Request Process​

  • PR template exists

    • .github/pull_request_template.md present
    • Template includes checklist
    • Template prompts for description

  • PR review requirements

    • Number of required reviews: [N]
    • Required reviewers defined
    • CI checks required

  • PR quality

    • Recent PRs reviewed: [Sample reviewed]
    • Good descriptions: ✅/❌
    • Appropriate size: ✅/❌
    • Linked to issues: ✅/❌

Git Practices Score: [X/10]

Project Management​

Issue Tracking​

  • Issues used for tracking work

  • Issue templates configured

    • Bug report template
    • Feature request template
    • Custom templates (if applicable)

  • Issue labels configured

    • Standard labels present (bug, enhancement, etc.)
    • Custom labels (if needed)
    • Labels used consistently

  • Issue triage process

    • Process documented
    • Regular triage occurs
    • Stale issues handled

Milestones & Projects​

  • Milestones used (if applicable)
  • Project boards used (if applicable)
  • Roadmap documented

Release Management​

  • Releases created (if applicable)

    • Using GitHub releases
    • Semantic versioning followed
    • Release notes included

  • Tagging strategy

    • Tags created for releases
    • Tag naming convention: [v1.0.0, etc.]
    • Tags are consistent

Project Management Score: [X/10]

Performance & Monitoring​

Build Performance​

  • Build time reasonable

    • Current build time: [X minutes]
    • Build time tracked
    • Optimizations applied

  • Bundle size monitored (if applicable)

    • Current size: [X MB]
    • Size budget defined
    • Size regressions prevented

Monitoring​

  • Application monitoring configured

    • Monitoring tool: [Sentry, DataDog, etc.]
    • Error tracking enabled
    • Performance monitoring enabled

  • Analytics configured (if applicable)

    • Analytics tool: [PostHog, GA, etc.]
    • Key events tracked
    • Privacy compliant

Repository Settings​

General Settings​

  • Repository description set
  • Topics/tags configured (for public repos)
  • Homepage URL set (if applicable)
  • Wiki enabled (if used)
  • Discussions enabled (if used)
  • Sponsorship enabled (if applicable)

Features​

  • Issues enabled
  • Projects enabled (if used)
  • Preserve this repository checked (if critical)

Webhooks​

  • Webhooks documented
    • Each webhook purpose documented
    • Webhook endpoints secured
    • Webhook failures monitored

Compliance & Standards​

License Compliance​

  • License is appropriate
  • License covers all dependencies
  • No license conflicts
  • Attribution requirements met

Accessibility (if applicable)​

  • Accessibility standards followed
  • ARIA labels present (web apps)
  • Keyboard navigation working
  • Screen reader tested

Data Privacy​

  • GDPR compliance (if applicable)
  • User data handling documented
  • Data retention policy defined
  • Privacy policy linked

Industry Standards​

  • Follows language standards
  • Follows framework best practices
  • Meets team/org standards

Overall Assessment​

Scores Summary​

CategoryScoreWeightNotes
Documentation[X/10]15%
Code Quality[X/10]20%
Testing[X/10]20%
CI/CD[X/10]15%
Security[X/10]20%
Dependencies[X/10]5%
Git Practices[X/10]5%

Overall Score: [X/100]

Grade: [A+ / A / B / C / D / F]

Health Status​

  • 🟢 Excellent (90-100): Production-ready, minimal issues
  • 🟡 Good (75-89): Solid, some improvements needed
  • 🟠 Fair (60-74): Functional, significant improvements needed
  • 🔴 Poor (< 60): Requires immediate attention

Status: [Emoji and description]

Critical Issues​

Immediate Action Required

These issues pose security risks or block development. Address within 48 hours.

  1. [Issue 1]

    • Severity: 🔴 Critical
    • Description: [Details]
    • Action: [Required action]
    • Owner: [Assigned to]
    • Due: [Date]

  2. [Issue 2]

    • Severity: 🔴 Critical
    • Description: [Details]
    • Action: [Required action]
    • Owner: [Assigned to]
    • Due: [Date]

Recommendations​

High Priority (Fix within 2 weeks)​

  • [Recommendation 1] - Owner: [Name]
  • [Recommendation 2] - Owner: [Name]
  • [Recommendation 3] - Owner: [Name]

Medium Priority (Fix within 1 month)​

  • [Recommendation 1] - Owner: [Name]
  • [Recommendation 2] - Owner: [Name]
  • [Recommendation 3] - Owner: [Name]

Low Priority (Nice to have)​

  • [Recommendation 1] - Owner: [Name]
  • [Recommendation 2] - Owner: [Name]

Technical Debt​

List known technical debt items:

  • [Debt item 1] - [Impact: High/Med/Low]
  • [Debt item 2] - [Impact: High/Med/Low]
  • [Debt item 3] - [Impact: High/Med/Low]

Action Items​

PriorityActionOwnerDue DateStatus
P0[Action][Name][Date]🔴/🟡/🟢
P1[Action][Name][Date]🔴/🟡/🟢
P2[Action][Name][Date]🔴/🟡/🟢

Comparison to Previous Audit​

Previous Audit Date: [YYYY-MM-DD or "N/A - First Audit"]

Previous Score: [X/100]

Current Score: [Y/100]

Change: [+/- Z points]

Improvements Made​

  • [Improvement 1]
  • [Improvement 2]
  • [Improvement 3]

Regressions​

  • [Regression 1]
  • [Regression 2]

Next Audit​

Scheduled Date: [YYYY-MM-DD]

Focus Areas for Next Audit:

  • [Area 1]
  • [Area 2]
  • [Area 3]

Follow-up Items:

  • Verify critical issues resolved
  • Check action item completion
  • Re-measure scores in weak areas

Audit Notes​

[Any additional notes, context, or observations from the audit]

  • [System Profile]
  • [Contributing Guidelines]
  • [Security Policy]
  • [Previous Audit Report]

Audit Version: 1.0 Auditor: [Name] Audit Date: [YYYY-MM-DD] Next Review: [YYYY-MM-DD]