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_API_TOKEN: Your Codesphere API token, generated in Account Settings > API Keys (recommended).
    • CI_ACCESS_TOKEN: The Project Access Token created in Phase 1.
    • CODESPHERE_EMAIL: (Deprecated) Your Codesphere login email. Use CODESPHERE_API_TOKEN instead.
    • CODESPHERE_PASSWORD: (Deprecated) Your Codesphere login password. Use CODESPHERE_API_TOKEN instead.

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
    API_TOKEN: $CODESPHERE_API_TOKEN
    TEAM: 'My Team'       # REPLACE with your exact Team Name
    PLAN: 'Boost'         # Options: Micro, Boost, Pro
    ON_DEMAND: 'true'     # 'true' enables cost-saving standby mode
    DEPLOYMENT_LINK_TYPE: 'preview'  # Optional: 'preview' or 'dev-domain'
    SHARED_VAULT_NAME: 'my-shared-vault'  # Optional: reuse a team shared vault's secrets across preview deployments
    CI_PROFILE: 'my-ci-profile'  # Optional: CI profile to use instead of the default
    CODESPHERE_RESTRICTED: 'false'  # Optional: 'true' restricts the dev domain to team members only
    CODESPHERE_BASE_IMAGE: 'my-base-image'  # Optional: overrides the workspace's base image
    VPN_CONFIG: 'my-vpn-config'  # Optional: attach the workspace to an existing team VPN config
    GIT_CLONE_DEPTH: '1'   # Optional: shallow-clone depth for the checkout
    GIT_SKIP_LFS: 'false'  # Optional: 'true' skips downloading Git LFS files
    GIT_RECURSE_SUBMODULES: 'true'  # Optional: 'false' skips cloning submodules
    TLS_ALLOW_UNAUTHORIZED: 'false'  # Optional: 'true' disables TLS certificate verification
    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.

Available Variables​

The following variables can be set under the variables key of the codesphere-deploy job. (*) = required variable.

VariableUsage
API_URL (*)The base URL for your Codesphere instance including https://, e.g. https://cloud.codesphere.com.
ACCESS_TOKEN (*)The GitLab Project Access Token created in Phase 1.
API_TOKENRecommended. Your Codesphere API token, generated in Account Settings > API Keys. When set, EMAIL and PASSWORD are ignored.
EMAIL(Deprecated) Email of the Codesphere user. Use API_TOKEN instead.
PASSWORD(Deprecated) Password of the Codesphere user. Use API_TOKEN instead.
TEAM (*)Name of the Codesphere team.
PLANWorkspace plan of the workspace that will be created. Available options: Micro, Boost, Pro. Default: Boost.
ON_DEMANDDecide whether this preview deployment should be deployed in always-on or off-when-unused deployment mode. Available options: true, false.
ENVSet environment variables in your workspace. Define them the same way you would when using dotenv in a Node.js project. See https://www.npmjs.com/package/dotenv for details.
DEPLOYMENT_LINK_TYPEControls the format of the deployment link posted to the Merge Request. preview opens an interactive preview where reviewers can leave frontend comments. dev-domain links directly to the workspace's development domain. Default: dev-domain.
SHARED_VAULT_NAMEName of a team shared vault to attach to the workspace. When set, the preview deployment 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.
CI_PROFILEName of the CI profile to use for the deployment. Defaults to the repository's ci.yml.
CODESPHERE_RESTRICTEDIf true, the workspace's dev domain is only reachable by team members instead of being public. Default: false.
CODESPHERE_BASE_IMAGEOverrides the base image the workspace is created from. Defaults to the plan's default image.
VPN_CONFIGIf you have created a VPN configuration for this team, reference it here by its config name. This connects the preview deployment to that VPN connection.
GIT_CLONE_DEPTHShallow-clone depth used when checking out the repository. Defaults to the full history.
GIT_SKIP_LFSIf true, skips downloading (smudging) Git LFS files during clone. Default: false.
GIT_RECURSE_SUBMODULESIf false, submodules are not initialized and cloned. Default: true.
TLS_ALLOW_UNAUTHORIZEDIf true, disables TLS certificate verification when talking to the Codesphere API. Only use this for self-hosted instances with self-signed certificates. Default: false.

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.