GitHub Integration

Set up FirmwareCI integration with GitHub repositories using the GitHub App.

Prerequisites

  • Repository set up with .firmwareci infrastructure (see Repository Setup)
  • fwci CLI tool authenticated

Setup Steps

1. Run Integration Command

Execute the integration command from your repository:

$ fwci integration

For GitHub repositories, you’ll receive output similar to:

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

2. Install GitHub App

Visit the FirmwareCI GitHub App page and install the app.

Installation options:

  • Install for all repositories in your organization
  • Install for specific repositories only

Grant the app access to the repositories where you want FirmwareCI enabled.

3. Verify Integration

Push a commit to your repository to trigger the first configuration update:

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

Check the commit status on GitHub - you should see the FirmwareCI status check appear.

How It Works

Automatic Configuration Updates:

  • Branch pushes: Update that branch’s configuration on the FirmwareCI server. Each pushed branch is tracked as a git branch with its own configuration, so main and feature branches stay independent (see the Branches reference).
  • Pull request pushes: Run validation to catch configuration errors before merge
  • Branch deletion: Deleting a branch on GitHub removes the corresponding git branch from FirmwareCI (best-effort); its jobs and history remain reachable.

Status Reporting:

  • Configuration validation results appear as commit status checks
  • Test results are reported back to pull requests (see Job Triggers)

HTTPS Authentication

When cloning HTTPS remotes fails, see these extra authentication options:

Environment Variable (Recommended):

export GIT_TOKEN=ghp_xxxxxxxxxxxx

Interactive Prompt (Fallback):

Enter token/password for https://github.com/owner/repo.git: <your PAT>

Generate Token:

Create a Personal Access Token with repo scope.

Next Steps