Configure your GitLab Dedicated instance

Tier: Ultimate Offering: GitLab Dedicated

The instructions on this page guide you through configuring your GitLab Dedicated instance, including enabling and updating the settings for available functionality.

Any functionality in the GitLab application that is not controlled by the SaaS environment can be configured by using the Admin area.

Examples of SaaS environment settings include gitlab.rb configurations and access to shell, Rails console, and PostgreSQL console. These environment settings cannot be changed by tenants.

GitLab Dedicated Engineers also don’t have direct access to tenant environments, except for break glass situations.

note
An instance refers to a GitLab Dedicated deployment, whereas a tenant refers to a customer.

Configuration changes

Configuration change policy

Configuration changes requested with a support ticket are batched up and applied during your environment’s weekly four-hour maintenance window.

This policy does not apply to configuration changes made by a GitLab Dedicated instance admin using Switchboard.

To have a change considered for an upcoming weekly maintenance window, all required information must be submitted in full two business days before the start of the window.

A configuration change might not be applied during an upcoming weekly maintenance window, even if it meets the minimum lead time. If GitLab needs to perform high-priority maintenance tasks that run beyond the maintenance window, configuration changes will be postponed to the following week.

Changes requested with a support ticket cannot be applied outside of a weekly maintenance window unless it qualifies for emergency support.

Configuration changes in Switchboard

Switchboard empowers the user to make limited configuration changes to their GitLab Dedicated instance. As Switchboard matures further configuration changes will be made available.

To change or update the configuration of your GitLab Dedicated instance, use Switchboard following the instructions in the relevant section or open a support ticket with your request.

You can request configuration changes for some of the options originally specified during onboarding, or for any of the following optional features.

Configuration changes made with Switchboard can be applied immediately or deferred until your next scheduled weekly maintenance window.

When applied immediately, changes may take up to 90 minutes to be deployed to your environment. Individual changes are applied in the order they are saved, or you may choose to save several changes at once before applying them in one batch. After your change is deployed, you will receive an email notification. You might have to check your spam folder if it does not show up in your main email folder.

All users with access to view or edit your tenant in Switchboard will receive a notification for each change made. See how to manage Switchboard notification preferences.

note
You will only receive email notifications for changes made by a Switchboard tenant admin. Changes made by a GitLab Operator (e.g. a GitLab version update completed during a maintenance window) will not result in an email notification.

View the configuration change log

You can use the configuration change log to track the changes made to your GitLab Dedicated instance, including:

  • Configuration change: Name of the configuration setting that changed.
  • User: Email address of the user that made the configuration change. For changes made by a GitLab Operator, this value will appear as GitLab Operator.
  • IP: IP address of the user that made the configuration change. For changes made by a GitLab Operator, this value will appear as Unavailable.
  • Status: Whether the configuration change is initiated, in progress, completed, or deferred.
  • Start time: Start date and time when the configuration change is initiated, in UTC.
  • End time: End date and time when the configuration change is deployed, in UTC.

Each configuration change has a status:

  • Initiated: Configuration change is made in Switchboard, but not yet deployed to the instance.
  • In progress: Configuration change is currently being deployed to the instance.
  • Complete: Configuration change has been deployed to the instance.
  • Delayed: Initial job to deploy a change has failed and the change has not yet been assigned to a new job.

To view the configuration change log:

  1. Sign in to Switchboard.
  2. Select your tenant.
  3. At the top of the page, select Configuration change log.

Bring your own domain (BYOD)

You can add a custom hostname for your GitLab Dedicated instance. Optionally, you can also provide a custom hostname for the bundled container registry and KAS services.

Prerequisites:

  • Access to your domain’s server control panel to set up DNS records.

Set up DNS records

Custom domains require a:

  • CNAME record: Add a CNAME record that points your custom hostname to tenant_name.gitlab-dedicated.com. 

    gitlab.my-company.com.  CNAME  tenant_name.gitlab-dedicated.com

  • CAA record: If your domain has an existing CAA (Certification Authority Authorization) record, add a CAA record for Let’s Encrypt. This allows Let’s Encrypt to also issue certificates for your domain. 

    example.com.  IN  CAA 0 issue "pki.goog"
example.com.  IN  CAA 0 issue "letsencrypt.org"

    In this example, the CAA record defines Google Trust Services ("pki.goog") and Let’s Encrypt ("letsencrypt.org") as certificate authorities that are allowed to issue certificates for your domain.

Add a custom hostname

To add a custom hostname after your instance is created, submit a support ticket.

SMTP email service

You can configure an SMTP email service for your GitLab Dedicated instance.

To configure an SMTP email service, submit a support ticket with the credentials and settings for your SMTP server.

