Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-GIT-TAG(1)                     HEE Tools                     HEE-GIT-TAG(1)

NAME
       hee-git-tag - a GPG-signed git tag with the key that is really yours

SYNOPSIS
              hee git tag NAME -m MESSAGE [COMMIT] [--key ID] [--push] [--yes]
              hee git tag --show-key
              hee git tag help

DESCRIPTION
              Creates an annotated, GPG-signed tag (`git tag -s`) and, with --push,
              pushes exactly that ref. The point of the tool is the key choice: plain
              `git tag -s` asks gpg for a key whose uid matches user.email, and in this
              org user.email is the shared dev@tcos.us from the dotfiles gitconfig --
              no secret key carries that uid, so the first prod promote ended with
              "gpg: skipped Spencer Butler <dev@tcos.us>: No secret key" (2026-09-06).

              Dry run by default: prints the key, the tag, the commit and the message
              and changes nothing. --yes creates the tag; --push pushes it.

FILES
              ~/.hee/index/_.yaml    SOA anchor; only `host:` is read, for the tie-break

EXIT STATUS
              0 OK, 2 CRITICAL (no key, ambiguous key, git or gpg failed), 3 UNKNOWN
              (gpg missing, not a git repo).

EXAMPLES
              hee git tag --show-key
              hee git tag v1.2.0 -m "release 1.2.0" --push

              Not marked "# ci": --show-key needs a signing key configured (a CI runner
              has none) and tagging signs and pushes. Both are host/identity state, not
              a self-contained run.

              hee git tag prod/tcos-www/20260906T0806Z -m "prod promotion: tcos.us" e7beec0 --yes --push
              hee git tag --show-key

SEE ALSO
              hee-git-merge(1), hee-ver(1), hee-contract-review(1)

KEY SELECTION
              1. --key ID, if given (any form gpg accepts).
              2. Otherwise $HEE_SIGN_KEY, if set. This is how `hee release -promote`,
                 which calls this tool itself, is told which key to use when the
                 keyring holds several: HEE_SIGN_KEY=<id> hee release -promote -yes.
                 Never a default -- unset means step 3.
              3. Otherwise gpg's own `default-key` from gpg.conf (read with
                 `gpgconf --list-options gpg`; gpg has no switch that prints it), if it
                 names a usable secret key here -- the last one that does, as gpg
                 itself picks. This is the one place to say "my signing key" for both
                 gpg and hee: `default-key 2A361A96A7A0FBA9` in ~/.gnupg/gpg.conf.
              4. Otherwise the secret keys in the caller's own keyring that can sign,
                 are not expired or revoked, and carry ultimate trust (the keys this
                 person generated here, as opposed to imported ones).
              5. If more than one remains, the one whose uid email host is this
                 machine per the SOA anchor (~/.hee/index/_.yaml `host:`), e.g.
                 spencer@kiosk.lab.tcos.us on kiosk.lab.tcos.us.
              6. Still more than one, or none: CRITICAL with the candidates listed --
                 say --key (or set HEE_SIGN_KEY). Never a guess.

              Nothing is read from gitconfig. The chosen key id is printed on every
              run so the record says which key signed.

                                                                 HEE-GIT-TAG(1)