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, such as one with only the workflow token or a pull request from a fork, skips sync and says why in the job summary.

sync:
  source: Resnovas/.github/templates@main
  values:
    COPYRIGHT_HOLDER: Jonathan Stevens trading as Resnovas
    SECURITY_EMAIL: [e-mail]
  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.

.github/dependabot.yml

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.