GitLab Integration

Set up FirmwareCI integration with GitLab repositories using access tokens and webhooks.

Prerequisites

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

Setup Steps

1. Generate Access Token

Create a token with required permissions:

Option A: Personal Access Token

  1. Navigate to Settings > Access Tokens in your GitLab account
  2. Create a token with these scopes:
    • api
    • read_repository
    • write_repository
  3. Save the token securely

Option B: Project Access Token

  1. Navigate to Settings > Access Tokens in your GitLab project
  2. Create a token with the same scopes as above
  3. Save the token securely

2. Run Integration Command

Provide the access token when running integration:

$ fwci integration --gitlab-auth="YOUR_ACCESS_TOKEN"

3. Configure Webhook

Set up the webhook in your GitLab project to enable automatic configuration updates:

  1. Navigate to Settings > Webhooks in your GitLab project
  2. Add the webhook URL:
    • URL: https://api.firmwareci.9esec.dev:8443
    • For self-hosted instances, use your FirmwareCI server URL
  3. Secret Token: Contact FirmwareCI team for the secret token
  4. Trigger events:
    • ☑ Push events
    • ☑ Merge request events
  5. Click Add webhook

GitLab Webhook Settings GitLab Webhook Settings

4. Verify Integration

Push a commit to trigger the first configuration update:

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

Check the commit in GitLab - you should see the FirmwareCI status 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).
  • Merge request pushes: Run validation to catch configuration errors before merge
  • Branch deletion: Deleting a branch on GitLab removes the corresponding git branch from FirmwareCI (best-effort); its jobs and history remain reachable.

Status Reporting:

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

HTTPS Authentication

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

Environment Variables (Recommended):

export GIT_TOKEN=glpat-xxxxxxxxxxxx
export GITLAB_USERNAME=your_gitlab_username

Interactive Prompt (Fallback):

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

Generate Token:

Create a Personal Access Token with api and read_repository scopes.

Next Steps