AWS Private Link allows users and applications in your VPC on AWS to securely connect to the GitLab Dedicated endpoint without network traffic going over the public internet.

To enable the Inbound Private Link:

  1. Open a support ticket. In the body of your support ticket, include the IAM principals for the AWS users or roles in your AWS organization that are establishing the VPC endpoints in your AWS account. The IAM principals must be IAM role principals or IAM user principals. GitLab Dedicated uses these IAM Principals for access-control. These IAM principals are the only ones able to set up an endpoint to the service.
  2. After your IAM Principals have been allowlisted, GitLab creates the Endpoint Service and communicates the Service Endpoint Name on the support ticket. The service name is generated by AWS upon creation of the service endpoint.
    • GitLab handles the domain verification for the Private DNS name, so that DNS resolution of the tenant instance domain name in your VPC resolves to the PrivateLink endpoint.
    • GitLab makes the Endpoint Service available in the Availability Zones you specified during the initial onboarding. If you did not specify any Availability Zones, GitLab randomly selects the Availability Zones IDs.
  3. In your own AWS account, create an Endpoint Interface in your VPC, with the following settings:
    • Service Endpoint Name: use the name provided by GitLab on the support ticket.
    • Private DNS names enabled: yes.
    • Subnets: choose all matching subnets.
  4. After you create the endpoint, use the instance URL provided to you during onboarding to securely connect to your GitLab Dedicated instance from your VPC, without the traffic going over the public internet.

Outbound private links allow your GitLab Dedicated instance and the hosted runners for GitLab Dedicated to securely communicate with services running in your VPC on AWS without exposing any traffic to the public internet.

This type of connection allows GitLab functionality to access private services:

  • For the GitLab Dedicated instance:

    • webhooks
    • import or mirror projects and repositories

  • For hosted runners:

    • custom secrets managers
    • artifacts or job images stored in your infrastructure
    • deployments into your infrastructure

Consider the following:

  • You can only establish private links between VPCs in the same region. Therefore, you can only establish a connection in the regions specified for your Dedicated instance.
  • The connection requires the Availability Zone IDs (AZ IDs) for the Availability Zones (AZs) in the regions that you selected during onboarding.
  • If you did not specify any AZs during onboarding to Dedicated, GitLab randomly selects the AZ IDs.

You can view the Reverse Private Link IAM Principal attribute in the Tenant Details section of Switchboard.

To enable an Outbound Private Link:

  1. Create the Endpoint service through which your internal service will be available to GitLab Dedicated. Provide the associated Service Endpoint Name on a new support ticket.
  2. Make sure you have configured a Network Load Balancer (NLB) for the endpoint service in the AZs to which your Dedicated instance was deployed. If you did not specify these during onboarding to Dedicated, you must either:
    • Submit a support ticket to request the AZ IDs required to enable the connection and ensure the NLB is enabled in those AZs.
    • Ensure the NLB is enabled in every AZ in the region.
  3. In your support ticket, GitLab will provide you with the ARN of an IAM role that will be initiating the connection to your endpoint service. You must ensure this ARN is included, or otherwise covered by other entries, in the list of “Allowed Principals” on the Endpoint Service, as described by the AWS documentation. Though it’s optional, you should you add it explicitly, allowing you to set Acceptance required to No so that Dedicated can connect in a single operation. If you leave Acceptance required as Yes, then you must manually accept the connection after Dedicated has initiated it.
  4. To connect to services using the Endpoint, the Dedicated services require a DNS name. Private Link automatically creates an internal name, but it is machine-generated and not generally directly useful. There are two options available:
    • In your Endpoint Service, enable Private DNS name, perform the required validation, and let GitLab know in the support ticket that you are using this option. If Acceptance Required is set to Yes on your Endpoint Service, also note this on the support ticket because Dedicated will need to initiate the connection without Private DNS, wait for you to confirm it has been accepted, and then update the connection to enable the use of Private DNS.
    • Dedicated can manage a private hosted zone (PHZ) within the Dedicated AWS account and alias DNS names to the endpoint, directing requests for those names to your endpoint service. These aliases are often referred to as PHZ entries. For more information, see Private hosted zones.

GitLab then configures the tenant instance to create the necessary Endpoint Interfaces based on the service names you provided. Any matching outbound connections made from the tenant instance are directed through the PrivateLink into your VPC.

Private hosted zones

You can use a private hosted zone (PHZ) if:

  • You have multiple DNS names or aliases that will be accessed using a single endpoint. For example, if you are running a reverse proxy to connect to more than one service in your environment.
  • The domain you want to use is not public and cannot be validated for use by private DNS.

To use private hosted zones, submit a support ticket. In the support ticket, provide a list of DNS names that should resolve to the endpoint service for the outbound private link. The list can be updated as needed.

