Repository Setup

Initialize the .firmwareci infrastructure in your Git repository and connect it to the FirmwareCI server.

Prerequisites

  • fwci CLI tool installed and authenticated (see Installation)
  • A Git repository where you want to set up FirmwareCI

Initialize .firmwareci Structure

Navigate to your Git repository and initialize the basic file structure:

$ cd path/to/your/git/repository
$ fwci init

The resulting file structure:

.firmwareci/
├── duts
│   └── dut-fwci-crystal-core
│       ├── dut.yaml
│       ├── post.yaml
│       └── pre.yaml
├── README.md
├── storage
└── workflows
    └── fwci-crystal-core
        ├── tests
        │   └── test.yaml
        └── workflow.yaml

This is a basic example of the -firmwareci directory structure. In the next step we’ll configure these files to match your repository so tests run for your use-case.

Directory Structure and Naming Conventions

workflows/

Each subdirectory under workflows/ defines a single workflow. The main configuration file is workflow.yaml, and any test definitions go in the tests/ subdirectory. A workflow declares the tests to run and the DUT label(s) or hardware it targets.

duts/

Contains one directory per Device Under Test (DUT). Each DUT directory must include dut.yaml and may include pre.yaml and post.yaml for setup and teardown steps. The DUT’s label field is used by workflows to select matching hardware.

storage/

Holds artifacts used by tests — firmware images, test tools, and other binary assets. Reference these files from workflows and test definitions so runs can access the required resources.

FirmwareCI follows specific naming conventions for its directory structure:

Fixed Paths:

  • .firmwareci/ - Root directory (must be named exactly this)
  • .firmwareci/duts/ - DUT configurations directory (must be named exactly this)
  • .firmwareci/workflows/ - Workflow configurations directory (must be named exactly this)
  • .firmwareci/workflows/<WORKFLOW_NAME>/tests/ - Tests directory (must be named exactly this)
  • .firmwareci/storage/ - Storage directory (must be named exactly this)

Flexible Paths:

  • .firmwareci/duts/<DUT_NAME>/ - DUT directory name can be customized (e.g., dut-fwci-crystal-core, arm-board-dut)
  • .firmwareci/workflows/<WORKFLOW_NAME>/ - Workflow directory name can be customized (e.g., fwci-crystal-core, boot-workflow)
  • .firmwareci/workflows/<WORKFLOW_NAME>/tests/<TEST_NAME>.yaml - Test file names can be customized (e.g., test.yaml, boot.yaml, integration.yaml)

Required Files (fixed names):

  • .firmwareci/duts/<DUT_NAME>/dut.yaml - DUT configuration (must be named exactly this)
  • .firmwareci/duts/<DUT_NAME>/pre.yaml - Optional pre-stage configuration (must be named exactly this if used)
  • .firmwareci/duts/<DUT_NAME>/post.yaml - Optional post-stage configuration (must be named exactly this if used)
  • .firmwareci/workflows/<WORKFLOW_NAME>/workflow.yaml - Workflow configuration (must be named exactly this)

Connect Repository to FirmwareCI

Connect your Git repository to the FirmwareCI server to enable automatic synchronization.

Integration Command

Execute the integration command to link your repository:

$ fwci integration

By default, this targets the origin remote. To specify a different remote:

$ fwci integration -r upstream

You may also directly specify an integration source:

$ fwci integration -o github:BlindSpotSoftware/coreboot

Platform-Specific Setup

Follow the guide for your platform:

Manage Integrations

Review and manage your integrations:

$ fwci integration

When executed within a Git repository, this displays all associated integrations. To update a project’s linked repository, rerun the integration command in the target directory.

You can also manage integrations via the FirmwareCI dashboard.

Commit and Push

Commit the .firmwareci files to your repository:

$ git add .firmwareci
$ git commit -m "Initialize .firmwareci infrastructure"
$ git push

For GitHub and GitLab repositories, pushes to the default branch trigger synchronizations. Pushes to other branches run validation, useful for testing changes in pull requests before merging.

Verify Setup

Check your setup status on the FirmwareCI dashboard or view the status report on the connected repository branch.

Next Steps

Now that your repository is connected to FirmwareCI, proceed to Configuration to customize DUTs and workflows for your testing needs.