How It Works

1. Commit Collection: The runner walks the git history of the repository inside your CI environment and extracts, for each commit, the commit hash, the commit date, the author, and the technologies touched (detected from the file extensions changed by the commit). Commits that touch no recognized technology — documentation, configuration, lockfiles — are skipped entirely.
   
   
2. Send to SecureFlag: The collected commits are sent to the SecureFlag platform, where each one is classified against its author's training records.

Data Protection & Privacy

1. The commit hash
2. The commit date
3. The commit author (email), used solely to match the commit to a SecureFlag user
4. The names of the technologies touched (e.g. java, nodejs, python)
   

Note: The following are never sent to SecureFlag: source code, diffs, file contents, file names or paths, and commit messages.

1. A CI/CD system that supports Docker
2. A SecureFlag API key with the Write SDLC data scope (see below)
   

Environment Variables

Variable	Description	Required
SECUREFLAG_API_KEY	SecureFlag API token with the "Write SDLC data" scope. Store it as a CI secret.	Yes
SECUREFLAG_COMMANDS	Set to collect-metrics.	Yes
SECUREFLAG_REPOSITORY	Repository identifier reported to SecureFlag (e.g. my-org/my-repo). Keep it stable across runs: it identifies the repository on the platform.	No — auto-detected from the CI environment, falling back to the git origin remote

Get the SecureFlag API Key

The token must be created by an Organization Admin:

1. Log in to SecureFlag and open the Management portal.
2. Go to Settings and open the API Access Tokens section.
3. Create a new token and select the Write SDLC data scope.
4. Generate the token and copy it right away — it will not be shown again.
5. Store it in your CI/CD system as a masked/secured secret named SECUREFLAG_API_KEY.

CI/CD Integration

The SecureFlag runner is platform-agnostic and works with any CI/CD system that supports Docker. Ready-to-use examples for GitHub Actions, GitLab CI, and Bitbucket Pipelines follow.

GitHub Actions Setup Example

Add this to your repository at .github/workflows/secureflag-commit-metrics.yml:

name: SecureFlag Commit Metrics

on:

  push:

    tags:

      - '*'

  # Run on schedule (configure as needed)

  # schedule:

  #   - cron: '0 2 * * *'

jobs:

  secureflag_commit_metrics:

    name: SecureFlag Commit Metrics

    runs-on: ubuntu-latest

    container:

      image: registry.gitlab.com/secureflag-community/sf-runner:latest

    env:

      SECUREFLAG_API_KEY: ${{ secrets.SECUREFLAG_API_KEY }}

      SECUREFLAG_COMMANDS: collect-metrics

      # Tag pipelines run on the tag ref ($GITHUB_REF_NAME would be the tag name):

      # pin the branch identifier reported to SecureFlag

      SECUREFLAG_BRANCH: main

    continue-on-error: true

    steps:

      - name: Checkout repository

        uses: actions/checkout@v4

        with:

          # Full history is required

          fetch-depth: 0

      - name: Run SecureFlag CI Runner

        run: /app/entrypoint.sh

GitLab CI Setup Example

Add this to your repository's .gitlab-ci.yml, with SECUREFLAG_API_KEY set as a masked/protected CI/CD variable:

stages:

  - tests

secureflag_commit_metrics:

  stage: tests

  image: registry.gitlab.com/secureflag-community/sf-runner:latest

  variables:

    SECUREFLAG_COMMANDS: collect-metrics

    # Full history is required

    GIT_DEPTH: 0

    # Tag pipelines run on the tag ref ($CI_COMMIT_REF_NAME would be the tag

    # name): pin the branch identifier reported to SecureFlag

    SECUREFLAG_BRANCH: main

  script:

    - /app/entrypoint.sh

  rules:

    # Run on tags

    - if: $CI_COMMIT_TAG

    # Run on schedules

    - if: '$CI_PIPELINE_SOURCE == "schedule"'

  allow_failure: true

Bitbucket Pipelines Setup Example

Add this to your repository at bitbucket-pipelines.yml, with SECUREFLAG_API_KEY set as a secured repository variable. Bitbucket has no native "allow failure" option; the trailing || true keeps the pipeline green if the SecureFlag run fails — remove it if you want the pipeline to fail on errors.