Configuring Automated Deployments from GitLab to Gestalt Platform


This guide shows how to implement an integration with GitLab where GitLab builds are automatically deployed via Gestalt Platform to a development environment as part of a continuous integration (CI) process.

Initial Setup

1. Create Gestalt Service Account in GitLab

In GitLab:

  • Create a service account for deploying to Gestalt Platform in GitLab.

  • Create an access token for the service account with api access. Suggest name gestalt-deploy-to-dev-token (name does not matter). An access token can typically be created via the profile page: https://[gitlab_url]/profile/personal_access_tokens

  • Save the access token for configuring Gestalt Platform in the next step.

2. Create GitLab Integration Workspace and Environment

  • Create an Environment in an appropriate common area in the Gestalt Hierarchy. (suggest Workspace under /root named "System Workspace" with Environment named "GitLab Integration")

3. Create GitLab Deployment Lambda

TARGET_PROVIDER - UUID of the provider to deploy to (typically a DEV cluster.  Get this from the `Providers` view)
GITLAB_API_URL - GitLab API endpoint for projects (e.g. https://[gitlab host]/api/v4/projects)
GITLAB_TOKEN - GitLab access token

4. Create Service API Endpoint

  • Create an API and API Endpoint for the Lambda. Suggest the following:

  • API - named gitlab-api

  • API Endpoint - /deploy maps to gitlab-deploy-to-dev Lambda

The GitLab deployment service will be available at https://[Gestalt API Gateway]/gitlab-api/deploy

5. Create GitLab Service Account

  • Create a service account via the UI or REST API:
POST https://<gestalt>/meta/root/users
    "name": "gitlab-deploy-service-account",
    "properties": {
        "password": "password",
        "firstName": "None",
        "lastName": "None",
        "email": "gitlab-deploy-service-account@gestalt.system",
        "phoneNumber": "",
        "gestalt_home": "root"
  • Create an API Key for the service account:
user= (uuid)
root_org= (uuid)
gestalt_url=https://(gestalt host)
api_key= ...
api_secret= ...

echo "{\"orgId\":\"$root_org\"}" | http POST $gestalt_url/security/accounts/$user/apiKeys --auth "$api_key:$api_secret"

Collect the following for later: API Key API Secret

Per-Project Setup

Gestalt Workspace Configuration

Create an Application Workspace and Development Environment:

  • Workspace - named after application

  • Environment - type Development, suggest name DEV

  • Set up API for the application in DEV environment (e.g. /my-app)

Collect the following information for later:

  • Parent Org short-name
  • Environment UUID

Gitlab Project Configuration

Create a new GitLab project (or modify an existing one) with the following configuration.

Configure Pipepline Credentials

Navigate to [Project] -> Settings -> Pipelines and configure the following variables:

Common or Group-Level Properties

GF_API_KEY - API key for Gestalt

GF_API_SECRET - API secret for Gestalt Security

GF_DEPLOY_URL - URL for GitLab deployment service, e.g. https://[Gestalt API Gateway]/gitlab-api/deploy

Project Specific Properties

APP_SERVICE_PORT - The service port of the app (the service port is exposed on the API gateway)


GF_TARGET_ENV_UUID - Target Gestalt Environment UUID

GF_TARGET_ORG_NAME - Target Gestalt Organization short-name (that contains the Gestalt Workspace / Environment)

GITLAB_PROJECT_ID - The integer ID of this GitLab project, which may be obtained from the JSON output of https://[Gitlab URL]/api/v4/projects.

GITLAB_PROJECT_NAME - The name of the Gitlab project (the deployed container name will be derived from this value)

2. Configure .gitlab-ci.yaml

Configure the .gitlab-ci.yaml file at the project's root. An example is provided:

Example .gitlab-ci.yaml

Verifying Functionality

In Gitlab:

Make a change on a feature branch, create a merge request. A build will occur. View the CI pipeline to see the build running:

GitLab Merge Request

When viewing the merge request, a URL pointed at the deployed application will show:

GitLab Merge Request

The deployed container and published endpoint is viewable in Gestalt:

Gestalt Containers View