Is this page helpful?

Make a Git Repository a Project#

Overview#

Converting a repository requires adding a specification file that defines the container environment.

Create a .project/spec.yaml file in your repository. This file declares what AI Workbench needs to build, manage and configure. The process is similar to adding a devcontainer.json file.

Start with a minimal specification and add features as needed.

Only a few fields are required: version information, base container image details, and a project mount. Optional fields let you configure project layout, applications, GPU resources, and more. Use nvwb validate project-spec frequently to check your specification.

Using an NVIDIA base image simplifies the specification.

NVIDIA provides pre-configured base images with common frameworks and tools. These images have proper labels so AI Workbench can auto-populate many fields. Browse available images at the NVIDIA NGC Catalog.

After creating the specification, push to a remote and clone using AI Workbench.

AI Workbench manages projects through its inventory system. The easiest way to add a converted repository is to push it to GitHub or GitLab and clone it. AI Workbench reads the specification and builds the container automatically.

Key Concepts#

Specification File

The .project/spec.yaml file that defines how AI Workbench builds and configures the project container.

Base Container Image

A pre-built Docker image that provides the foundation for the project environment (OS, tools, frameworks).

Required Fields

Mandatory fields in the spec: version identifiers, base image details (registry, image, name, description, OS), and project mount.

Optional Fields

Additional configuration for GPU resources, secrets, volumes, and applications.

Layout Section

Defines directory structure and storage backends (git, gitlfs, gitignore) for different file types.

Convert Repository to AI Workbench Project#

Step One: Create the directory structure.

  1. Navigate to your repository root directory

  2. Create the recommended directory structure:

    mkdir -p .project code models data data/scratch
Step Two: Create the minimal spec.yaml file.

  1. Create a minimal spec.yaml file with this template:

    cat > .project/spec.yaml << 'EOF'
specVersion: v2
specMinorVersion: 2
meta:
    name: my-project-name
    image: project-my-project-name
    description: My AI Workbench Project Description
    createdOn: "2025-11-15T12:00:00Z"
    defaultBranch: main
    labels: []
layout:
    - path: code/
      type: code
      storage: git
    - path: models/
      type: models
      storage: gitlfs
    - path: data/
      type: data
      storage: gitlfs
    - path: data/scratch/
      type: data
      storage: gitignore
environment:
    base:
        registry: nvcr.io
        image: nvidia/ai-workbench/python-basic:1.0.8
        name: Python Basic
        description: A Python environment with JupyterLab
        os: linux
        os_distro: ubuntu
        os_distro_release: "22.04"
        schema_version: v2
execution:
    mounts:
        - type: project
          target: /project/
          description: Project directory
          options: rw
EOF

  2. Edit the file to customize these required fields:

    • meta.name - Lowercase alphanumeric with hyphens (e.g., my-ml-project)

    • meta.image - Should match pattern project-<name> (e.g., project-my-ml-project)

    • meta.description - Brief description of your project

    • meta.createdOn - ISO 8601 timestamp with current date and time

    • environment.base.registry - Container registry (e.g., nvcr.io, docker.io)

    • environment.base.image - Base container image with tag (choose from NGC catalog)

    • environment.base.name - Human-readable container name

    • environment.base.description - Brief description of the container

    • environment.base.os_distro - Must match the actual OS distribution in your base container (e.g., ubuntu, centos)

    • environment.base.os_distro_release - Must match the actual OS release in your base container (e.g., "22.04", "20.04")

Step Three: Commit and push the .project directory.

  1. Stage and commit the new directory:

    git add .project/ code/ models/ data/
git commit -m "Add AI Workbench project specification"
git push origin main

  2. Ensure the repository is accessible (public or with appropriate credentials)

Step Four: Clone the repository as an AI Workbench project.

  1. Using Desktop App:

    • Select Location Manager > Location Card

    • Click Clone Project

    • Enter Clone Project > Git Repository URL > your repository URL

    • Click Clone

  2. Using CLI:

    nvwb clone project https://github.com/username/repository.git

  3. AI Workbench reads the spec.yaml file and builds the container

Success: The project appears in the Location Manager and the container builds successfully.

Test early by cloning to catch errors

The most reliable validation happens when you actually clone the project. Push your repository and clone it with AI Workbench to verify the specification works correctly. YAML is sensitive to indentation—use spaces (not tabs) with consistent indentation levels.

Start minimal and add features incrementally

The minimal specification includes only the essential fields required for AI Workbench to function. Add optional features one at a time and test by cloning after each addition. This approach makes debugging easier and helps you understand what each field does.

Use NVIDIA base images for simpler specifications

NVIDIA-provided base images from nvcr.io have proper labels that minimize configuration effort. You still need to specify the OS distribution and release to match the actual container. Custom containers need additional Docker labels for full AI Workbench integration. See Use a Custom Container Image for custom container requirements.

The validation command has limitations

The nvwb validate project-spec command checks basic syntax and structure. However, it does not catch all errors and has known limitations. The most reliable test is to push your repository and clone it with AI Workbench.

Add Optional Features to Your Project#

The minimal specification is functional, but you can add optional features as needed.

Start simple and add complexity only when required. Each addition should serve a specific purpose for your project.

Customize project layout for different storage needs.

The minimal specification includes a standard layout with code, models, data, and scratch directories. Modify the layout section to change storage backends for different directories. Storage options: git (regular), gitlfs (large files), gitignore (excluded). Each layout entry requires type and storage fields.

Add package dependencies with helper files.

Create these files in .project/ directory:

  • requirements.txt - Python packages (one per line)

  • apt.txt - System packages (one per line)

  • preBuild.bash - Runs before container build

  • postBuild.bash - Runs after container build

See Manage Packages for details.

Configure GPU and memory resources.

Add resources section to execution:

execution:
    resources:
        gpu:
            requested: 1
        sharedMemoryMB: 2048
    mounts:
        - type: project
          target: /project/
          description: Project directory
          options: rw

Both gpu.requested and sharedMemoryMB are optional. See Configure GPU Settings for Project Container for hardware configuration.

Add environment secrets for API keys.

Add secrets section to execution:

execution:
    secrets:
        - variable: NVIDIA_API_KEY
          description: NVIDIA API key for accessing models
        - variable: OPENAI_API_KEY
          description: OpenAI API key
    mounts:
        - type: project
          target: /project/
          description: Project directory
          options: rw

Only variable is required; description is optional but recommended.

Add volume mounts for shared storage.

Add additional mounts to execution.mounts:

execution:
    mounts:
        - type: project
          target: /project/
          description: Project directory
          options: rw
        - type: volume
          target: /data/
          description: Shared dataset storage
          options: volumeName=my-data-volume

Each mount requires type and target (absolute path with trailing slash). The project mount is always required.

For complete field documentation, see: