> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blitzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Setup

> Set up a Blitzy project from account provisioning through repository configuration, branch isolation, source control integration, and project creation

This guide walks you through setting up your environment and creating a new Blitzy project, from initial account provisioning through to project creation on the platform.

<Note>
  **Jump to:** [Account Provisioning](#phase-1-account-provisioning) | [Repository Structure](#phase-2-repository-structure-configuration) | [Branch Configuration](#phase-3-branch-configuration) | [Source Control Integration](#phase-4-source-control-integration) | [Codebase Context](#phase-5-codebase-context-configuration) | [Project Creation](#phase-6-project-creation)
</Note>

Before beginning, ensure you have:

* **Administrative access** - to your source control organization (required to install the Blitzy integration)
* **Team member list** - for account provisioning
* **Target repositories** - identified
* **Build documentation** - ready

## Phase 1: Account Provisioning

Submit a list of email addresses for all users requiring platform access to your Blitzy technical contact. When submitting the list, categorize users by their required role level:

* **Users** - Standard user access for code generation workflows
* **Admins** - Project and workflow management capabilities
* **Super Admins** - Platform configuration and organizational settings

Account creation is handled by Blitzy. Users receive email invitations upon completion of the provisioning process.

**Role Permissions:** For detailed specifications on capabilities and restrictions for each role type, refer to the [Teams & Role Configuration guide](/administration/teams).

## Phase 2: Repository Structure Configuration

<Tabs>
  <Tab title="Single Repository">
    If you are onboarding a single repository, no additional configuration is required for this phase. Proceed directly to Phase 3: Branch Configuration.
  </Tab>

  <Tab title="Multiple Repositories">
    For multi-repository projects (microservices, monorepo decomposition, shared libraries), Blitzy uses Git submodules to maintain context across related codebases and understand inter-repository dependencies.

    **To implement:** Create a parent repository, add child repositories as submodule references, and configure tracking branches. See the **[Git Submodules Guide](/administration/submodules)** for complete setup instructions with Git commands and configuration examples.
  </Tab>
</Tabs>

## Phase 3: Branch Configuration

Create a dedicated branch for Blitzy operations from your target base branch (typically `main` or `dev`):

```bash theme={null}
git checkout main
git checkout -b blitzy
git push origin blitzy
```

### Rationale for Branch Isolation

Blitzy requires a stable reference point during code ingestion. Using an inactive branch prevents synchronization issues caused by frequent commits to active development branches. This isolation ensures that the AI has a consistent view of your codebase during analysis and generation.

### Blitzy Workflow

The isolated branch workflow follows this pattern:

<Steps>
  <Step title="Ingestion">
    Blitzy ingests code from the `blitzy` branch to build its understanding of your codebase
  </Step>

  <Step title="Generation">
    Generated code and modifications are committed to the `blitzy` branch
  </Step>

  <Step title="Review">
    Changes are reviewed via standard pull request process
  </Step>

  <Step title="Integration">
    Approved changes are merged to active branches (`dev`, `main`) through your existing CI/CD pipeline
  </Step>
</Steps>

<Warning>
  **Do not push changes to the `blitzy` branch while code generation is in progress.** Pushing commits during generation causes conflicts, lost work, or broken builds. Wait until generation completes and the pull request is delivered before pushing any changes to the branch.
</Warning>

This isolation ensures generated code undergoes your existing review and CI/CD processes before integration into production code. All generated code is subject to the same quality gates, automated testing, and human review as manually written code.

## Phase 4: Source Control Integration

Connect your source control provider to enable repository access for the Blitzy platform.

<Note>
  For organization-owned repositories, a workspace or organization admin may need to authorize the Blitzy integration before individual users can connect their accounts.
</Note>

### OAuth Connection

<Steps>
  <Step title="Log In">
    Log into the Blitzy platform
  </Step>

  <Step title="Navigate to Integrations">
    Go to **Settings > Integrations**
  </Step>

  <Step title="Connect Provider">
    Select your source control provider and follow the OAuth flow
  </Step>

  <Step title="Grant Access">
    Grant repository access permissions (see below)
  </Step>
</Steps>

### Repository Access Configuration

Grant Blitzy access to **all repositories that will be ingested onto the platform**, including submodule and shared-library repositories. When in doubt, grant access to all repositories.

<Tabs>
  <Tab title="All Repositories (Recommended)">
    Granting access to all repositories is the simplest approach and ensures no access issues during ingestion. This is the recommended configuration for most organizations.
  </Tab>

  <Tab title="Selected Repositories">
    If you choose to grant access to specific repositories only, include every repository Blitzy will ingest: parent repositories, each submodule individually, and any shared dependency repositories.

    <Warning>
      **Submodule access is not inherited.** Granting access to a parent repository does not automatically include its submodules. Each must be explicitly authorized.
    </Warning>
  </Tab>
</Tabs>

For additional information on configuring environment-specific access and credentials, refer to the [Environment Configuration guide](/administration/environments).

## Phase 5: Codebase Context Configuration

### Environment Setup

Create a Blitzy environment configuration containing the information necessary to build and run your codebase. This enables Blitzy to understand your development environment and generate code that integrates with your existing build processes.

#### Build Instructions

Provide complete build and runtime setup steps that a developer would need to get your project running locally:

* **Dependency installation commands** - e.g., `npm ci`, `mvn clean install`, `pip install -r requirements.txt`
* **Build tool invocations** - required flags and configuration
* **Pre-build script execution** - any setup scripts that must run first
* **Compilation steps** - build order for multi-module projects
* **Local development server** - startup commands

See the **[Environment Configuration Guide](/administration/environments)** for detailed examples.

#### Secrets and Environment Variables

Document all required configuration values: API keys, PATs for private registries, service endpoints, feature flags, and authentication credentials. Use placeholder syntax with curly braces (e.g., `${DATABASE_PASSWORD}`, `${API_KEY}`) to reference secrets in your build instructions. Actual credential values are encrypted and stored separately.

See the **[Environment Configuration Guide](/administration/environments)** for complete details on variables vs. secrets, encryption, and configuration best practices.

### Ingestion Prompt (Optional)

The ingestion prompt provides architectural and domain-specific context beyond what can be derived from code analysis alone. While optional, providing this information significantly improves code generation accuracy and quality.

#### Recommended Content

<Tabs>
  <Tab title="Architectural Patterns">
    "Services follow a three-tier architecture: Controllers handle HTTP, Services contain business logic, Repositories manage data access"
  </Tab>

  <Tab title="Code Organization">
    "Feature modules are organized by domain entity; shared utilities reside in `/core`"
  </Tab>

  <Tab title="Framework Patterns">
    "All database access uses the Repository pattern with Specification objects for complex queries"
  </Tab>

  <Tab title="Domain Terminology">
    "In this codebase, 'instruments' refer to financial securities; 'positions' represent holdings"
  </Tab>

  <Tab title="Technical Constraints">
    "All API responses must include correlation IDs for distributed tracing"
  </Tab>

  <Tab title="Testing Requirements">
    "Generated code must include unit tests following the Arrange-Act-Assert pattern"
  </Tab>
</Tabs>

## Phase 6: Project Creation

With your environment fully configured, create your project on the Blitzy platform.

<Steps>
  <Step title="Open Workspace">
    Navigate to your **Workspace** (homepage)
  </Step>

  <Step title="Create Project">
    Click **Create new project**
  </Step>

  <Step title="Select Project Type">
    Choose between **New Product** or **Existing Product** based on your use case
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="New Product" icon="sparkles" href="/quickstart#project-type">
    Starting from scratch. Skip ingestion and go straight to writing a generation prompt.
  </Card>

  <Card title="Existing Product" icon="code" href="/quickstart#existing-product">
    Working with an existing codebase. Blitzy ingests your repository before code generation begins.
  </Card>
</CardGroup>

## Technical Support

Contact your assigned Blitzy AI Solutions Consultant for configuration validation or troubleshooting during project setup.