Preparing GitLab for GPG key provisioning

A Git Signing Connector authenticates to GitLab with a personal access token (PAT). Code Sign Manager uses the token to find each user's GitLab account by email address, and to add, check, and revoke GPG keys on that user's behalf. Because these actions affect other users' accounts, the token must belong to a GitLab administrator.

Before you create the connector, prepare GitLab as described in this topic. Then Create a Git Signing Connector.

Requirements

• GitLab Self-Managed or GitLab Dedicated. The token must belong to a GitLab administrator, because adding and revoking GPG keys for other users requires administrator access. GitLab.com doesn't give customers administrator access, so it isn't supported.
• HTTPS at the root of the host name. GitLab must be served over HTTPS at an address such as https://gitlab.example.com. Servers that run GitLab under a sub-path aren't supported.
• A trusted certificate. The Trust Protection Foundation servers must trust GitLab's TLS certificate and be able to reach its certificate revocation list (CRL).
• Matching email addresses. Each user's GitLab account must have an email address that matches the email address on their GPG key. The key's email address comes from the E-mail setting of the per-user GPG Environment Template. Exactly one GitLab account can match each address.

Create the personal access token

Sign in to GitLab with an administrator account, and create a personal access token. Code Sign Manager can't limit what a token is allowed to do, so follow the principle of least privilege when you choose the token type and its permissions.

• Fine-grained token (recommended). Grants only the permissions the connector needs. Fine-grained tokens are available in GitLab 19.2 and later.
• Legacy token. Available on GitLab versions earlier than 19.2 as well as later ones, but its scopes grant much broader access than the connector needs. Decide whether that is acceptable for your organization.

Fine-grained token permissions

For GitLab's instructions, see Fine-grained personal access tokens in the GitLab documentation. Under Add resource permissions, grant only these permissions. The Tab column shows where GitLab lists each permission.

Resource	Permission	Tab	Used to
User	Read	User	Confirm that the token belongs to an administrator.
User	Read	Global	Find each user's GitLab account by email address.
GPG Key	Read	User	Check whether a user's key is already in GitLab.
GPG Key	Create	Global	Upload users' GPG public keys.
GPG Key	Revoke	Global	Revoke keys in GitLab when you revoke them from the Environment's Instances tab.

The token doesn't need any group or project resources, so you can ignore the Group and project access setting. Leave Use token to act on behalf of other users (sudo) cleared.

GitLab checks both the token's permissions and the token owner's own access for every request. The token works only while its owner remains a GitLab administrator.

Legacy token scopes

For GitLab's instructions, see Personal access tokens in the GitLab documentation. Select these scopes:

• api: required. Adding and revoking other users' GPG keys requires write access, which read_user and read_api don't provide.
• admin_mode: required only if Admin Mode is enabled on your GitLab instance.

Don't select sudo. The connector never acts as another user.

Because the api scope grants full API access with the administrator's privileges, keep the token's expiration as short as you can manage.

Expiration

For either token type, set the shortest expiration your organization can manage.

Code Sign Manager doesn't track the token's expiration date or warn you before it expires. Set a reminder to rotate the token before it expires.

Rotate the token

When the token expires or is revoked, Code Sign Manager can't connect to GitLab:

• Key uploads fail and show Failed on the Environment's Instances tab. These uploads aren't retried automatically.
• Saving the connector fails with Token is unauthorized.

Replace the token before it expires to avoid failed uploads.

To rotate the token

1. In GitLab, create a new personal access token with the same permissions. See Create the personal access token.
2. In Trust Protection Foundation Configuration Console, expand the Code Sign node, and then click Git Signing Connectors.
3. Select the connector, and then click Properties in the Actions panel.
4. Click the Credential DN drop-down list. With the current credential selected, the GitLab PAT panel appears.
5. Enter the new token in GitLab PAT, and then click Save.
6. Click OK. The connection is tested with the new token before the connector is saved.
7. In GitLab, revoke the old token.
8. Repush any keys that failed while the token was invalid. See Repush failed keys.

If several connectors share the same credential, updating the credential updates all of them.