Skip to main content
Version: Weekly Build

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:
    API_URL: https://cloud.codesphere.com/ # replace with your instance URL
    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
    SHARED_VAULT_NAME: 'my-shared-vault'  # Optional: reuse a team shared vault's secrets across preview deployments
    ENV: |                # Optional: Add environment variables below
      MY_ENV=test

Shared Vaults

SHARED_VAULT_NAME attaches an existing team shared vault to the preview deployment, so it reuses the vault's secrets instead of maintaining its own isolated set. The shared vault must already be configured in the team. See Secret Management → Shared Vaults.

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.