How-to guides

Operate and troubleshoot Flint

Inspect Flint resources, configure provider mappings safely, read bounded logs, cancel or replay runs, and diagnose native execution, cleanup, and publication failures.

Preview contract. These operational guides describe unreleased source, not a shipped-release or deployment claim. Match your build's help and bundled skill before using commands. Check compatibility.

Inspect and allocate resource pools

  1. Run rune --json exe --repo "$FLINT_PROJECT" resources. Read the returned artifact before submitting jobs that need shared services.
  2. Have the operator define RUNE_SETTING_FLINT_RESOURCES_JSON for the intended environment. The source's fallback postgres and redis pool names are accounting defaults, not running databases.
  3. Use the job's requires list for the configured resource names. Inspect available slots and quarantine state before retrying a waiting job.

A resource definition uses this shape. The names and environment values are examples, not a provisioning command:

[{
  "name": "postgres",
  "slots": 1,
  "grace_seconds": 60,
  "environment": {"DATABASE_SLOT": "${RESOURCE}-${SLOT}-${JOB_ID}"}
}]

Optional acquire_hook and release_hook objects declare a selector, bounded arguments, and timeout_ms. The selector must resolve through RUNE_PROCESS_POLICY_JSON. The Scheme policy renders ${JOB_ID}, ${RESOURCE}, and ${SLOT}. Do not replace a selector with an arbitrary executable path in a workflow.

Flint heartbeats held leases during native work. Failed cleanup or a failed release hook quarantines a slot. Preserve the failure evidence and let the operator inspect the sandbox and hook result. Do not mark a slot free by editing SQLite or asserting cleanup succeeded.

Prepare a provider integration without implicit exposure

These steps describe prerequisites for an authorized operator. They do not activate a public service. Review the trust of each repository and workflow before adding a mapping.

  1. Choose GitHub, Forgejo, or Gitea. Store its exact-body webhook secret as RUNE_CREDENTIAL_<SERVICE>_WEBHOOK_SECRET. Service prefixes are GITHUB, FORGEJO, and GITEA.
  2. Define RUNE_SETTING_FLINT_REPOSITORIES_JSON as an array mapping a lowercase service, exact repository, and operator-approved workflow object. A private checkout can name checkout_credential_name. Keep the secret itself outside the workflow.
  3. For publication, supply RUNE_CREDENTIAL_<SERVICE>_STATUS_TOKEN and RUNE_SETTING_<SERVICE>_STATUS_AUTHORITY. Allow the outbound authority explicitly through RUNE_HTTPS_ALLOWED_AUTHORITIES. Configure checkout authority and content separately.
  4. Review the local listener, proxy, TLS, request-size limit, authentication, and access policy before any public exposure. The checked-in listener is disabled. Webhook signing is not general authentication for the operation endpoint.
  5. Use the provider's signed delivery to the exact webhook route. Preserve the exact bytes and required signature and delivery headers. Inspect rejection and publication diagnostics using private logs.

A mapping has the following shape. Replace the sample repository and workflow with reviewed inputs. This object is not a real integration:

[{
  "service": "github",
  "repository": "owner/project",
  "workflow": {
    "schema_version": 1,
    "name": "sample",
    "jobs": [{"id": "build", "needs": [], "steps": [{"run": "true"}]}]
  },
  "checkout_credential_name": "CI_CHECKOUT"
}]

A signed payload selects a configured mapping and a validated 40-character head SHA. A webhook-supplied workflow is never executed. The matched candidate also validates pull-request base and head metadata. Credentials remain opaque Rune handles, and status I/O stays outside job sandboxes. Read status publication separately from job completion. A successful job does not prove that the provider received its status.

Inspect, cancel, or replay a run

First use status, logs, and explain against the actual run identifier. Preserve the run and artifact references before a new attempt. Logs are bounded, not a guarantee of an unlimited transcript.

To persist cancellation for a run you intend to stop, use:

rune --json exe --repo "$FLINT_PROJECT" cancel --run-id "$RUN_ID"

Read the domain result and cleanup disposition. Cancellation is not proof that a process tree is gone. If cleanup cannot be proved, the implementation fails closed and affected slots can remain quarantined.

To create a replay after inspecting a terminal run, use:

rune --json exe --repo "$FLINT_PROJECT" replay --run-id "$RUN_ID"

Replay creates a new queued run from the stored workflow with replay_of pointing to the prior run. It does not replace history. The CLI replay handler creates the run; a running service worker is needed to drive queued work. A repo-only replay command does not itself prove that the new jobs executed. Inspect the new run identifier and state before reporting an outcome.

MCP request cancellation, where a transport exists, stops the protocol request. The registered flint.cancel_run operation is the separate persistent CI-domain action. Do not treat the two as equivalent.

Find the failing boundary

  1. Record the matched Rune build, project version, run ID, job ID, and actual command result. Confirm that all commands select the same repo or named deployment and private state.
  2. If the workflow is rejected, inspect the error and pointer. Check schema version, duplicate job IDs, dependency names, cycles, conditions, action pins, image digests, and matrix limits. Do not assume every GitHub Actions construct is supported.
  3. If native execution fails before a step, inspect the rootfs, cgroup delegation, namespace availability, overlayfs, state-path length, and service-account permissions. A macOS sandbox error is not a job failure on supported Linux.
  4. If a job waits for leases, inspect resource availability and held leases. If a slot is quarantined, have the operator inspect native cleanup and release-hook evidence.
  5. If a command summary says it executed but the run failed, read the nested domain artifact. Inspect job states, expected job count, bounded logs, and explain output.
  6. If the provider shows no status, inspect the publication queue, authority allowlist, status token handle, retry state, and receipt. Keep provider failure separate from job outcome.
  7. If HTTP returns 404, compare method, path, active bundle, and versioned envelope. Registry operation annotations do not guarantee callable routes.
  8. If recovery blocks startup, preserve state and evidence. Do not delete the database, force-release leases, bypass cleanup proof, or enable extra privilege to make a green check.

Share sanitized diagnostics through your existing support channel. Remove credentials, private paths, repository names, raw provider bodies, and personal logs. The error reference identifies contract-level failures without implying that every error is retryable.

Back to top