Skip to main content
Version: Next

Gitlab Preview Deployment

Phase 1: Account Preparation

  1. Set a password for your Codesphere account (required for API access).
    • Note: If you used Google/GitHub login, use the "Forgot Password" link to define a distinct password.
  2. Connect your GitLab account to Codesphere.
    • Action: Click "+ New Workspace" and select "Connect GitLab" to authorize.
  3. Create a GitLab Project Access Token.
    • Scopes: Select api.
    • Role: Select Developer.
    • Copy: Save this token immediately; you will need it for the secrets.

Phase 2: Configure GitLab Secrets

  1. Open your repository on GitLab.
  2. Navigate to Settings > CI/CD > Variables.
  3. Add the following variables (Uncheck "Protect variable" if your branch is not protected):
    • CODESPHERE_EMAIL: Your Codesphere login email.
    • CODESPHERE_PASSWORD: Your Codesphere login password.
    • CI_ACCESS_TOKEN: The Project Access Token created in Phase 1.

Phase 3: Configure Pipeline

  1. Create a .gitlab-ci.yml file in your repository root.
  2. Paste the following configuration:
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: 'My Team'       # REPLACE with your exact Team Name
    PLAN: 'Boost'         # Options: Micro, Boost, Pro
    ON_DEMAND: 'true'     # 'true' enables cost-saving standby mode
    ENV: |                # Optional: Add environment variables below
      MY_ENV=test

Phase 4: Deploy & Verify

  1. Commit and push the .gitlab-ci.yml file.
  2. Open a new Merge Request in your repository.
  3. Check the comment section of your Merge Request.
    • Success: Codesphere will automatically post a comment with the direct link to your new Preview Deployment.