Skip to content

GITHUB_CONFIGURATION.md

Latest commit

 

History

History
359 lines (242 loc) · 8.35 KB

GITHUB_CONFIGURATION.md

File metadata and controls

359 lines (242 loc) · 8.35 KB

GitHub Repository Configuration Checklist

This document describes the GitHub UI settings that need to be configured for proper branch protection and CI/CD integration.

Status: ✅ Configuration Complete

Repository Settings

General

  • Repository name: SecurityHelperLibrary
  • Description: "Enterprise-grade cryptographic utility library for .NET with hardened PBKDF2, Argon2, AES-GCM, and HMAC"
  • Visibility: Public
  • Template repository: Disabled
  • Default branch: master
  • Require contributors to sign off on commits: Recommended
  • Automatically delete head branches: Enabled

Code and Automation

  • GitHub Actions: Enabled
  • Dependabot alerts: Enabled
  • Dependabot security updates: Enabled
  • Code scanning: Enabled (via GitHub Advanced Security)

Secrets & Variables

Secrets (Settings → Secrets and variables → Actions)

Must be set by repo admin:

Secret Name Value Scope
NUGET_API_KEY [Your NuGet.org API key] publish.yml

To obtain NuGet API key:

  1. Go to https://www.nuget.org/account/apikeys
  2. Create new key with "Push" scope
  3. Copy and add to GitHub Secrets

Branch Protection Rules

Protected Branch: master

Path: Settings → Branches → Add rule

Branch name pattern: master

Enable:

  • Require a pull request before merging

    • Require approvals: 1
    • Require review from code owners: Checked (if CODEOWNERS file exists)
    • Dismiss stale pull request approvals when new commits are pushed
    • Require approval of the most recent reviewable push

  • Require status checks to pass before merging

    • Status checks required:
      • security-tests (from security-tests.yml)
      • build (from build.yml)
      • quality (from build.yml)
      • package (from build.yml)
      • build-summary (from build.yml)

  • Require branches to be up to date before merging

  • Require code reviews before merging

    • Minimum reviewers: 1

  • Require conversation resolution before merging

  • Require signed commits (Recommended)

  • Require deployment to succeed before merging (Optional)

Allow exceptions:

  • Specify who can push to matching branches
    • Whitelist: Repository admins only

Rules apply to admins: [x] Enforced (recommended)

Protected Branch: development

Path: Settings → Branches → Add rule

Branch name pattern: development

Enable:

  • Require a pull request before merging

    • Require approvals: 1 (recommended, not required)

  • Require status checks to pass before merging

    • Status checks required:
      • security-tests
      • build
      • quality
      • build-summary

  • Require branches to be up to date before merging

  • Require code reviews before merging (optional for development)

Allow exceptions:

  • Allow force pushes
    • Permitting: Those with push access
  • Allow deletions: Disabled

Code Owners (Optional but Recommended)

File: .github/CODEOWNERS

# Security-critical files
SecurityHelperLibrary/SecurityHelperLibrary.cs @modestustr
SecurityHelperLibrary.Tests/SecurityHelperPentestTests.cs @modestustr

# Workflow automation
.github/workflows/ @modestustr

# All other files
* @modestustr

Actions Permissions

Path: Settings → Actions → General

  • Actions permissions: Allow all actions

    • Allow public and verified actions: Enabled
    • Allow actions created by GitHub: Enabled
    • Allow specified actions and reusable workflows:
      • actions/checkout@* ✓
      • actions/setup-dotnet@* ✓
      • actions/upload-artifact@* ✓
      • codecov/codecov-action@* ✓
      • actions/create-release@* ✓

  • Workflow permissions:

    • Default permissions: Read and write
    • Allow scripts to create and approve pull requests: Enabled

Environments (Optional)

For NuGet publishing, consider creating an environment:

Path: Settings → Environments → New environment

Environment name: production

Deployment branches:

  • Selected branches: master only

Secrets (environment-specific):

  • NUGET_API_KEY: [Your NuGet API key]

