> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Files and Git-backed source
> Choose a first-class File for user input or an immutable Git-backed tree for repository work without treating FileTree as a universal resource.
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](/concepts/capabilities). 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:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
}
}'
```
```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/concepts/capabilities#skills) 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.
See how SkillVersion differs from repository content.
Retain knowledge under a different version and erasure boundary.