Detailed Gitsign Usage

Configuration

File config

Gitsign can be configured with a standard git-config file. For example, to set the Fulcio option for a single repo:

$ git config --local gitsign.connectorID https://accounts.google.com
$ cat .git/config
[gitsign]
        connectorID = https://accounts.google.com

The following config options are supported:

OptionDefaultDescription
fulciohttps://fulcio.sigstore.devAddress of Fulcio server
logPathPath to log status output. Helpful for debugging when no TTY is available in the environment.
clientIDsigstoreOIDC client ID for application
issuerhttps://oauth2.sigstore.dev/authOIDC provider to be used to issue ID token
redirectURLOIDC Redirect URL
rekorhttps://rekor.sigstore.devAddress of Rekor server
connectorIDOptional Connector ID to auto-select to pre-select auth flow to use. For the public sigstore instance, valid values are:
- https://github.com/login/oauth
- https://accounts.google.com
- https://login.microsoftonline.com

Environment Variables

Environment VariableSigstore
Prefix
DefaultDescription
GITSIGN_CREDENTIAL_CACHEOptional path to gitsign-credential-cache socket.
GITSIGN_CONNECTOR_IDOptional Connector ID to auto-select to pre-select auth flow to use. For the public sigstore instance, valid values are:
- https://github.com/login/oauth
- https://accounts.google.com
- https://login.microsoftonline.com
GITSIGN_FULCIO_URLhttps://fulcio.sigstore.devAddress of Fulcio server
GITSIGN_LOGPath to log status output. Helpful for debugging when no TTY is available in the environment.
GITSIGN_OIDC_CLIENT_IDsigstoreOIDC client ID for application
GITSIGN_OIDC_ISSUERhttps://oauth2.sigstore.dev/authOIDC provider to be used to issue ID token
GITSIGN_OIDC_REDIRECT_URLOIDC Redirect URL
GITSIGN_REKOR_URLhttps://rekor.sigstore.devAddress of Rekor server

For environment variables that support Sigstore Prefix, the values may be provided with either a GITSIGN_ or SIGSTORE_ prefix - e.g. GITSIGN_CONNECTOR_ID or SIGSTORE_CONNECTOR_ID. If both environment variables are set, GITSIGN_ prefix takes priority.

Signing a Commit

After installing Gitsign and configuring Git to use it as a signer application for your project (or globally), you can sign commits as usual with git commit -S (or git config --global commit.gpgsign true to enable signing for all commits).

$ git commit --message="Signed commit"
Your browser will now be opened to:
https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&...
[main 040b9af] Signed commit

Commits can then be verified using git verify-commit:

$ git verify-commit HEAD
tlog index: 2801760
gitsign: Signature made using certificate ID 0xf805288664f2e851dcb34e6a03b1a5232eb574ae | CN=sigstore-intermediate,O=sigstore.dev
gitsign: Good signature from [billy@chainguard.dev]
Validated Git signature: true
Validated Rekor entry: true

Signing Tags

You can sign tags with git tag -s (or git config --global tag.gpgsign true to enable signing for all tags).

$ git tag v0.0.1
Your browser will now be opened to:
https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&...

This will redirect you through the Sigstore Keyless flow to authenticate and sign the tag.

Tags can then be verified using git verify-tag:

$ git verify-tag v0.0.1
tlog index: 2802961
gitsign: Signature made using certificate ID 0xe56a5a962ed59f9e3730d6696137eceb8b4ee8ea | CN=sigstore-intermediate,O=sigstore.dev
gitsign: Good signature from [billy@chainguard.dev]
Validated Git signature: true
Validated Rekor entry: true

Debugging

If there is a problem during signing, you may receive an error similar to the following:

error: gpg failed to sign the data
fatal: failed to write commit object

By default, gitsign will try and write to your terminal if there is a TTY available. If you are running in an environment where there is not a TTY, you can use the GITSIGN_LOG environment variable to tee logs into a readable location for debugging.

Edit this page on GitHub Updated at Mon, Nov 28, 2022