Integrate GitLab & Codesphere

GitLab is an open source version control and hosting service for Git repositories. Unlike the other major players in the remote git service area, you can self-host GitLab on your own servers. GitLab also offers features for continuous integration and delivery (CI/CD).

Working with GitLab in Codesphere

Sign up to Codesphere with your GitLab account, check out repositories, and automatically create preview deployments for each merge request.

You can also connect an existing account to GitLab - it only takes a few clicks. Once connected, you can browse your GitLab repositories in the create workspace dialog.

GitLab Integration "Create Workspace" Modal

Automating Preview Deployments for GitLab Merge Requests

Follow the step by step guide on how to set up preview deployments for any GitLab repository:

If you haven't done so already, create a Codesphere user with a username & password (OAuth won't work for using GitLab Pipelines) - we recommend creating a separate sysadmin user for this.
Log in to your new user and connect it to GitLab by clicking the "+ New Workspace" button and selecting "Connect GitLab" in the "Create Workspace" modal.
Ensure the connected GitLab account has access to the repository for which you are setting up the preview deployments.
Make sure the repository has a Codesphere CI pipeline with instructions on how to build & run your app.
Create a GitLab Project Access Token with API access and the developer role. Remove the expiration date if you do not want the token to expire.

Navigate to repository Settings/CI/CD/variables and add the secrets (CI_ACCESS_TOKEN, CODESPHERE_EMAIL and CODESPHERE_PASSWORD) to the repository's environment variables. Make sure to keep the protect variable checkbox unchecked.

GitLab Repository Variables

Create a .gitlab-ci.yml file in the root of your repository and add the following code. Make sure to change the TEAM in both places to the actual name of the Codesphere team you want to deploy to. You can find more information on which optional variables can be set below.

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

stages:
  - deploy

codesphere-deploy:
  image: ghcr.io/codesphere-cloud/codesphere-monorepo/integrations/gitlab-ci:latest
  stage: deploy
  script:
    - node /app/server.js
  variables:
    ACCESS_TOKEN: $CI_ACCESS_TOKEN
    EMAIL: $CODESPHERE_EMAIL
    PASSWORD: $CODESPHERE_PASSWORD
    TEAM: 'Demo'
    PLAN: 'Micro'
    ON_DEMAND: 'false'
  environment:
    name: 'Codesphere Preview MR_$CI_MERGE_REQUEST_IID'
    on_stop: codesphere-teardown

codesphere-teardown:
  when: manual
  image: ghcr.io/codesphere-cloud/codesphere-monorepo/integrations/gitlab-ci:latest
  stage: deploy
  script:
    - node /app/server.js
  variables:
    ACCESS_TOKEN: $CI_ACCESS_TOKEN
    EMAIL: $CODESPHERE_EMAIL
    PASSWORD: $CODESPHERE_PASSWORD
    TEAM: 'Demo'
  environment:
    name: 'Codesphere Preview MR_$CI_MERGE_REQUEST_IID'
    action: stop

Available Variables

The following are the variables you can use for your Repository variables.

(*) = required variable.

Variable	Usage
CI_ACCESS_TOKEN (*)	The access token you created for the repository. It is recommended to use a secure repository variable.
EMAIL (*)	Email of the Codesphere user
PASSWORD (*)	Password of the codepshere user. It is recommended to use a secure repository/workspace variable.
TEAM (*)	Name of the codesphere team.
PLAN	Workspace plan of the workspace that will be created. Available options `Micro`, `Boost`, `Pro`. Default: `Boost`.
ON_DEMAND	Decide whether this preview deployment should be deployed in `always on` or `off when unused` deployment mode. Available options `true`, `false`
ENV	Set environment variables in your workspace. Define them in the same way you would, when using dotenv in a Node.js project. See https://www.npmjs.com/package/dotenv for details.

Result

After following this guide, your Pipeline will run on every merge request and create a Preview Deployment for you to review your changes. It will add a new comment to your merge Request that includes the domain to your Preview Deployment:

GitLab Preview Deployment Comment on merge Request

Upon closing the PR it will also destroy the deployment in Codesphere. This way you only pay (prorated) for the time you actually used cloud resources.