Create and configure a project

A project connects one repository to the environment its tasks need. Create separate projects for separate repositories. Organization owners and admins manage project configuration.

Create a project

Open Projects, choose Create project, and complete the three steps:

1. Repository: select a connected repository.
2. Image: choose a preset, package manager, setup command, and any additional tools.
3. Runner: choose Self-hosted or Devboxes Cloud, when available.

Use the package manager and setup command already maintained by the repository. Check version requirements rather than relying on a preset name alone.

Understand image readiness

The workspace image supplies the tools installed before the task starts. Qualified means the image passed the preparation checks required for use. A pending image may still be building or being verified.

A run accepted against a pending image remains queued while its environment is prepared. Do not dispatch it again to move it forward. Inspect the project's image status and any failure details.

Changing the project configuration affects how new work is prepared. Runs retain their recorded execution configuration; editing a project is not a way to rewrite an existing run's instructions or credential snapshot.

Configure variables and secrets

Open Projects, select the project, and open Environment. Choose Add key, enter the key and value, and select Save. Confirm that the key appears under Project variables and secrets. Store tokens and passwords as secrets. Do not put them in task instructions, blueprint text, or repository files.

The Inherited from credentials section lists organization keys attached to this project. A project key with the same name overrides the inherited value. Deleting that project key makes the inherited value active again. To change an organization key or its project assignments, open Credentials and select Environment.

A blueprint may require named inputs or a value from organization configuration. Check its readiness for this project before starting work. A blueprint that works in one project may need different setup in another.

Choose a runner target

Self-hosted tasks need a connected runner with Docker, a compatible platform, and access to the selected model. Cloud tasks need cloud execution enabled and an available organization model account.

See runners for execution setup and credentials for model access.