gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-06-24 13:15:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add ssh commit signing to docs of 1.25-dev (#241)

Browse Source 
Documentation for my changes to ssh commit signing in <https://github.com/go-gitea/gitea/pull/34341>.

* Renames "GPG Commit Signatures" to "GPG/SSH Commit Signatures", since the url is called just signing and creating a new page would duplicate a lot
* _"The default option and repository specific signing keys are not supported for ssh keys"_
   * the original draft implementation did support this for ssh keys
   * this warning should avoid people expecting this gitconfig style things to work for ssh keys, since verifying is disabled in this case (e.g. pre 1.25 undocumented behavior preserved).

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/241
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: Christopher Homberger <christopher.homberger@web.de>
Co-committed-by: Christopher Homberger <christopher.homberger@web.de>
This commit is contained in:
Christopher Homberger
2025-07-28 20:37:52 +00:00
committed by Lunny Xiao
parent 641977c93a
commit e8a6c4281d
1 changed files with 45 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/administration/signing.md
View File

@@ -6,12 +6,14 @@ aliases:
- /en-us/signing
---
# GPG Commit Signatures
# GPG/SSH Commit Signatures
Gitea will verify GPG commit signatures in the provided tree by
Gitea will verify gpg/ssh commit signatures in the provided tree by
checking if the commits are signed by a key within the Gitea database,
or if the commit matches the default key for Git.
Additionally Gitea will verify commits signed by ssh keys, which public keys are part of [`TRUSTED_SSH_KEYS`](#general-configuration).
Keys are not checked to determine if they have expired or revoked.
Keys are also not checked with keyservers.
@@ -46,6 +48,11 @@ for GPG - in particular it is probably advisable to only install a
signing secret subkey without the master signing and certifying secret
key.
## Installing and generating a SSH key for Gitea
You can run `ssh-keygen -t ed25519 -f gitea-signing-key` to generate the private/public keypair for commit signing without any password. Usually you would store the key next to the gitea configuration, then point `SIGNING_KEY` to the generated public key `/path/to/gitea-signing-key.pub`. Gitea generates all its commits using the server `git` command at present - and therefore the server `ssh-keygen` will be used for
signing (if configured.)
## General Configuration
Gitea's configuration for signing can be found with the
@@ -65,16 +72,41 @@ MERGES = pubkey, twofa, basesigned, commitssigned
...
```
---
For SSH commit signing, you need to specify the `SIGNING_FORMAT` to `ssh` instead of the default `openpgp`. `SIGNING_NAME` and `SIGNING_EMAIL` are required for verifing the signatures.
This looks like this:
```ini
...
[repository.signing]
SIGNING_KEY = /path/to/gitea-signing-key.pub
SIGNING_NAME =
SIGNING_EMAIL =
SIGNING_FORMAT = ssh
INITIAL_COMMIT = always
CRUD_ACTIONS = pubkey, twofa, parentsigned
WIKI = never
MERGES = pubkey, twofa, basesigned, commitssigned
...
```
- `/path/to/gitea-signing-key` is expected to be the private key for `/path/to/gitea-signing-key.pub` [see here how to generate a new ssh keypair](#installing-and-generating-a-ssh-key-for-gitea).
- `TRUSTED_SSH_KEYS = ssh-<algorithm> <key>` or `TRUSTED_SSH_KEYS = ssh-<algorithm> <key1>, ssh-<algorithm> <key2>` can be used for rotating the global ssh signing key to continue verifying commits signed by the previous keys.
### `SIGNING_KEY`
The first option to discuss is the `SIGNING_KEY`. There are three main
options:
- `none` - this prevents Gitea from signing any commits
- `default` - Gitea will default to the key configured within `git config`
- `default` - Gitea will default to the gpg key configured within `git config`
- `KEYID` - Gitea will sign commits with the gpg key with the ID
`KEYID`. In this case you should provide a `SIGNING_NAME` and
`SIGNING_EMAIL` to be displayed for this key.
- `/path/to/gitea-signing-key.pub` - Gitea will sign commits with the ssh key without the `.pub` suffix `/path/to/gitea-signing-key`. In this case you should provide a `SIGNING_NAME` and
`SIGNING_EMAIL` to be displayed for this key and set `SIGNING_FORMAT` to `ssh`.
The `default` option will interrogate `git config` for
`commit.gpgsign` option - if this is set, then it will use the results
@@ -97,6 +129,10 @@ Related home files for git command (like `.gnupg`) should also be put in Gitea's
If you like to keep the `.gnupg` directory outside of `{[git].HOME_PATH}/`, consider setting the `$GNUPGHOME` environment variable to your preferred location, otherwise Gitea will use the gpg keys only under `{[git].HOME_PATH}/.gnupg`.
:::
:::warning
The default option and repository specific signing keys are not supported for ssh keys
:::
### `INITIAL_COMMIT`
This option determines whether Gitea should sign the initial commit
@@ -168,3 +204,9 @@ In cases where there is a repository specific key this can be obtained from:
```sh
/api/v1/repos/:username/:reponame/signing-key.gpg
```
For ssh commit signing the default ssh public key can be obtained via the API at:
```sh
/api/v1/signing-key.pub
```