Files and Git-backed source

Checkfu does not use FileTree as the universal container for everything an Agent can read or change. Use the resource that owns the lifecycle you need:

Resource	Use it for	Authority boundary
File	One user-provided upload or artifact	File identity, content digest, retention, and Session attachment
Git-backed source	A repository tree resolved to an immutable commit	Repository identity plus a governed Connection for provider effects
Skill / SkillVersion	Reusable authored capability	Human-reviewed versioning and AgentVersion selection
MemoryStore / MemoryVersion	Retained knowledge across Sessions	Permissioned writes, proposals, curation, retention, and erasure

The currently served API still exposes /v1/file-trees for multi-file uploads and Git repository workflows. Treat that as the exact compatibility contract for those workflows, not as the final meaning of File, Skill, Memory, or every other resource.

Files

A File is a first-class Workspace resource. Upload it once, attach its ID to a Session, and let Session admission freeze the exact object the run may read. The Files API is intentionally small:

POST /v1/files uploads exactly one multipart file with an Idempotency-Key;
GET /v1/files/{id} reads its credential-free metadata; and
DELETE /v1/files/{id} removes it under the File lifecycle contract.

The upload limit is 64 MiB. A File is not a Credential store, a mutable folder, a MemoryStore, or a Skill. A Session that references a File records the selected File identity and content digest. Replacing a local file later does not change an admitted Session.

A customer-provided File can contain a secret if the customer uploads one. Do not put API keys, passwords, OAuth grants, session cookies, or provider tokens into Files merely because Checkfu never injects a custodied Connection Credential into a File.

Git-backed source

Use Git-backed source when the Agent needs a repository tree rather than one uploaded object. The source resolves a branch or ref to an exact commit and immutable tree before execution. Provider access goes through a governed Connection. The acting Principal must hold the required PermissionAssignment, and Checkfu rechecks live Connection authority before provider reads or writes. Checkfu does not inject or return the Git Connection’s custodied Credential value through the Session, sandbox, commit message, pull-request body, or event log. Repository bytes remain customer content. A committed secret can still reach the Agent because it is part of the selected tree; review and scan repositories independently of Connection credential custody.

Current FileTree compatibility operations

The current /v1/file-trees contract serves two narrow source kinds:

`source.kind`	Meaning
`upload`	A bounded multi-file tree published directly to Checkfu
`git`	A repository resolved through a Connection to an immutable commit

Each publication or refresh creates an immutable FileTree version. latest, a pinned version, or an already-published Git ref can select which version a Run receives. The resolved version is recorded with the Run. Create a Git-backed FileTree with the Principal that owns and may use the Connection:

curl --request POST https://api.checkfu.com/v1/file-trees \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-29" \
  --header "Idempotency-Key: project-support-site" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "support-site",
    "acted_as": "prin_…",
    "source": {
      "kind": "git",
      "provider": "github",
      "repository": "acme/support-site",
      "connection_id": "conn_…",
      "ref": "main"
    }
  }'

const project = await checkfu.projects.create(
  {
    name: "support-site",
    acted_as: principalId,
    source: {
      kind: "git",
      provider: "github",
      repository: "acme/support-site",
      connection_id: connectionId,
      ref: "main",
    },
  },
  { idempotencyKey: "project-support-site" },
)

A provider name in this example does not claim universal hosted support. The exact Connection, package, placement, scopes, and provider operation must be qualified and available.

Runtime overlays

A repository or multi-file tree can be mounted read_only or read_write. A writable mount gives the sandbox a disposable overlay. It does not mutate the source resource in place. Publishing work back to Git is a separate external effect. The current FileTree compatibility contract can push a new non-force branch and open a pull request through the same live Connection. Those mutations need stable idempotency keys, exact base versions, policy evaluation, and provider-side reconciliation. The human merge remains outside the Session. A Session-owned pull-request writeback policy may capture a bounded overlay at settlement under standard retention. Omission keeps the overlay disposable. Uploaded trees and zero-data-retention placements can reject writeback where retained content is required. A lost response after push or pull-request creation is not proof that the provider rejected the request. Reconcile the retained provider receipt or provider state before retrying; never turn uncertainty into a blind second Git effect.

Repository Skills

A frozen Git tree may contain repository-local Skill instructions at an admitted path. Those files remain repository content. They do not create a Skill resource or SkillVersion automatically. Mounting a repository is therefore also an instruction-trust decision. Review contributions before letting an Agent read repository-local instructions. Use a real Skill when you need an independently versioned, reusable capability.

Choosing the resource

Use a File for a document the user supplied. Use Git-backed source for a repository and explicit Git effects. Use a Skill for reusable authored capability. Use Memory for retained knowledge. Keeping these separate lets Session admission freeze the right selection policy and each Run record the exact version it receives. It also lets revocation target the correct authority and lets retention or erasure operate without inventing one mutable aggregate that owns everything.

Capabilities, Tools, and Skills

See how SkillVersion differs from repository content.

Memory

Retain knowledge under a different version and erasure boundary.

Get started

Understand Checkfu

Core concepts

Agent systems

Run sessions

Connect tools

Add context

Secure and govern

Automate and deliver

Files and Git-backed source

Files

Git-backed source

Current FileTree compatibility operations

Runtime overlays

Repository Skills

Choosing the resource

Capabilities, Tools, and Skills

Memory

​Files

​Git-backed source

​Current FileTree compatibility operations

​Runtime overlays

​Repository Skills

​Choosing the resource

Capabilities, Tools, and Skills

Memory

Files

Git-backed source

Current FileTree compatibility operations

Runtime overlays

Repository Skills

Choosing the resource