Initial Setup

This documentation provides a step-by-step guide to set up and synchronize FirmwareCI with a git repository using the fwci CLI tool.

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 synchronized 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 sync command. It may redirect you to additional installation steps. See Synchronization 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 synchronizing 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 synchronization 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.

Integration Sources

• GitHub

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

• Gitlab

  1. Create a Gitlab access token:

     • Go to your Gitlab account settings (or your dedicated FirmwareCI user account)
     • Navigate to “Access Tokens”

     

     • Create a new token with api, read_repository and write_repository scopes
     • Copy the generated token for use with the fwci integration command

     

  2. Visit the webpage of your project.

  3. Scroll down to the Webhook Settings.

     

  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.

     

4. 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 synchronization 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.

5. 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.