Skip to content
Crow CI

CI quota enforcement and accounting

Crow can check CI allowances before starting workflows and report completed workflow runtime to the external CI quota reporter API provided by the CodeFloe Forgejo fork. This API is a CodeFloe extension and is not available in upstream Forgejo. Both variables are required to enable enforcement and reporting.

CI_QUOTA_URL

Section titled “CI_QUOTA_URL”
  • Name: CROW_CI_QUOTA_URL
  • Description: Base URL of the Forgejo instance that owns the CI quota ledger.
  • Example: https://code.example.com

CI_QUOTA_TOKEN

Section titled “CI_QUOTA_TOKEN”
  • Name: CROW_CI_QUOTA_TOKEN
  • Description: Dedicated reporter token configured under [quota.ci.reporter.<name>] in Forgejo.
  • Secret: yes

Crow reports each completed workflow separately, so parallel workflows consume their individual runner time. Queue time is excluded, and Linux, Windows, and macOS workflows are attributed to their respective runner classes. Reports use the workflow ID as an idempotency key and retry transient failures during the server process lifetime.

Platform agents

Section titled “Platform agents”

Crow sends the registered global agent name as runner_id in allowance checks and completed-workflow reports. Use those names in Forgejo’s per-reporter allowlist:

[quota.ci.reporter.crow]
TOKEN_HASH = <hex SHA-256 of the reporter token>
PLATFORM_RUNNER_IDS = public-linux-1, public-macos-1

The names must match exactly and uniquely identify your public agents. You can inspect registered names with crow admin agent ls. Numeric Crow database IDs are not used by this integration. Only listed global agents count toward the CI quota; an empty allowlist excludes all agents. Organization-scoped agents bypass both quota checks and reports, even if their name matches a public agent, because organization administrators control those names.

Forgejo accepts reports from unlisted global agents with HTTP 204 and omits them from the ledger. Crow treats this as successful processing and does not retry.

Workflow admission

Section titled “Workflow admission”

Before dispatching each workflow to an agent, Crow calls Forgejo’s /api/v1/quota/ci/check endpoint with the repository name, registered agent name as runner_id, and the same runner class used for accounting. Both the owner’s total allowance and any OS-specific cap apply. A denied workflow fails without running, with Forgejo’s reason shown as its error. Other independent workflows are checked separately, so a macOS cap does not prevent Linux work that still has an allowance. Workflows depending on the denied workflow follow the usual dependency failure rules.

Crow retries failed checks up to three attempts with a one-second delay between attempts, within a total budget of 20 seconds per workflow. Each agent poll finishes at most one refused workflow before the agent polls again, so an outage never holds a single poll open past reverse-proxy timeouts. If Forgejo remains unavailable, returns an authentication error, or sends an invalid response, the workflow fails without starting. After fixing the problem, restart the failed pipeline to try again. An agent that disconnects while its check is in progress does not fail the workflow; the queue treats it like any other task that was claimed but never delivered. Instances with neither quota variable configured continue to run without quota checks. The configured Forgejo instance must support both the usage and check endpoints.

Checks do not reserve minutes or stop workflows already running. Concurrent workflows can exceed the remaining budget because their usage is reported on completion.