Upload with the API

From the APICopy Anchor Link

You need an API key with the write:security-findings scope and a plan with API access. An upload takes three calls: create it, PUT the file, then complete it.

1. Create the upload with the file's name, size in bytes and SHA-256 (64 lowercase hex characters):

FILE=results.sarif
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA256=$(sha256sum "$FILE" | cut -d' ' -f1)

curl -s -X POST https://api.prodgator.io/v1/security/uploads \
  -H "Authorization: Bearer $PRODGATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"$FILE\", \"size\": $SIZE, \"sha256\": \"$SHA256\", \"format\": \"sarif\",
       \"repository\": \"acme/api\", \"category\": \"codeql-js\", \"gitRef\": \"main\", \"commitSha\": \"$GITHUB_SHA\"}"

The response is {"data": {"upload": {...}, "put": {...}}}. put holds a url, method (PUT), the headers to send and expiresAt (15 minutes). If the same file was already uploaded for the same repository, category and branch, put is null and nothing new is counted.

2. PUT the file to put.url with exactly the headers in put.headers (Content-Type and x-amz-checksum-sha256). The URL only accepts a file of the declared size and checksum:

curl -s -X PUT "$PUT_URL" \
  -H "Content-Type: application/json" \
  -H "x-amz-checksum-sha256: $CHECKSUM_HEADER" \
  --data-binary "@$FILE"

$CHECKSUM_HEADER is the value from put.headers (the base64 form of the SHA-256).

3. Complete the upload to start reading it:

curl -s -X POST https://api.prodgator.io/v1/security/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $PRODGATOR_API_KEY"

Prodgator checks the stored file's size and checksum. A mismatch deletes the file and fails the upload. Check progress with GET /v1/security/uploads/{uploadId}: status moves from queued to processing to done (or failed, with error), and counts gives the findings read.

Same name on more than one providerCopy Anchor Link

Prodgator keeps findings per repository, and a repository is its provider plus the id the provider gives it (GitHub repository id, GitLab project id, Bitbucket repository UUID, Azure Repos repository GUID), not its name. acme/api on GitHub and acme/api on GitLab are two repositories: their findings, tracked branches and release policy counts never mix.

An upload that names only the repository is matched to a provider like this:

• If exactly one of your providers has a repository with that name (or a linked account named like its owner), the report is for that repository.
• If more than one does, the upload fails with REPOSITORY_AMBIGUOUS. Send provider (and repositoryId if you have it) to say which one.
• If none does, the report is kept under the name alone until Prodgator sees the repository.

Reports sent by the Prodgator report action always carry the repository id from the run's OIDC token. A repository filter on the findings API follows the same rule: add provider (and optionally repository_id) when the name is on more than one provider.

A complete scriptCopy Anchor Link

Outside GitHub Actions, create an API key with the write:security-findings scope and upload the SARIF file in three calls (create, PUT, complete). This script needs curl, jq and sha256sum:

FILE=trivy.sarif
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA256=$(sha256sum "$FILE" | cut -d' ' -f1)
API=https://api.prodgator.io/v1/security/uploads

CREATED=$(curl -sf -X POST "$API" \
  -H "Authorization: Bearer $PRODGATOR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"filename\": \"$FILE\", \"size\": $SIZE, \"sha256\": \"$SHA256\", \"format\": \"sarif\",
       \"repository\": \"acme/api\", \"category\": \"trivy\", \"gitRef\": \"main\", \"commitSha\": \"$COMMIT_SHA\"}")
UPLOAD_ID=$(echo "$CREATED" | jq -r '.data.upload.id')
PUT_URL=$(echo "$CREATED" | jq -r '.data.put.url // empty')

if [ -n "$PUT_URL" ]; then
  curl -sf -X PUT "$PUT_URL" \
    -H "Content-Type: $(echo "$CREATED" | jq -r '.data.put.headers["Content-Type"]')" \
    -H "x-amz-checksum-sha256: $(echo "$CREATED" | jq -r '.data.put.headers["x-amz-checksum-sha256"]')" \
    --data-binary "@$FILE"
  curl -sf -X POST "$API/$UPLOAD_ID/complete" -H "Authorization: Bearer $PRODGATOR_API_KEY"
fi

An empty put means the same file was already uploaded for this repository, category and branch, and nothing new is counted. The fields and the status check are described above.