Preparing a Project for Automatic Workspace Configuration

Workspace Manager can automatically provision new workspaces with code, databases, and configuration—ready to use without manual setup. This guide walks you through preparing your project for automatic initialization.

Connecting Your Git Repository

Before workspaces can auto-initialize, you need to connect a Git repository at the project level. Only project administrators can perform this setup.

1. Navigate to your project’s configuration page
2. Click the Repositories tab

3. Copy the SSH public key displayed on the page
4. Add this key as a Deploy Key in your Git repository settings
5. Back in Workspace Manager, click Add Repository and paste your repository’s SSH URL
6. Click the green checkbox to verify the connection
7. Click Save

Your repository is now ready to initialize workspaces.

Automatic Database Provisioning

Every workspace gets its own database automatically, named ws_{workspaceId}. Access this name in your code using the $WORKSPACE_DATABASE_NAME environment variable.

Seeding Databases with Starter Data

Workspace Manager can populate new databases with starter data from SQL dumps stored in the /shared/databases folder. The system selects the appropriate dump file based on your branch or tag:

Branch/tag-specific dumps: If you create a workspace from a branch named 245_upgrade, the system looks for /shared/databases/245_upgrade.sql.gz

Default dump: If no branch-specific dump exists, the system uses /shared/databases/default.sql.gz

Creating a database dump:

mysqldump \
  --single-transaction \
  --skip-column-statistics \
  --no-tablespaces \
  --set-gtid-purged=OFF \
  -h db \
  -u root \
  -p \
  {database_name} | gzip > default.sql.gz

The dump file must be gzipped SQL that can be loaded with the zcat command.

Flag explanations:

• --single-transaction: Creates a consistent snapshot without locking tables
• --skip-column-statistics: Avoids warnings about column statistics (MySQL 8.0+)
• --no-tablespaces: Prevents tablespace access warnings
• --set-gtid-purged=OFF: Avoids GTID-related errors when importing

Configuring Files and Symlinks

Configuration files and media assets that aren’t stored in your repository can be automatically copied or linked during workspace initialization. Define these in /shared/workspaceInit.yaml:

# Files to copy from /shared into the repository
files: []

# Files to symlink from the repository to /shared
symlinks:
  - auth.json
  - pub/media

# Template files to render (see below)
templates:
  - app/etc/env.php

Configuration Options

files: Copies files from /shared into the cloned repository folder

symlinks: Creates symbolic links from the repository to files under /shared

templates: Generates files from Golang templates (see Workspace Initialization File Templates)

Template file extension

Template files must end with .tmpl. This extension is stripped from the rendered output. For example, /shared/app/etc/env.php.tmpl renders to app/etc/env.php.

Note

Files specified in workspaceInit.yaml will overwrite any existing files in the repository during initialization.

Initialization Hooks

Workspace Manager executes shell scripts at specific points during initialization, giving you fine-grained control over the setup process. Hook scripts can live in two locations:

• /shared/hooks (available for all hooks)
• ordin/ subfolder in your repository (not available for pre-clone hooks)

Hook scripts must have a .sh extension and are executed with bash. Some hooks receive command-line parameters.

General Hooks

These hooks run for all workspace types, in this order:

• ws-before-git-clone.sh $workspace_repo $clone_dir $ref_name (only in /shared/hooks)
• ws-after-git-clone.sh $workspace_repo $clone_dir $ref_name
• ws-before-ref-checkout.sh $workspace_repo $clone_dir $ref_name
• ws-after-ref-checkout.sh $workspace_repo $clone_dir $ref_name
• ws-before-db-create.sh $db_name
• ws-after-db-create.sh $db_name
• ws-before-db-import.sh $db_name $import_file
• ws-after-db-import.sh $db_name $import_file
• ws-before-file-copy.sh
• ws-after-file-copy.sh

Adobe Commerce Hooks

Additional hooks for Adobe Commerce projects:

• ws-before-composer-install.sh $composer_json_file
• ws-after-composer-install.sh $composer_json_file
• ws-before-m2-setup-upgrade.sh $m2_root
• ws-after-m2-setup-upgrade.sh $m2_root

Creating Workspaces from Git

Once your project is connected to a Git repository, developers can select a specific branch or tag when creating a workspace.

Note

Repository settings can only be configured during workspace creation. You cannot retroactively connect an existing workspace to a repository.

Monitoring Initialization

Track the initialization process from the Workspace Status page:

• During initialization, the workspace status shows “Initializing”
• The workspace cannot be started until initialization completes
• View detailed logs by clicking the gear dropdown and selecting Show Initialization Log