When using your Dedicated instance’s domain as part of an alias, you must include two subdomains before the main domain. This is because:

  1. The first subdomain becomes the name of the PHZ.
  2. The second subdomain becomes the record entry for the alias.

For example:

  • This is a valid PHZ entry: subdomain2.subdomain1.<your-tenant-id>.gitlab-dedicated.com.
  • This is an invalid PHZ entry: subdomain1.<your-tenant-id>.gitlab-dedicated.com.

If you don’t use the Dedicated instance domain, the PHZ name and a PHZ entry in the format phz-entry.phz-name.com is still required.

Custom certificates

In some cases, the GitLab Dedicated instance can’t reach an internal service you own because it exposes a certificate that can’t be validated using a public Certification Authority (CA). In these cases, custom certificates are required.

Add a custom certificate with Switchboard

  1. Sign in to Switchboard.
  2. At the top of the page, select Configuration.
  3. Expand Custom Certificate Authorities.
  4. Select + Add Certificate.
  5. Paste the certificate into the text box.
  6. Select Save.
  7. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window.

Add a custom certificate with a Support Request

To request that GitLab add custom certificates when communicating with your services over PrivateLink, attach the custom public certificate files to your support ticket.

GitLab Dedicated limits the number of reverse PrivateLink connections to 10.

IP allowlist

GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. Once the IP allowlist has been enabled, when an IP not on the allowlist tries to access your instance an HTTP 403 Forbidden response is returned.

IP addresses that have been added to your IP allowlist can be viewed on the Configuration page in Switchboard. You can add or remove IP addresses from your allowlist with Switchboard or a support request.

Add an IP to the allowlist with Switchboard

  1. Sign in to Switchboard.
  2. At the top of the page, select Configuration.
  3. Expand Allowed Source List Config / IP allowlist.
  4. Turn on the Enable toggle.
  5. Select Add Item.
  6. Enter the IP address and description. To add another IP address, repeat steps 5 and 6.
  7. Select Save.
  8. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window. After the changes are applied, the IP addresses are added to the IP allowlist for your instance.

Add an IP to the allowlist with a Support Request

Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your support ticket. The IP addresses are then added to the IP allowlist for your instance.

Enable OpenID Connect for your IP allowlist

Using GitLab as an OpenID Connect identity provider requires internet access to the OpenID Connect verification endpoint.

To enable access to the OpenID Connect endpoint while maintaining your IP allowlist:

  • In a support ticket, request to allow access to the OpenID Connect endpoint.

The configuration is applied during the next maintenance window.

SAML

You can configure SAML single sign-on (SSO) for your GitLab Dedicated instance.

The following SAML SSO options are available:

Prerequisites:

  • You must set up the identity provider (IdP) before you can configure SAML for GitLab Dedicated.
  • To configure GitLab to sign SAML authentication requests, you must create a private key and public certificate pair for your GitLab Dedicated instance.

Activate SAML with Switchboard

