Appearance

Powered by Platform One

Configure Commit Signing in WSL Using Your Windows CAC ​

Overview ​

This article explains how to configure WSL to sign Git commits using the CAC certificate configured on your Windows host.

Use this workflow if you:

  • Develop primarily in WSL (Ubuntu/Linux).
  • Store Git repositories inside WSL (~/repo/...).
  • Use a Windows computer with a CAC reader.
  • Need to sign commits for GitLab projects (code.il4.dso.mil).
  • Prefer to use your existing Windows CAC configuration instead of configuring smart card support directly in Linux.

All commits must be signed using either a CAC or a GPG key. Developers with a CAC can configure Git to sign commits using their CAC certificate. For projects operating in IL4 and IL5 environments, CAC signing is required for all commits.

If you do not use a CAC for commit signing, follow the How to Commit Sign with GPG Guide.

WARNING

Party Bus does not support commit signing through IDE integrations. If you create commits in an IDE, use the command line to sign them. Do not submit Party Bus support requests for IDE-specific commit signing issues.

INFO

These instructions have been tested on Ubuntu 20.04 LTS. Other Linux distributions may require additional configuration. Updates to GPG packages may affect CAC detection.

Prerequisites ​

Before you begin:

  • Complete the Windows CAC Signing Guide. This guide assumes Git, S/MIME Sign, and your CAC signing certificate are already configured on Windows.
  • Install WSL with Ubuntu.
  • Insert your CAC.
  • Verify that Windows recognizes your CAC before continuing.

  1. Verify that Windows recognizes your CAC.

    a. Insert your CAC into the reader.

    For Dell Precision 5680, your chip faces up.

    b. Run

    shell
    certutil -scinfo

  2. Verify your document signing certificate exists.

    shell
    Get-ChildItem Cert:\CurrentUser\My\ -EKU "Document Signing"

    Confirm that:

    • A Document Signing certificate is returned.
    • Record the certificate thumbprint. You will use it when configuring Git in WSL.

Confirm Your GitLab Commit Email Address ​

After identifying your CAC signing certificate, verify that your GitLab commit email matches the email address on your CAC signing certificate.

  1. Open User Settings > Emails .
  2. Find the email address marked with the Commit email icon icon.
  3. Verify that your GitLab commit email matches the email address on your CAC.

If the correct email address is not listed:

  1. Submit a request for GitLab commit sign email validation .

    • For repo1.dso.mil, contact the Iron Bank team instead.

  2. Wait until the request is complete.

  3. Open User Settings > Profile.

  4. Select the newly added CAC CDS email address as your Commit Email.

    WARNING

    Do not add the email address to GitLab yourself. User-added email addresses require email verification, but GitLab on P1 cannot send verification emails. The email address must be added and verified through the service request.

    If multiple developers need commit email validation, submit a single request that includes all users. If the team is not yet in the pipeline queue, add the information to the COT Epic in Jira.

Configure Git Authentication in WSL ​

  1. Inside WSL, run:

    bash
     git config --global credential.helper store

  2. Run git pull or git push. Enter your credentials once. Git will store them in ~/.git-credentials.

    DO NOT use Windows Git Credential Manager from WSL.

    Avoid this entirely, as it will cause repeated issues such as: /mnt/c/Program Files/Git/.../git-credential-manager.exe not found and/or git: 'credential-/mnt/c/...'.

    Use credential.helper=store unless your organization explicitly requires something else.

  3. Configure WSL Git signing.

    Replace <WINDOWS_USERNAME> with your Windows user name. Replace <THUMBPRINT> with the thumbprint you recorded earlier.

    bash
    git config --global user.signingkey <THUMBPRINT>
git config --global gpg.x509.program "/mnt/c/Users/<WINDOWS_USERNAME>/AppData/Local/Programs/smimesign/smimesign.exe"
git config --global gpg.format x509
git config --global commit.gpgsign true

  4. Configure your Git identity.

    bash
    git config --global user.email "<DoD Email Address>"
git config --global user.name "<Firstname Lastname>"

  5. Verify the Git email matches CAC identity.

    bash
    git config --list | grep -E 'user|gpg|commit'

    Confirm the output includes:

    • Your CAC-associated email address.
    • Your signing certificate thumbprint.
    • smimesign.exe for gpg.x509.program.
    • x509 for gpg.format.
    • true for commit.gpgsign.

  6. Test commit signing.

    bash
    git commit --allow-empty -m "test CAC signing"

    Expected behavior:

    • Windows PIN prompt appears.
    • Enter CAC PIN.
    • Commit succeeds.

  7. Verify the signed commit.

    bash
    git log --show-signature -1

    The commit should appear as Verified in GitLab.

Daily Workflow ​

After the initial configuration, your daily workflow is simple:

  • Insert your CAC.
  • Enter your PIN when prompted.
  • Continue working normally from WSL.

Related Content/References ​

Submit Requests to the Help Desk ​

Review Supporting Documentation ​

Powered By Platform One