GitHub Action

FlagShark/flagshark is the official FlagShark GitHub Action. It runs the same detection engine as the CLI, posts a sticky comment on every pull request, and writes a job summary to the Actions UI. You can optionally fail the workflow when your flag health score drops below a threshold you set.

No FlagShark account required. The Action is open-source (MIT) and lives at FlagShark/flagshark.

Quickstart

Drop this into .github/workflows/flagshark.yml:

name: FlagShark
on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  flagshark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required: git blame (flag age) and the changed-file diff need full history
      - uses: FlagShark/flagshark@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

On the next PR, FlagShark scans the changed files, posts a comment, and writes a job summary.

pull-requests: write is needed so the Action can post (and update) its PR comment; contents: read lets it read the diff. If you set output-format: none, you can drop pull-requests: write.

@v2 tracks the latest v2.x (staleness threshold in days, the current behavior shown here). You can pin more strictly to a full version tag or a commit SHA for supply-chain control.

Inputs

All inputs are optional.

Pass inputs via with::

      - uses: FlagShark/flagshark@v2
        with:
          scan: full          # scan the whole repo, not just PR files
          threshold: 7        # stricter staleness window
          fail-threshold: 80  # block the PR below 80/100 health
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Outputs

The Action sets the following outputs you can chain into later steps.

Reference outputs in a later step by giving the Action an id: and using steps.<id>.outputs.<name>:

jobs:
  flagshark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: FlagShark/flagshark@v2
        id: flagshark
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Enforce health gate
        run: |
          echo "Health score: ${{ steps.flagshark.outputs.health-score }}"
          echo "Stale flags: ${{ steps.flagshark.outputs.stale-count }}"
          echo "Flags with errors: ${{ steps.flagshark.outputs.error-count }}"

What the Action produces

Each run produces up to four artifacts:

• Sticky PR comment: Posted on pull_request events when at least one flag is found and output-format is markdown. If a comment from a previous push already exists (identified by a hidden HTML marker), the Action updates it in place rather than stacking new ones.
• Actions job summary: Written on every run. Headed "🦈 FlagShark Scan Results", it includes the health score, a metrics table, detected providers, and the top 15 stale flags. Visible under the Summary tab on the workflow run page, useful for scheduled scans and pushes to main where there is no PR comment.
• Status check: core.setFailed() is called when fail-threshold is exceeded or fail-on-error triggers a missing-in-platform error, failing the workflow step and any required branch-protection check wired to it.
• SARIF file: Written to the path specified by the sarif: input (optional). The sarif-path output contains the resolved absolute path.

Gating the merge

Set fail-threshold to block PRs whose health score falls below a target. Once the workflow has run on the default branch at least once, GitHub recognizes the check name and you can mark it required under Settings → Branches → Branch protection rules.

- uses: FlagShark/flagshark@v2
  with:
    fail-threshold: 80  # Block merges when health score drops below 80
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

With the default fail-threshold: 0, the Action only reports; it never fails the workflow even if your code is full of stale flags.

SARIF → GitHub Code Scanning

Set the sarif: input to emit a SARIF file, then upload it with github/codeql-action/upload-sarif@v3. Stale flags then appear in the repo's Security → Code Scanning tab alongside other static-analysis findings.

jobs:
  flagshark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: FlagShark/flagshark@v2
        id: flagshark
        with:
          sarif: flagshark.sarif
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ${{ steps.flagshark.outputs.sarif-path }}

For the full GitHub integration setup, see GitHub Integration.

Runtime details

The Action runs on Node 20.

Related Documentation

• FlagShark CLI: The same scanner, run locally or in any CI
• Configuration: .flagshark.yml for custom providers and exclusions
• Library (@flagshark/core): use the detection engine directly in your own tooling