GC Ledger

Ingest gc-ledger events from a build

post

Records component drop observations (detected, moved) from a build's source scan. Each event upserts the ledger entry for the component on the branch.

Resolution states are never client-asserted: restored/handled transitions are derived server-side from published package manifests, and dismissals go through the dismiss endpoint with user identity.

Repeat detections of an unchanged state refresh the entry's lastEventAt without growing its event history. Dismissed entries are not re-opened by repeat detections.

Ingestion also triggers reconciliation of the branch's open entries against the latest published package manifests — builds with no drops still post (with an empty events array) so previously dropped components that were restored, moved, or covered by destructive changes get resolved.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Example: flxbl-io/sf-core

branchstringRequired

Branch the events were detected on

Example: main

commitShastringOptional

Commit SHA of the build that produced the events

buildNumbernumberOptional

Build number that produced the events

Responses

201

Events ingested and branch reconciled

No content

400

Invalid request body

401

Unauthorized

403

Forbidden - Requires role: application

post/sfp/api/gc-ledger/events

POST /sfp/api/gc-ledger/events HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 317

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "branch": "main",
  "commitSha": "text",
  "buildNumber": 1,
  "events": [
    {
      "type": "detected",
      "packageName": "core",
      "componentType": "ApexClass",
      "fullName": "LeadScoring",
      "packageType": "source",
      "packageVersion": "text",
      "baselineVersion": "text",
      "orgImpact": "auto-deletable",
      "movedTo": "text"
    }
  ]
}

No content

Query gc-ledger entries

get

Lists components dropped from packages across a repository, optionally scoped to a branch. Filter by status to see what is pending garbage collection (status=detected) or what has been resolved.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequiredExample: flxbl-io/sf-core

branchstringOptional

Branch to scope to; omit for all branches

statusstring · enumOptionalPossible values:

packagestringOptional

Filter by package name

limitnumberOptional

Max entries (default 100, max 500)

Responses

200

Ledger entries, newest first

No content

400

Missing repositoryIdentifier or invalid status

401

Unauthorized

403

Forbidden - Requires role: member, owner, application

get/sfp/api/gc-ledger

GET /sfp/api/gc-ledger?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Dismiss a gc-ledger entry

patch

Manually acknowledges a dropped component so it no longer shows as pending garbage collection. Dismissal is sticky against repeat detections; the entry only re-opens if the component is restored and dropped again.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Example: flxbl-io/sf-core

branchstringRequired

Branch the ledger entry belongs to

Example: main

packageNamestringRequired

Package the component was dropped from

Example: core

componentTypestringRequired

Metadata type of the component

Example: ApexClass

fullNamestringRequired

Full name of the component

Example: LeadScoring

reasonstringOptional

Reason for dismissing the entry

Responses

200

Entry dismissed

No content

401

Unauthorized

403

Forbidden - Requires role: member, owner, application

404

No ledger entry for the component

patch/sfp/api/gc-ledger/dismiss

PATCH /sfp/api/gc-ledger/dismiss HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "branch": "main",
  "packageName": "core",
  "componentType": "ApexClass",
  "fullName": "LeadScoring",
  "reason": "text"
}

No content

Apply org verification results for an environment

post

Records the verified presence of dropped components in one registered environment's org. When an entry is positively confirmed absent in ALL registered environments tracking the branch, it is removed from the ledger. unknown results never count as absent, and nothing is removed while zero environments are registered.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Example: flxbl-io/sf-core

branchstringRequired

Branch the checked entries belong to

Example: main

environmentstringRequired

Registered environment name the org was checked for

Example: qa

Responses

201

Results applied; confirmed-absent entries removed

No content

400

Invalid request body

401

Unauthorized

403

Forbidden - Requires role: member, owner, application

post/sfp/api/gc-ledger/org-check

POST /sfp/api/gc-ledger/org-check HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "branch": "main",
  "environment": "qa",
  "results": [
    {
      "packageName": "core",
      "componentType": "ApexClass",
      "fullName": "LeadScoring",
      "presence": "present"
    }
  ]
}

No content

Undo a dismissal

patch

Returns a dismissed entry to detected (pending cleanup). Only dismissed entries can be reopened; the action is recorded with the acting user.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Example: flxbl-io/sf-core

branchstringRequired

Branch the ledger entry belongs to

Example: main

packageNamestringRequired

Package the component was dropped from

Example: core

componentTypestringRequired

Metadata type of the component

Example: ApexClass

fullNamestringRequired

Full name of the component

Example: LeadScoring

reasonstringOptional

Reason for undoing the dismissal

Responses

200

Entry reopened

No content

400

Entry is not dismissed

401

Unauthorized

403

Forbidden - Requires role: member, owner, application

404

No ledger entry for the component

patch/sfp/api/gc-ledger/reopen

PATCH /sfp/api/gc-ledger/reopen HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "branch": "main",
  "packageName": "core",
  "componentType": "ApexClass",
  "fullName": "LeadScoring",
  "reason": "text"
}

No content

Last updated 3 hours ago

Was this helpful?