Skip to content
CodeCleared Docs
AppFrançais
Published

Last reviewed: 2026-07-25

GitHub Actions

Run CodeCleared scans from GitHub Actions using a protected service token, repository resolution, commit-aware requests, and safe timeout handling.

Purpose

Run a CodeCleared scan from GitHub Actions for the commit that triggered your workflow. This workflow resolves the connected repository first, then creates a scan using its UUID.

Who

A repository administrator configures the workflow and secret. An organization owner enables the repository and provides the least-privileged API credential/service token.

Prerequisites

Use an eligible plan with API access, connect the repository, and store the token as a GitHub Actions secret named CODECLEARED_TOKEN. Replace https://api.example with your customer API base URL.

Steps

name: CodeCleared scan
on:
  push:
    branches: [main]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Resolve, create, and wait
        env:
          API_BASE: https://api.example
          TOKEN: ${{ secrets.CODECLEARED_TOKEN }}
          REPOSITORY: ${{ github.repository }}
          COMMIT: ${{ github.sha }}
        run: |
          set -euo pipefail
          repo=$(curl --fail-with-body -sS -G "$API_BASE/v1/repositories/resolve" \
            -H "Authorization: Bearer $TOKEN" --data-urlencode "fullName=$REPOSITORY")
          repository_id=$(printf '%s' "$repo" | jq -r '.id')
          scan=$(curl --fail-with-body -sS -X POST "$API_BASE/v1/scans" \
            -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
            --data "{\"repositoryId\":\"$repository_id\",\"commitHash\":\"$COMMIT\",\"branch\":\"${{ github.ref_name }}\"}")
          scan_id=$(printf '%s' "$scan" | jq -r '.id')
          curl --fail-with-body -sS "$API_BASE/v1/scans/$scan_id/wait?timeout=300&interval=10" \
            -H "Authorization: Bearer $TOKEN"

Business rules

Resolve with GET /v1/repositories/resolve?fullName=owner/repo. Create with POST /v1/scans using repositoryId (UUID) and commitHash; branch, projectUnitId, and scanTypes are optional. Wait defaults to 300 seconds and cannot exceed 600 seconds.

Scenarios & edge cases

Fork or renamed repository: resolve the actual github.repository value and ensure it is connected. A wait expires: retain the returned scan ID and fetch status later; do not assume the scan failed. A pull request: choose the intended commit deliberately, because a merge commit and head commit can differ.

Limits

Do not log the token or embed it in YAML. Do not send fullName or commitSha to scan creation. A 402 indicates missing credit, plan entitlement, or MAU license (seat_license_required), not malformed JSON.

Common errors

  • Token absent from the environment because the secret is unavailable to the event.
  • jq returns an empty ID because repository resolution failed.
  • Repeating a 402 instead of reviewing credits and feature access.

Links