GitLab Dedicated encryption

{{< details >}}

• Tier: Ultimate
• Offering: GitLab Dedicated

{{< /details >}}

GitLab Dedicated encrypts all data at rest and in transit using Advanced Encryption Standard (AES) 256-bit encryption with the AWS Key Management Service (KMS).

Encryption at rest

All data at rest uses envelope encryption, where your data is protected by multiple layers of encryption keys.

Each service implements encryption differently:

In this envelope encryption system:

• Your data is encrypted with data encryption keys.
• The data encryption keys themselves are encrypted with encryption keys.
• Encrypted data encryption keys are stored alongside your encrypted data.
• Encryption keys remain in the Key Management Service and are never exposed in unencrypted form.
• All encryption keys are protected by hardware security modules.

This envelope encryption process works by having KMS derive the data encryption keys specifically for each encryption operation. The data encryption key (DEK) directly encrypts your data, while the DEK itself is encrypted by the encryption key, creating a secure envelope around your data.

Encryption in transit

All data in transit uses Transport Layer Security (TLS) with strong cipher suites to protect data as it moves between services and across network connections.

Each service uses TLS:

TLS certificates are generated and managed by default. You can optionally configure custom TLS certificates to use your organization's certificates instead. For more information, see custom certificate authorities for external services.

Encryption options

The following encryption options are available:

• GitLab-managed encryption (default): GitLab handles all encryption setup with no configuration required.
• Customer-managed encryption: You provide and control your own encryption keys for additional control over key management and access policies.

GitLab-managed encryption

By default, GitLab handles all encryption setup for your instance. No setup is required and GitLab configures encryption across all services automatically.

The keys are protected by AWS Hardware Security Module (HSM) based security controls that prevent unauthorized access to your encryption keys and ensure your data remains encrypted.

Customer-managed encryption

[!warning] Customer-managed encryption keys must be configured during instance onboarding. Once enabled, they cannot be disabled or changed after provisioning.

Customer-managed encryption keys give you direct control over the keys that protect your data at rest.

You create and manage AWS KMS keys in your own AWS account, then configure them when you create your instance. GitLab uses your keys to encrypt data, but you retain full control over key access policies, rotation, and lifecycle management through your AWS account.

You can configure keys at different levels:

• One key for all services across all regions: Use a single multi-region key with replicas in each region where you have Geo instances.
• One key for all services within each region: Use separate keys for each region where you have Geo instances.
• Per-service keys per region: Use different keys for different services (backup, EBS, RDS, S3, advanced search) within each region.

Create encryption keys

Due to key rotation requirements, your instance only supports keys where AWS generates the cryptographic key material (the AWS_KMS origin type), rather than keys where you import your own key material. For more information, see create multi-region primary keys.

Prerequisites:

• You must have received your GitLab AWS account ID from the GitLab Dedicated account team.

To create your own encryption keys:

1. Sign in to the AWS Management Console and go to the KMS service.

2. Select the region where you want to create a key.

3. Select Create key.

4. In the Configure key section:

   • For Key type, select Symmetric.
   • For Key usage, select Encrypt and decrypt.
   • Under Advanced options:
     • For Key material origin, select AWS_KMS.
     • For Regionality, select Multi-Region key.

5. Enter an alias, description, and tags for your key.

6. Select the IAM users and roles that can administer the key.

7. Optional. Clear Allow key administrators to delete this key to prevent accidental deletion.

8. On the Define key usage permissions page, in the Other AWS accounts section, enter the GitLab AWS account ID provided by your account team.

9. Verify the KMS key policy matches the following example. Replace placeholder values with your account IDs and usernames. Additional restrictions beyond this policy are not supported.

   [!note] Remove any additional conditions or restrictions, including those that AWS might auto-generate like kms:GrantIsForAWSResource.

{
    "Version": "2012-10-17",
    "Id": "byok-key-policy",
    "Statement": [
        {
            "Sid": "Enable IAM User Permissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<CUSTOMER-ACCOUNT-ID>:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow access for Key Administrators",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<CUSTOMER-ACCOUNT-ID>:user/<CUSTOMER-USER>"
                ]
            },
            "Action": [
                "kms:Create*",
                "kms:Describe*",
                "kms:Enable*",
                "kms:List*",
                "kms:Put*",
                "kms:Update*",
                "kms:Revoke*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Delete*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ScheduleKeyDeletion",
                "kms:CancelKeyDeletion",
                "kms:ReplicateKey",
                "kms:UpdatePrimaryRegion"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow use of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<GITLAB-ACCOUNT-ID>:root"
                ]
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow attachment of persistent resources",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<GITLAB-ACCOUNT-ID>:root"
                ]
            },
            "Action": [
                "kms:CreateGrant",
                "kms:ListGrants",
                "kms:RevokeGrant"
            ],
            "Resource": "*"
        }
    ]
}

Create replica keys

Create replica keys when you want to use the same encryption key across multiple Geo instances in different regions. For more information, see create multi-region replica keys.

Prerequisites:

• You must have created a multi-region primary key.
• You must have additional Geo instances in different AWS regions.

To create replica keys:

1. In the AWS KMS console, choose the key you previously created.
2. Select the Regionality tab.
3. In the Related multi-Region keys section, select Create new replica keys.
4. Choose the AWS Regions where you have additional Geo instances.
5. Keep the original alias or enter a different alias for the replica key.
6. Optional. Enter a description and add tags.
7. Select the Identity and Access Management (IAM) users and roles that can administer the replica key.
8. Optional. Select or clear the Allow key administrators to delete this key checkbox.
9. On the Define key usage permissions page, verify that the GitLab AWS account is listed under Other AWS accounts.
10. Review the policy and your settings.
11. Select Finish.