Configure Commit Signing on Mac with Your CAC

Overview

This article explains what commit signing is and how to configure your Mac to sign Git commits with your CAC.

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.

Prerequisites

Before you begin:

• Install the required DoD root and intermediate certificates on your computer. For instructions, see MilitaryCAC DoD Certificates Guide.
• Verify that your CAC contains a CDS certificate with an associated email address.
  • If your CAC does not include an email address, update your CAC at a local ID Card office using the ID Card Office Locator.
  • If you cannot update your CAC, use GPG commit signing instead by following our Commit Signing with GPG guides.

Identify Your CAC Signing Certificate

Before you configure Git commit signing, identify the Digital Signature certificate on your CAC and record its certificate ID. You'll use this ID as your signing key later in this procedure.

1. Install Homebrew by following the instructions on the Homebrew website.

2. Install OpenSC.

   brew install opensc

3. List the certificates on your CAC.

   pkcs15-tool --list-certificates

4. Find the X.509 Certificate [Certificate for Digital Signature] entry and record the third value in the Encoded serial field.

   • For example, if the output shows: Encoded serial: 02 03 123456, then record 123456.

5. Install smimesign by following the installation instructions on GitHub.

6. List the available signing certificates.

   smimesign --list-keys

7. Find the certificate whose S/N matches the encoded serial number you recorded. The S/N value may omit leading zeros (for example, 01234567 becomes 1234567).

         ID: 1234567890abcdefghijklmnopea7de1908d74b0
         S/N: 123456
   Algorithm: SHA256-RSA
   Validity: 2025-01-07 00:00:00 +0000 UTC - 2026-01-02 23:59:59 +0000 UTC
      Issuer: CN=DOD ID CA-72,OU=DoD+OU=PKI,O=U.S. Government,C=US
   Subject: CN=SKYWALKER.LUKE.901082350304,OU=DoD+OU=PKI+OU=CONTRACTOR,O=U.S. Government,C=US
      Emails: luke.skywalker.ctr@us.af.mil

8. Verify the following:

   • The S/N matches the encoded serial number you recorded.
   • The Emails field contains the email address associated with your CAC.
   • Record the ID value. You will use it as your signing key in the next section.

Confirm Your GitLab Commit Email Address

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

1. Open User Settings > Emails .
2. Find the email address marked with the icon.
3. Verify that the commit email matches the email address on your CAC's CDS certificate.

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

Configure Git to use your CAC certificate when signing commits. If you already have Git settings for other accounts or repositories, adjust these steps as needed.

Replace the example email you see here with the email address associated with your CAC. Replace <SIGNING_KEY> with the certificate ID you recorded in the previous section.

Choose the configuration scope that best fits your needs:

• Repository – Applies only to one Git repository. Navigate to the repository and run:

  git config user.email john.doe.ctr@us.af.mil
  git config user.signingkey $signing_key
  git config gpg.x509.program smimesign
  git config gpg.format x509
  git config commit.gpgsign true

  Note: Repository settings override folder and global settings.

• Folder – Applies to all Git repositories in a specific folder. Run the following commands:

  git config --file=.gitconfig-partybus --add user.email john.doe.ctr@us.af.mil
  git config --file=.gitconfig-partybus --add user.signingkey $signing_key
  git config --file=.gitconfig-partybus --add gpg.x509.program smimesign
  git config --file=.gitconfig-partybus --add gpg.format x509
  git config --file=.gitconfig-partybus --add commit.gpgsign true # set if you do not want to set -S flag for commits
  git config --global --add includeif.gitdir:~/path/to/folder/.path .gitconfig-partybus

  Replace ~/path/to/folder with the path to the folder containing your repositories.

• Global – Applies to all Git repositories on your computer. Run the following commands:

  git config --global user.email john.doe.ctr@us.af.mil
  git config --global user.signingkey $signing_key
  git config --global gpg.x509.program smimesign
  git config --global gpg.format x509
  git config --global commit.gpgsign true

1. Configure your Git signing settings. Replace <SIGNING_KEY> with the ID value identified in the previous section.

   git config --global user.signingkey <SIGNING_KEY> 
   git config --global gpg.x509.program smimesign 
   git config --global gpg.format x509
   git config --global commit.gpgsign true

2. Verify the configuration.

   git config --global --get user.signingkey 
   git config --global --get commit.gpgsign

Using Commit Signing

Before you configure Git commit signing, make sure you have:

• The email address associated with your CAC's CDS certificate.
• The certificate ID ($signing_key) identified in the previous section.

Verify Git Commit Signing

1. Open a terminal in a configured repository.

2. Verify your Git configuration:

   git config --list

3. Confirm the output includes:

   • user.email matches the email associated with your CAC.

   • user.signingkey matches the ID you recorded in the previous section.

   • gpg.x509.program is smimesign

   • gpg.format is x509

   • commit.gpgsign is true

   Git Configuration Precedence:

   Git uses the last listed value when the same configuration setting appears more than once.
   Configuration precedence is:

   1. Global
   2. Folder (includeif configuration)
   3. Repository

   In the example above, user.email is listed twice. ejay.tumacder.ctr@us.af.mil is listed second, making it take precedence over etumacder@revacomm.com.

   Repository settings take precedence over folder and global settings.

4. Create a commit. Git will prompt you to enter your CAC PIN.

5. Verify that the commit was signed:

   git log --show-signature

Commits should now appear as Verified in GitLab. If commits are not marked Verified, verify your Git configuration and confirm that your GitLab commit email matches your CAC certificate email address.

Troubleshooting

CAC PIN prompts fail after reboot or reconnecting your CAC

If commit signing stops working after restarting your computer or reconnecting your CAC, restart the GPG agent:

gpgconf --kill all

After restarting the agent, try signing a commit again.

Multiple PIN or certificate trust prompts appear during signing

If you use a non-GUI PIN entry method (such as pinentry-curses), the first commit signing attempt may prompt you multiple times for your CAC PIN and certificate trust.

To initialize authentication and reduce repeated prompts, run:

gpgsm --status-fd=2 -bsau "$signing_key"

After completing the prompts, try signing a commit again.

Related Content/References

Submit Requests to the Help Desk

• Request GitLab commit sign email validation

Review Supporting Documentation

• Learn how to use x509-signed commits in GitLab projects
• Learn how to install Homebrew
• Access S/MIME Sign on GitHub
• Download the S/MIME signing tool
• Review the OpenSC Wiki
• Review the Git configuration documentation
• Install DoD certificates
• Locate an ID card office