Settings | Pages CMS

What `settings` does

Use settings for behavior that applies across the whole repository.

Typical uses:

hide admin pages,
preserve unmanaged keys when saving structured content,
define default commit messages,
choose commit identity behavior.

Keys

Key	Description
`hide`	If `true`, hides the Settings page in the UI.
`content`	Controls how structured content is saved. See `Content`.
`commit`	Controls commit settings. See `Commit`.

Content

For now, settings.content only supports merge.

Value	Behavior
`false`	Default. Rewrite the file from the configured schema only. Anything outside the submitted editor output is removed.
`true`	Merge the submitted fields into the existing file before saving. Keys outside the schema are preserved unless the editor overwrites them.

Commit

Commit templates

settings.commit.templates defines the default commit message format for content and media changes.

Key	Default value
`create`	`Create {path} (via Pages CMS)`
`update`	`Update {path} (via Pages CMS)`
`delete`	`Delete {path} (via Pages CMS)`
`rename`	`Rename {oldPath} to {newPath} (via Pages CMS)`

content[].commit.templates and media[].commit.templates override these global templates.

Within these templates, you can use any of the following tokens:

Token	Description
`{action}`	Current action: `create`, `update`, `delete`, or `rename`.
`{path}`	File path.
`{filename}`	File name only.
`{name}`	Content or media entry name.
`{owner}`	Repository owner.
`{repo}`	Repository name.
`{branch}`	Current branch.
`{user}`	Current user identifier. Kept for compatibility.
`{userName}`	Current user display name when available.
`{userEmail}`	Current user email when available.
`{oldPath}`	Previous path. Rename only.
`{newPath}`	New path. Rename only.
`{oldFilename}`	Previous file name. Rename only.
`{newFilename}`	New file name. Rename only.

Prefer {userName} and {userEmail} in new templates. {user} remains available as a legacy fallback.

Commit identity

settings.commit.identity controls whether Pages CMS sends explicit committer metadata on writes.

Value	Behavior
`app`	Default. Do not send explicit committer metadata. GitHub uses the authenticated writer identity for the request.
`user`	Send the current user's name and email as committer metadata when available.

content[].commit.identity and media[].commit.identity override the global setting for a specific schema.

Examples

Global commit templates and identity

settings:
  commit:
    identity: app
    templates:
      create: "content(create): {path}"
      update: "content(update): {path}"
      delete: "content(delete): {path}"
      rename: "content(rename): {oldPath} -> {newPath}"

Global default with a media override

settings:
  commit:
    identity: app

media:
  - name: assets
    input: public/uploads
    output: /uploads
    commit:
      identity: user
      templates:
        update: "media(update): {path} by {userEmail}"