Reviewers (optional):

  • GitHub users that must approve before publish

Webhooks & Apps

Installed Apps:

  • GitHub Actions (native)
  • Dependabot (native)
  • CodeCov (optional, for coverage tracking)

Recommended third-party integrations:

  1. GitGuardian (for secret scanning)

    • Detects accidentally committed secrets
    • Blocks push if secrets found

  2. LGTM or Codacy (for code quality)

    • Analyzes code on every PR
    • Provides quality metrics

  3. Snyk (for dependency vulnerabilities)

    • Scans npm/NuGet packages
    • Auto-opens PRs for patches

Pages (for Documentation)

Path: Settings → Pages

Build and deployment:

  • Source: Deploy from a branch
  • Branch: gh-pages (optional)

Custom domain: (optional)

  • security-helper-library.dev

HTTPS: [x] Enforce HTTPS

Security Policy

File: .github/SECURITY.md

Status: ✅ Created

Enables:

  • GitHub Security Advisories
  • Vulnerability reporting interface
  • Private security discussions

Visit: https://github.com/modestustr/SecurityHelperLibrary/security/advisories

Danger Zone Configuration

Considerations:

  • Allow auto-merge: Disabled (requires manual approval)
  • Allow rebase merging: Disabled (prefer squash)
  • Allow merge commits: Disabled (prefer squash)
  • Allow squash merging: Enabled (preferred)

Default message for merge commits:

Default (pull request title and description)

GitHub Packages (Optional)

If publishing to GitHub Packages instead of/in addition to NuGet.org:

Path: Settings → Packages → Registry access

GitHub Package Registry:

  • Enabled (allows publishing)
  • Permissions: Public read

Release Automation (Optional)

GitHub automatically creates releases from tags:

On tag push: v2.1.0 → Creates Release with release notes from RELEASE_NOTES.md

git tag v2.1.0
git push origin v2.1.0

Verification Checklist

Run this to verify everything is configured:

# Check that all workflows exist
ls -la .github/workflows/
# Expected: build.yml, security-tests.yml, publish.yml, security-tests.yml

# Check templates exist
ls -la .github/ISSUE_TEMPLATE/
# Expected: bug_report.md, feature_request.md

# Check documentation exists
ls -la *.md | grep -E "SECURITY|CONTRIBUTING|BRANCH_PROTECTION|CI_CD"
# Expected: SECURITY.md, CONTRIBUTING.md, BRANCH_PROTECTION.md, CI_CD_STATUS.md

# Check PR template exists
ls -la .github/pull_request_template.md
# Expected: Found

# Verify version in .csproj
grep '<Version>' SecurityHelperLibrary/SecurityHelperLibrary.csproj
# Expected: 2.1.0

Manual Setup Steps (First Time)

  1. Push all files to development branch:

    git add .github CONTRIBUTING.md SECURITY.md BRANCH_PROTECTION.md CI_CD_STATUS.md
git commit -m "chore: add CI/CD configuration and documentation"
git push origin development

  2. In GitHub UI (Settings → Branches):

    • ✅ Add branch protection for master
    • ✅ Add branch protection for development
    • ✅ Configure required status checks

  3. In GitHub UI (Settings → Secrets):

    • ✅ Add NUGET_API_KEY secret

  4. Test the workflow:

    git checkout -b test/ci-validation
echo "# Test" >> README.md
git commit -am "test: verify CI/CD"
git push origin test/ci-validation
# Create PR → Verify all workflows run

  5. Merge to development and verify master rules work

Monitoring & Maintenance

Weekly:

  • Review GitHub Actions usage/quota
  • Check for workflow failures
  • Monitor Dependabot alerts

Monthly:

  • Update GitHub Actions to latest versions
  • Review branch protection rules
  • Audit secrets (rotate API keys if needed)

Quarterly:

  • Review security advisories
  • Update dependencies
  • Audit access permissions

Support

For GitHub-specific configuration questions:

For project-specific questions:

Last Updated: March 1, 2026
Configuration Status: ✅ Complete