Lfx git setup

<!-- Copyright The Linux Foundation and each contributor to LFX. --> <!-- SPDX-License-Identifier: MIT -->

LFX git Setup: DCO Signoff & GPG Signed Commits

This skill walks contributors through two essential git contribution requirements used across linux foundation projects:

1. DCO signoff (--signoff / -s), adds a Signed-off-by: your name <email> line to every commit, certifying you wrote the code and have the right to contribute it under the project's license. This is a legal agreement, not just a formality.
2. GPG signed commits (-S), cryptographically signs each commit with your personal GPG key so GitHub can display a green "verified" badge, proving the commit genuinely came from you.

Your First Step: Detect the User's Platform

Before doing anything else, check what operating system the user is on. The steps are meaningfully different across platforms.

Ask the user (or check their context):

• macos → read references/mac.md for the full walkthrough
• linux (ubuntu, fedora, debian, arch, etc.) → read references/linux.md
• windows → read references/windows.md, note this is a supported but less common setup path; wsl2 (windows subsystem for linux) users should follow linux steps

If it's unclear which platform they're on, just ask: "what operating system are you using, mac, linux, or windows?"

Overall Workflow (all platforms)

The end goal is a ~/.gitconfig that looks roughly like this:

[user]
    name = your full name
    email = [email protected]
    signingkey = abc123def456  # your gpg key id

[commit]
    gpgSign = true             # auto-sign every commit with -S (GPG signing)

[tag]
    gpgSign = true             # auto-sign tags too

and a GPG key that:

• was generated with the same email address as your github account
• has its public key uploaded to GitHub (settings → ssh and gpg keys)

The DCO signoff (-s) is handled separately, see the DCO signoff section below.

The Four Phases

• phase 1, Prerequisites: install gpg tools and verify git version.
• phase 2, Generate GPG key: create your personal signing key.
• phase 3, Configure git: wire the key into ~/.gitconfig.
• phase 4, Register with GitHub: upload your public key so github can verify.

Each platform reference file covers all four phases with exact commands.

DCO signoff

The DCO (--signoff or -s) flag is separate from gpg signing. it adds this line to your commit message:

Signed-off-by: your name <[email protected]>

Option A: Always Sign Off Manually (simplest)

git commit -s -S -m "your commit message"

Both flags together: -s for the DCO signoff, -S for GPG signature.

Option B: git alias (recommended for convenience)

Add a c shortcut (or something you will remember) to ~/.gitconfig so git c -m "..." does both automatically:

An example would be:

git config --global alias.c 'commit -s -S'

Then use: git c -m "your commit message"

Option C: Global Commit Hook (fully automatic)

This approach automatically appends Signed-off-by to every commit message, even in GUI tools:

# create global hooks directory
mkdir -p ~/.git-hooks

# create the hook script
cat > ~/.git-hooks/prepare-commit-msg << 'eof'
#!/bin/sh
# Auto-add DCO Signed-off-by line
sob=$(git var git_author_ident | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
grep -Fqs "^$sob" "$1" || echo "$sob" >> "$1"
eof

# Make the git hook executable
chmod +x ~/.git-hooks/prepare-commit-msg

# Tell git to use this global hooks directory
git config --global core.hookspath ~/.git-hooks

⚠️ Note: the global hook applies to ALL repositories on your machine. If you work on non-lfx projects, you may prefer option A or B instead.

Verifying Everything Works

Once setup is complete, do a test commit:

# in any git repository
git commit -s -S --allow-empty -m "test: verify DCO and gpg signing setup"
git log --show-signature -1

You should see:

• gpg: good signature from "your name <email>" in the output
• a Signed-off-by: line in the commit message

On GitHub, after pushing, the commit will show a green verified badge.

Troubleshooting Quick Reference

problem	likely cause	fix
error: gpg failed to sign the data	gpg agent issue	run export GPG_TTY=$(tty) and retry
no verified badge on github	key not uploaded or wrong email	check key email matches github verified email
secret key not available	key id mismatch	re-run git config --global user.signingkey <id>
DCO check failing in ci	missing signed-off-by	amend last commit: git commit --amend -s
gpg prompts not appearing	missing pinentry	see platform reference file for pinentry setup
gpg: signing failed: inappropriate ioctl	tty not set	add export GPG_TTY=$(tty) to your shell profile

Platform Reference Files

• macos: references/mac.md
• linux: references/linux.md
• windows / wsl2: references/windows.md

Read the appropriate file based on the user's OS before walking them through setup.

Communication Style

This skill serves both technical and non-technical users. Adjust your tone:

• If the user is clearly a developer (mentions terminal, dotfiles, brew, apt, etc.), go straight to commands with brief explanations.
• If the user seems newer to the command line, explain what each command does before showing it, and reassure them that these are one-time setup steps.
• Never assume the user knows what GPG, DCO, or ~/.gitconfig are, briefly define each on first mention.
• After each phase, confirm it worked before moving on. ask: "Did that complete without errors?" before proceeding.