Glossary¶

adopt — take a local file back under the hub: touchmark apply --adopt <glob> replaces it with the pack's current version. Also adopt_unmarked, the one-off operation that takes over a multi-gitter setup's pull requests.

automatic close — a sync pull request closed without merging by a bot (a GitHub Bot, an account in automation_accounts) or because its base branch is gone. Not a decline: the content comes back after memory.auto_close_cooldown.

content key — sha256: of every (path, from, mode, to) a pull request carries. The memory of declines compares by it.

decline — a sync pull request a person closed without merging. touchmark does not propose the same content to that repository again.

distribute — the command that writes: opens, updates and closes sync pull requests, with the writer, from the hub's default branch.

fingerprint — the hub's identity: the host and immutable repository id of the hub, like github.com/712345678; on Bitbucket the repository's UUID, lowercase and without braces, like bitbucket.org/3f2a8d4e-1b6c-4f0a-9e7d-5c2b1a0f9e8d; on Azure DevOps the repository's id, lowercase, like dev.azure.com/0b7e5a2c-9d4f-4e1b-8a3c-6f5d2e1c0b9a. In the commit trailers and the marker. CI provides it; --hub-fp outside CI.

hub — the repository, created from the template, that holds the packs, hub.yml, targets.yml and .touchmark/operations.yml.

hub channel — the hub CI's own token (GITHUB_TOKEN, CI_JOB_TOKEN, Gitea's token), used only towards the hub repository: the tip of its default branch, its visibility, its environment, the plan comment.

known_authors — former writers whose pull requests are still the hub's own.

local — the state of a file whose content matches no version the hub ever shipped at its path: the repository's own, never touched.

manifest — every version each pack ever shipped at each path, read from the hub's history. touchmark manifest prints it.

marker — the HTML comment at the end of a sync pull request's description: . It records the fingerprint and what the pull request carries. On Bitbucket Cloud, which shows HTML comments as text, the same payload is a Markdown link reference definition: [touchmark]: # "touchmark:v1 hub=… fp=… stream=sync key=sha256:… data=…". On Azure DevOps, whose descriptions hold 4 000 characters, the comment lives in the pull request property touchmark.marker instead of the description.

opt-in file — .engineering-assets.yml at a target's root. Its presence is consent; it can add packs and ignore paths, and enabled: false in it opts the target out.

opt_in: assumed — an entry of targets.yml that subscribes the repositories it selects: they count as opted in without an opt-in file. See targets.yml.

orphaned — the state of a file shipped only by a pack the target no longer gets, and still unchanged: left in place and listed.

pack — a directory packs/<name>/ of the hub, laid out like a target repository.

plan — the command that reports, with the reader, what distribute would do; it runs on every hub pull request.

probe — the check that the write key is not visible to jobs any branch can start: a job on GitHub Actions, touchmark probe on GitLab CI.

provenance — ownership decided by content: a file is the hub's while its content is a version the hub shipped at that path.

provider — a platform instance the hub delivers to, in hub.yml's providers, with its own reader and writer. Targets name it as <provider>:<path>.

reader — the read-only account plan uses.

sweep — the search for the hub's open pull requests in repositories that are no longer targets, to close them.

sync branch — touchmark/<id> in each target: one touchmark commit on the target's default branch.

sync pull request — touchmark's pull request (merge request on GitLab) from the sync branch.

target — a repository targets.yml selects: by path, by web URL, or through an organisation or group, narrowed by topics and match and minus exclude.

write isolation — keeping the write key visible to the default branch only: security.write_isolation (platform, external, none).

writer — the account distribute and doctor use, different from the reader, with no access to the hub.