To activate SAML for your GitLab Dedicated instance:

  1. Sign in to Switchboard.
  2. At the top of the page, select Configuration.
  3. Expand SAML Config.
  4. Turn on the Enable toggle.
  5. Complete the required fields:
    • SAML label
    • IdP cert fingerprint
    • IdP SSO target URL
  6. Optional. To configure users based on SAML group membership, complete the following fields:
    • SAML group attribute
    • Admin groups
    • Auditor groups
    • External groups
    • Required groups
  7. Optional. To configure SAML request signing, complete the following fields:
    • Name identifier format
    • Attribute statements
    • Security
  8. Select Save.
  9. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window.
  10. Optional. To use group sync, configure the SAML group links.
  11. To verify the SAML configuration is successful:
    • Check that the SSO button description is displayed on your instance’s sign-in page.
    • Go to the metadata URL of your instance (https://INSTANCE-URL/users/auth/saml/metadata). This page can be used to simplify much of the configuration of the identity provider, and manually validate the settings.

Activate SAML with a Support Request

To activate SAML for your GitLab Dedicated instance:

  1. To make the necessary changes, include the desired SAML configuration block for your GitLab application in your support ticket. At a minimum, GitLab needs the following information to enable SAML for your instance:
    • IDP SSO Target URL
    • Certificate fingerprint or certificate
    • NameID format
    • SSO login button description 
    "saml": {
  "attribute_statements": {
      //optional
  },
  "enabled": true,
  "groups_attribute": "",
  "admin_groups": [
    // optional
  ],
  "idp_cert_fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
  "idp_sso_target_url": "https://login.example.com/idp",
  "label": "IDP Name",
  "name_identifier_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
  "security": {
    // optional
  },
  "auditor_groups": [
    // optional
  ],
  "external_groups": [
    // optional
  ],
  "required_groups": [
    // optional
  ],
}
  2. After GitLab deploys the SAML configuration to your instance, you are notified on your support ticket.
  3. To verify the SAML configuration is successful:
    • Check that the SSO login button description is displayed on your instance’s login page.
    • Go to the metadata URL of your instance (https://INSTANCE-URL/users/auth/saml/metadata). This page can be used to simplify much of the configuration of the identity provider, as well as manually validate the settings.

Request signing

If SAML request signing is desired, a certificate must be obtained. This certificate can be self-signed which has the advantage of not having to prove ownership of an arbitrary Common Name (CN) to a public Certificate Authority (CA). If you choose to enable SAML request signing, the manual steps below will need to be completed before you are able to use SAML, since it requires certificate signing to happen. To enable SAML request signing, indicate on your SAML support ticket that you want request signing enabled. GitLab works with you on sending the Certificate Signing Request (CSR) for you to sign. Alternatively, the CSR can be signed with a public CA. After the certificate is signed, GitLab adds the certificate and its associated private key to the security section of the SAML configuration. Authentication requests from GitLab to your identity provider can then be signed.

SAML groups

With SAML groups you can configure GitLab users based on SAML group membership.

To enable SAML groups, add the required elements to the SAML configuration block you provide in your support ticket.

Group sync

With group sync, you can sync users across identity provider groups to mapped groups in GitLab.

To enable group sync:

  1. Add the required elements to the SAML configuration block you provide in your support ticket.
  2. Configure the Group Links.

Add users to an instance

Administrators can add Switchboard users to their GitLab Dedicated instance. There are two types of users:

  • Read only: Users can only view instance data.
  • Admin: Users can edit the instance configuration and manage users.

To add a new user to your GitLab Dedicated instance:

  1. From the Tenants page, select Manage next to the tenant instance.
  2. From the top of the page, select Users.
  3. Select New user.
  4. Enter the Email and select a Role for the user.
  5. Select Create.

An invitation to use Switchboard is sent to the user.

Manage notification preferences

You can specify whether you want to receive email notifications from Switchboard. You will only receive notifications after you:

  • Receive an email invitation and first sign in to Switchboard.
  • Set up a password and two-factor authentication (2FA) for your user account.

To manage your own email notification preferences:

  1. From any page, open the dropdown next to your user name.
  2. To stop receiving email notifications, select Toggle email notifications off.
  3. To resume receiving email notifications, select Toggle email notifications on.

You will see an alert confirming that your notification preferences have been updated.

Switchboard Tenant Admins can also manage email notifications for other users with access to their organization’s tenant:

  1. From the Users page, open the dropdown in the Email notifications column next to the user’s email.
  2. To turn off email notifications for that user, select No.
  3. To turn on email notifications for that user, select Yes.

You will see an alert confirming that your notification preferences have been updated.

Access to application logs

GitLab application logs are delivered to an S3 bucket in the GitLab tenant account, which can be shared with you. Logs stored in the S3 bucket are retained indefinitely, until the 1 year retention policy is fully enforced. GitLab team members can view more information in this confidential issue: https://gitlab.com/gitlab-com/gl-infra/gitlab-dedicated/team/-/issues/483.

To gain read only access to this bucket:

  1. Open a support ticket with the title “Customer Log Access”. In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that are fetching the logs from S3.
  2. GitLab then informs you of the name of the S3 bucket. Your nominated users/roles are then able to list and get all objects in the S3 bucket.

You can use the AWS CLI to verify that access to the S3 bucket works as expected.

Bucket contents and structure

The S3 bucket contains a combination of infrastructure logs and application logs from the GitLab log system. The logs in the bucket are encrypted using an AWS KMS key that is managed by GitLab. If you choose to enable BYOK, the application logs are not encrypted with the key you provide.

The logs in the S3 bucket are organized by date in YYYY/MM/DD/HH format. For example, there would be a directory like 2023/10/12/13. That directory would contain the logs from October 12, 2023 at 1300 UTC. The logs are streamed into the bucket with Amazon Kinesis Data Firehose.

Troubleshooting

If you have trouble establishing a connection after the Outbound Private Link has been set up, there are a few things in your AWS infrastructure that could be the cause of the problem. The specific things to check will vary based on the unexpected behavior you’re seeking to fix. Things to check include:

  • Ensure that cross-zone load balancing is turned on in your Network Load Balancer (NLB).
  • Ensure that the Inbound Rules section of the appropriate Security Groups permits traffic from the correct IP ranges.
  • Ensure that the inbound traffic is mapped to the correct port on the Endpoint Service.
  • In Switchboard, expand Reverse Private Link Config and confirm that the details appear as you expect.
  • Ensure that you have allowed requests to the local network from webhooks and integrations.