GitLab Servers

Register the GitLab servers your organization uses so that members can connect their GitLab accounts and run workflows from projects hosted on them. This includes self-managed GitLab instances on private networks as well as GitLab.com.

How the GitLab Integration Works

A GitLab server is registered once per organization. Each member then connects their own GitLab account to that server under Account > Connections, and ACTIVATE reads repositories as that member. A member only ever sees the projects their GitLab account can see; registering a server grants no access by itself.

Members can connect in one of two ways, depending on how the server is registered:

• OAuth: you register an OAuth application on the GitLab server and enter its Application ID and Application secret. Members click Connect and authorize ACTIVATE in GitLab.
• Personal access tokens: you allow tokens and members paste a personal access token with the read_api scope.

At least one method is required. A server can offer both.

Once a member is connected, they can:

• add remote workflows whose YAML lives in a GitLab project
• reference GitLab projects from the uses field of a workflow step (see jobs.<job>.steps[*].uses)
• run a project's workflow.yaml directly with pw workflows run https://gitlab.example.com/group/project@main
• check out private projects on a cluster with the checkout action

Registering a GitLab Server

Create an OAuth Application in GitLab

Skip this section if members will only connect with personal access tokens.

On the GitLab server, create an OAuth application (under your user or group Settings > Applications, or in the Admin Area for an instance-wide application) with:

• Redirect URI: https://<your ACTIVATE hostname>/api/integrations/gitlab/oauth/callback. The exact value is shown in the registration dialog below.
• Scopes: read_api.
• Confidential: enabled.

GitLab shows the Application ID and Secret after saving. You need both in the next step.

Add the Server in ACTIVATE

From the Organizations list, select your organization. In the sidebar, under Settings, click GitLab Servers.

Click + Add.

In the dialog box, enter the following:

• Name: a short name for the server, using lowercase letters, digits, and hyphens. Members see this name on their Connections page.
• Server URL: the https origin of the GitLab instance, for example https://gitlab.example.com.
• Application ID and Application secret: from the OAuth application you created in GitLab. Leave both blank to only allow personal access tokens.
• Allow personal access tokens: lets members connect by pasting a personal access token. The token is verified against the server, stored in the platform vault, and forgotten when the member disconnects.

The dialog box shows the redirect URI to configure on the GitLab OAuth application.

Click Create.

A dialog box with the message GitLab server registered will appear, and the server will be listed with the methods members can connect with under Connect via.

Connection Options

The pills at the bottom of the dialog box control how ACTIVATE reaches the server:

• Certificate verification: how the server's TLS certificate is checked.
  • Publicly trusted certificate (default): the certificate must chain to a public root.
  • Custom CA certificate: for servers with certificates issued by a private PKI. Paste the CA certificate in PEM format, or click Discover from server to fetch the CA from the chain the server presents. If the server doesn't include its root in the chain, paste the root certificate manually.
  • Skip verification (insecure): traffic is encrypted but the certificate is not checked. Use only when no CA you can supply will chain to the server.
• Minimum TLS: the lowest TLS version the platform negotiates with the server (1.2 by default).
• Allow private network address: lets the platform reach a GitLab server on a private network address. This option is only shown to, and can only be set by, platform administrators.

Editing a GitLab Server

On the GitLab Servers page, hover over the server and click the edit icon, or right-click the row and select Edit.

The application secret is never shown again. Leave the Application secret field blank to keep the stored secret, or enter a new one to replace it. Switching Certificate verification away from Custom CA certificate discards the stored CA certificate.

Click Save.

Removing a GitLab Server

Hover over the server, click the ⋯ menu, and select Delete.

Click Remove server.

A dialog box with the message GitLab server removed will appear.