Skip to content

Development Environment Setup

This document describes a recommended, portable Git setup

to keep Windows 11 and WSL environments aligned when working on this repository.

All examples use placeholders and are safe to publish.

Repository

This project uses SSH for Git operations.

Public repository URL:

git@github.com:<GITHUB_USERNAME>/<REPOSITORY_NAME>.git

Git Transport (SSH)

Always use SSH instead of HTTPS.

git remote set-url origin git@github.com:<GITHUB_USERNAME>/<REPOSITORY_NAME>.git

Verify:

git remote -v

SSH Keys

Recommended key type:

  • ED25519
  • One key per machine

The public key must be added to GitHub as:

  • Authentication key
  • Signing key

Test SSH connectivity:

ssh -T git@github.com

Expected output:

Hi <GITHUB_USERNAME>! You've successfully authenticated...

Commit Signing (SSH-based)

Enable SSH-based commit signing:

git config --global gpg.format ssh

git config --global user.signingkey ~/.ssh/id_ed25519.pub

git config --global commit.gpgsign true

allowed_signers File

Git requires an explicit list of allowed signing keys.

Create the file:

  • Linux / WSL
~/.config/git/allowed_signers
  • Windows
C:/Users/<USERNAME>/.config/git/allowed_signers

File format (single line per identity):

<EMAIL_OR_IDENTITY> ssh-ed25519 AAAA...

Notes:

  • the SSH key must match user.signingkey
  • the file is personal
  • it must not be committed to the repository

Signature Verification

Verify commit signatures with:

git log --show-signature -1

Expected result:

Good "git" signature for <IDENTITY>

Commit Signing and Release Model

This project enforces commit signing as part of its development workflow.

Local Enforcement (Developers)

All developers are required to sign their commits using SSH keys.

  • Commit signing must be enabled locally
  • SSH-based signing is the recommended and supported mechanism
  • Local Git hooks (pre-commit, commit-msg) enforce commit hygiene and conventions

Unsigned commits created locally are considered invalid.

Server-Side Enforcement

Due to current GitHub platform limitations, commit signature verification is enforced as follows:

  • Direct pushes to main by human users are not allowed
  • All changes must go through Pull Requests
  • CI checks must pass before merging
  • Automated commits generated by CI (e.g. semantic-release) are allowed

This ensures a secure workflow while preserving full automation.

See also:

Platform Notes

  • .gitconfig may differ between Windows and WSL
  • allowed_signers is local-only
  • only repository policy and hooks should be versioned

Security Notes

  • Never commit private keys
  • Never commit allowed_signers
  • Do not include personal emails or usernames in documentation
  • Use placeholders in public documentation