Resources / File
File
File manages files in a single repository — CODEOWNERS, LICENSE, CI workflows, security policies, and any other files you want to keep in a declared state.
apiVersion: gh-infra/v1kind: Filemetadata: owner: babarot name: my-cli
spec: files: # Inline content - path: .github/CODEOWNERS content: | * @babarot
# Inline content with templating (<% %> expanded per repo) - path: go.mod content: | module github.com/<% .Repo.FullName %> go 1.24.0
# From local file - path: LICENSE source: ./templates/LICENSE
# From GitHub repository - path: .github/workflows/ci.yml source: github://babarot/shared-config/workflows/ci.yml
via: push # push | pull_request commit_message: "ci: add the managed files" # pr_title: "Add the managed files" # pull_request only # pr_body: | # pull_request only # <% range .Files -%> # - <% .Action %> `<% .Path %>`: <% .Description %> # <% end -%>Metadata
Section titled “Metadata”metadata: owner: babarot # GitHub owner or organization name: my-cli # Repository nameThe combination of owner and name identifies the target repository (babarot/my-cli).
| Field | Default | Description |
|---|---|---|
files |
(required) | List of files to manage — see File Sources |
files[].patches |
(none) | List of unified diff patches (file paths or inline) applied after template expansion — see Patches. |
files[].reconcile |
additive |
Per-entry reconcile mode: additive (add/update), authoritative (add/update/delete), or create_only (create if missing, never update) — see Reconcile. |
files[].executable |
(none) | true commits the file as executable (100755), false as non-executable (100644). When omitted, the current mode is kept. See File modes. |
files[].description |
(none) | What the file is for, written for the target repository. Listed in the default pull request body and available as .Files in messages — see Pull request description. |
via |
push |
Delivery method: push or pull_request — see Delivery Method. |
commit_message |
made from the changed files | Custom commit message. Accepts <% %> expressions such as <% .Repo.Name %> (see Templated messages) |
branch |
gh-infra/sync-<owner>-<name> |
Branch name for pull_request mode. Must differ from other pull_request resources on the same repository — see Pull request branch |
pr_title |
headline of commit_message |
Custom PR title (pull_request only). Templated like commit_message |
pr_body |
a line per changed file entry | Custom PR body (pull_request only). Templated like commit_message |
File content supports <% %> template syntax for per-repo customization — see Templating.
When to Use
Section titled “When to Use”Use File when you want to manage files in one repo’s YAML file. This is the simplest file management resource and the starting point for most users.
It works best when:
- Each repo has its own distinct files — different CODEOWNERS, different CI workflows, different licenses.
- You want per-repo change tracking — each file maps to one repo, so
git blametells you exactly who changed what and when. - You’re managing files in a small number of repos — for 1–5 repos, separate files are easy to maintain.
If you find yourself copying the same files across many repos, consider FileSet instead.