Codebase setup

Before Condux accepts delegated work for a repository, it prepares and validates a repeatable development environment for that codebase.

Import and investigation

Choose a repository available through the Condux GitHub App. Condux creates the repository’s condux issue label, then reads its contributor guidance, package configuration, tests, and existing automation to understand how work should be performed. Label provisioning is part of import so a repository is never shown as ready for GitHub Issue dispatch without it.

Configuration pull request

Condux opens a focused pull request containing a .condux directory. This repository-owned configuration teaches Condux how to prepare and validate the project and, when applicable, how to create previews.

Review this pull request with the engineers who understand the repository. You are checking that the proposed setup reflects normal development practice, not designing Condux’s orchestration system.

Environment validation

After the configuration merges, Condux builds a clean environment, prepares the repository, and runs its readiness check. The codebase becomes available for delegated work only after that validation succeeds.

If requirements change later, updates to the base branch trigger validation again. Condux keeps the last known working environment when a newer configuration cannot be validated.

What belongs in .condux

Most teams only need to know that the directory can define:

• How a checkout is prepared
• How readiness is verified
• Whether a change needs a preview
• How previews are deployed and removed
• Additional stable development-environment dependencies

The initial version is generated by Condux. Modify it when the repository’s development or preview workflow changes.

Preparation runs on a warm environment

After validation succeeds, Condux saves the validated environment and starts every later run from it. prepare-workspace.sh therefore runs on an environment where it has already run once: installed dependencies, Docker images, containers and volumes, generated files, and any global configuration it wrote are still present.

Every step in the script must reconcile that state to the current checkout rather than assume a clean machine:

• Use docker compose up -d --build so image changes are rebuilt instead of reusing the validation-day image.
• Copy generated files unconditionally instead of guarding with [ ! -f ].
• Let lockfile-driven installers (composer install, pnpm install --frozen-lockfile, bundle install) run every time; they are fast when nothing changed.
• Never append to global configuration files such as ~/.gitconfig; the saved environment would carry the earlier entry and each run would add another.

A create-if-missing step is not wrong on the first run, but it silently freezes the environment at its validation-day state. Validation always runs the script on a clean environment first, so the clean path is exercised on every configuration change.

Private GitHub dependencies

Workspace preparation runs with a short-lived GITHUB_TOKEN and GH_TOKEN for the Condux GitHub App, and Git is already configured to authenticate to GitHub. Preparation scripts can pass GITHUB_TOKEN to Composer, npm, pnpm, or bundler to install private packages from repositories the App can read. The token is available only during preparation; do not store it or rely on it in later steps.

Secrets

Do not commit service credentials to .condux or the repository. Add repository-specific values from the codebase’s Secrets page under Codebases. Add values intentionally shared across every codebase in the workspace under Settings → Workspace secrets. Provider connections remain under Integrations.