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.

Automating Preview Deployments for GitLab Merge Requests

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

1. 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.
2. 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.
3. Ensure the connected GitLab account has access to the repository for which you are setting up the preview deployments.
4. Make sure the repository has a Codesphere CI pipeline with instructions on how to build & run your app.
5. 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.

6. 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.

7. 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.

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:

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.