> ## Documentation Index
> Fetch the complete documentation index at: https://smartcloud.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync

> Sync files from a template directory in another repository, and protect synced content.

The sync feature keeps files such as community health documents, issue forms, CODEOWNERS and workflows in line with a template directory in another repository. It is enabled by a `sync` section.

Sync needs a token that can read the source repository and push workflow files, which the workflow token cannot do. A [restricted run](/reporting#restricted-runs), such as one with only the workflow token or a pull request from a fork, skips sync and says why in the job summary.

```yaml theme={null}
sync:
  source: Resnovas/.github/templates@main
  values:
    COPYRIGHT_HOLDER: Jonathan Stevens trading as Resnovas
    SECURITY_EMAIL: security@example.com
  exclude:
    - .github/CODEOWNERS
  branch: smartcloud/sync
  check: true
```

| Key               | Default           | Meaning                                                                                                   |
| ----------------- | ----------------- | --------------------------------------------------------------------------------------------------------- |
| `source`          | required          | The template directory, as `owner/repo/path@ref`. The ref is optional.                                    |
| `values`          | none              | Values for `{{KEY}}` placeholders. Keys are upper snake case.                                             |
| `exclude`         | none              | Template paths this repository keeps its own copy of.                                                     |
| `branch`          | `smartcloud/sync` | The branch sync pull requests are opened from. It is force-updated, so it cannot be the default branch.   |
| `check`           | `true`            | Fail pull requests that edit synced content.                                                              |
| `maintainerLevel` | `warning`         | The level for a maintainer's or the owner's own edit to synced content. Contributors always get an error. |

## Syncing

On `schedule`, `workflow_dispatch` and `push` events, smartcloud renders every template in `source`, merges each into the matching file on the default branch, and opens or updates one pull request from `branch` with whatever changed, titled `chore(sync): sync files from owner/repo`.

* `{{KEY}}` placeholders are replaced from `values`. `{{REPOSITORY}}` is always available as the repository's `owner/name`. A placeholder with no value fails the sync rather than leaving a blank.
* Excluded templates are neither rendered nor synced, so a repository that keeps its own copy need not supply that template's values.
* An executable template makes its file executable.
* The commit is made through the GitHub API as the token's own identity, and signed off as that identity. GitHub signs it when the token is the workflow token or a GitHub App token, so it passes a ruleset that requires signed commits. Setting `SMARTCLOUD_COMMITTER_NAME` and `SMARTCLOUD_COMMITTER_EMAIL` commits and signs off as that identity instead, which GitHub does not sign.

## Managed blocks

A template without markers is synced whole. A template with a managed block is extendable: smartcloud only replaces the lines between the markers and keeps everything the repository adds around them.

```yaml .github/dependabot.yml theme={null}
version: 2
updates:
  # house:managed:begin
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
  # house:managed:end
  # house:local
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
```

| Marker                | Meaning                                  |
| --------------------- | ---------------------------------------- |
| `house:managed:begin` | Opens the managed block.                 |
| `house:managed:end`   | Closes it.                               |
| `house:local`         | Where the repository's own additions go. |

Markers count only on comment lines: `#` in YAML and CODEOWNERS, `<!--` in Markdown. The first time a file the repository already had is adopted, its previous content is kept, commented out, at the `house:local` line (or at the end), so nothing is lost silently.

Local additions that conflict with the synced rules are reported as warnings when syncing: a rule after a block that must come last (as in CODEOWNERS, where the last matching rule wins), a local YAML key, issue form field id or workflow job that redefines a synced one, or a Dependabot update that duplicates a synced one (in `dependabot.yml` or `dependabot.yaml`, one entry per directory in `directories`). Field ids are checked in issue and discussion forms only.

## The edit check

On pull request events, unless `check` is `false`, smartcloud flags edits to synced content with the rule id `SYNC`, as an error for contributors and a warning for maintainers and the owner (see `maintainerLevel`): a changed synced document, a changed managed block, removed markers, a deleted synced file, or a local rule that redefines a synced one. Change synced content in the source repository instead; a conflicting local rule is fixed in the repository itself. A conflict already on the default branch is left to the sync's warning, so it does not fail unrelated pull requests or the sync's own. Bringing a file in line with the latest templates is always allowed.

Pull requests in the source repository itself are not checked, since they legitimately change the templates.

Findings link to `GOVERNANCE.md#synced-files` under [`links.policyBase`](/configuration#links).