Initial Setup

This documentation provides a step-by-step guide to set up and integrate FirmwareCI with a git repository using the fwci CLI tool. You can add any number of git repositories to your FirmwareCI organization this way.

Attention: Synchronization is currently only supported with GitHub and Gitlab repositories.

Prerequisites

  • Ensure you have the fwci CLI tool installed on your system.
  • A git repository where you want to set up the .firmwareci infrastructure.

Set Up .firmwareci Infrastructure

  1. Navigate to Your Git Repository:

    Open your terminal and navigate to the root directory of your git repository.

    $ cd path/to/your/git/repository

  2. Intialization & review of .firmwareci structure:

    Use the fwci CLI tool to initialize the basic file structure for .firmwareci.

    $ fwci init

    The resulting file structure should resemble the following:

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

    • The fwci-crystal-core directory encompasses all configurations related to a specific workflow, with its primary configuration located in the workflow.yaml file. An example test is provided within the tests subdirectory.

    • The duts directory contains configurations for DUTs. Each DUT directory includes its configuration file (dut.yaml), along with example pre-stage (pre.yaml) and post-stage (post.yaml) files.

    • The storage directory contains potential storage items used in tests.

    A more detailed explanation of these files will be covered in subsequent guides and inside the references.

  3. Synchronize Git Repository:

    To complete the setup of the git repository with FirmwareCI, it needs to be integrated with the FirmwareCI server. Once completed, the FirmwareCI server will be notified of all changes made in the git repository.

    Therefore, log in via the CLI:

    $ fwci login <email> <password>

    After logging in, execute the integration command. It may redirect you to additional installation steps. See Integration Sources for more details.

    $ fwci integration

Successfully set up integration with github/<owner>/<repository>.
Please visit the following link to complete the integration setup: https://github.com/apps/blindspot-software-firmware-ci

    The integration command defaults to integrating with the origin remote of the git repository. You can specify other remotes using the -r flag.

    $ fwci integration -r upstream

    Alternatively, you can directly include a integration source.

    $ fwci integration -o github:BlindSpotSoftware/coreboot

    Note for Gitlab repositories: When integrating with Gitlab, you’ll need to provide an access token using the --access-token flag:

    $ fwci integration --access-token="ACCESS_TOKEN"

    You must create this access token in your Gitlab account with appropriate permissions (api, read_repository, write_repository) to allow FirmwareCI to interact with your repository. For better organization and clear identification of automated actions, we recommend creating a dedicated user named “FirmwareCI” in your Gitlab instance and generating the access token from that account. This allows our backend to post comments and status updates using that identity.

    Note: Alternatively, you can also utilize a project access token for authentication instead of creating a user account.

    You can keep track of your integrations by visiting the FirmwareCI dashboard or by executing fwci integration once more. If you are currently inside a git repository, you will be provided a list of all your integrations.

    You may also update a project’s linked repository by using the following command:

    $ fwci integration update

    You will be prompted to select a project to update with the git repository you’re currently in.

Integration Sources

  • GitHub

    Visit the web-page of the Firmware CI App. Install and enable the app for any repository which should be integrated with FirmwareCI.

  • Gitlab

  1. Create a Gitlab access token (select one method):

    Option 1: User Access Token

    • Navigate to your Gitlab account settings
    • Select “Access Tokens” in the left navigation panel

    Gitlab Access Tokens Gitlab Access Tokens

    • Generate a new token with the required scopes: api, read_repository

    Option 2: Project Access Token

    • Access your Gitlab project repository
    • Navigate to Settings > Access Tokens

    Gitlab Project Access Token Setting Gitlab Project Access Token Setting

    • Create a project access token with minimum developer role permissions and both api and read_repository scopes

    Gitlab Project Access Token Creation Gitlab Project Access Token Creation

    1. Integrate the token using the following command:
    fwci integration --access-token="YOUR_ACCESS_TOKEN"

  2. Visit the webpage of your project.

  3. Scroll down to the Webhook Settings.

    Project Tab Project Tab

  4. Add the webhook as shown and save.

Note: The secret token for the webhook will be provided upon request. Please contact the FirmwareCI team to obtain your specific webhook token.

Webhook Settings Webhook Settings

Default-Webhook-URL:

   https://api.firmwareci.9esec.dev:8444

Caution: If you are using a self-hosted instance of FirmwareCI, ensure to update the URL to match your instance.

This will push the current commit to the FirmwareCI server for processing.

  1. Commit the Changes:

    Add the newly created .firmwareci files to your git repository and commit the changes.

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

    Note: For GitHub and Gitlab repositories, pushes to the default branch will trigger synchronizations on the FirmwareCI side. Pushes to any other branch will run a validation on all the files. This can be particularly useful for validating changes within a Pull Request before merging them into the default branch.

  2. Check FirmwareCI Status

To check the status of your FirmwareCI setup and ensure everything is configured correctly, you can visit the FirmwareCI dashboard or check for a status report on the repository branch you just connected.

CLI Synchronization

You can also synchronize your codebase with FirmwareCI directly through the CLI without webhook integration, subject to the following requirements:

  • The specific commit you intend to synchronize must be checked out locally
  • Your working directory must contain no uncommitted changes
  • The commit must be pushed to the remote repository (this is required as FirmwareCI generates web links to commit changes in the UI)

Important Note: CLI synchronization should be reserved for specific scenarios, such as:

  • When synchronizing commits outside the default branch
  • When network restrictions prevent your version control system from communicating with the FirmwareCI instance
  • For troubleshooting integration issues

To synchronize using the CLI method:

$ fwci synchronization
Logged in as fabian.wienand@blindspot.software in git@gitlab.firmware-ci.com:firmware-ci/development.git@29e5e3d

commit 29e5e3d08661fe31053ce0fe5d07fad7b26274a6
Author: Fabian Wienand <fabian.wienand@blindspot.software>
Date:   Tue Apr 01 08:56:21 2025 +0000

    Merge branch 'fwci-iac' into 'main'

    feat: add fwci IaC

    These are a bunch of changes

    Signed-off-by: Fabian Wienand <fabian.wienand@blindspot.software>