Maintaining the repository
Build from source covers the build: the sources, make.cmd, and what the checks look for. This page covers the rest of the repository — the CI workflows that are not written here, the bot that keeps them current, and the rules that make main unpushable. It is for maintainers; nothing on this page is needed to build, run or contribute to NcDavTray.
ncmake is a build system for Nextcloud apps. NcDavTray is neither a Nextcloud app nor a thing ncmake could build — only its workflow manager is used, which is app-agnostic: it installs CI workflows from their upstream templates and records what it installed.
| Workflow | Comes from | Does |
|---|---|---|
block-unconventional-commits.yml |
nextcloud/.github |
fails a pull request whose commit subjects are not Conventional Commits |
branch-cleanup.yml |
ncmake | deletes a merged pull request's head branch if it is still there |
workflow-updater.yml |
ncmake | refreshes the managed workflows from upstream and opens a pull request |
checks.yml |
— | this project's own, hand-written |
release.yml |
— | this project's own, hand-written |
The two at the bottom are listed as unmanaged: ncmake knows they exist and never touches them.
Templates are installed as they are, with one rewrite: runs-on: ubuntu-latest-low becomes ubuntu-latest, because that runner label only exists inside the nextcloud organisation.
Warning
ncmake also ships a release.yml of its own, which builds a Nextcloud app tarball. Installing it would overwrite this project's release workflow — the one that rebuilds from the tag and attaches the archive. Never install W=release here.
.github/workflows/.ncmake-workflows.json records, per managed workflow, where it came from, the upstream blob sha it was taken from, and the hash of the content that was written:
{
"branch-cleanup.yml": {
"hash": "621cfd0244b8b9…",
"sha": "0a5957bffde5b7…",
"source": "ncmake"
}
}It is generated, so it carries no SPDX header of its own — .ncmake-workflows.json.license supplies one (CC0-1.0), which is what keeps the REUSE check green.
The hash is what makes the updater safe: a workflow whose content no longer matches its hash counts as locally modified and is left alone. That is a decision, not a failure — but a modified workflow stops receiving upstream fixes, so it is worth being sure before editing one by hand.
flowchart LR
A["schedule<br>05:30 UTC"] --> B{{"make workflows-update"}}
B -->|nothing changed| C["done"]
B -->|drift| D["PR on<br>ncmake/ci/workflow-update"]
D --> E["merged"]
E --> F["branch deleted<br>by the same run"]
workflow-updater.yml runs make dev-init && make workflows-update from the repository root, daily at 05:30 UTC, and can be started by hand from the Actions tab (workflow_dispatch). GitHub starts scheduled runs on a best-effort basis and delays them under load, so a few hours late is normal.
It authenticates as a GitHub App, minted per run into a short-lived token. That is required — the default GITHUB_TOKEN may not push files under .github/workflows/ — and it is also what makes the commits verified. Its credentials live in the repository secrets:
| Secret | Holds |
|---|---|
NCMAKE_UPDATER_CLIENT_ID |
the app's client id |
NCMAKE_UPDATER_PRIVATE_KEY |
the app's private key |
The bot owns exactly one pull request. Writing @ncmake-updater rebase as a comment on it rebuilds its branch on top of the current main; the comment is answered only for OWNER, MEMBER and COLLABORATOR. The rebuild goes through the API rather than a git rebase in the runner, because a runner holds no signing key and would push unsigned commits.
The bot refreshes what is already listed. Adding one is a hand step, and it needs GNU make. That is what the Makefile in the repository root is: ncmake's bootstrap, a handful of lines that fetch the rest. It has nothing to do with building NcDavTray — make.cmd only borrows the name and is a PowerShell script.
Windows has no make, so the rare occasion when a workflow is adopted is done from a Linux checkout:
git clone https://github.com/ernolf/NcDavTray.git && cd NcDavTray
make dev-init
make workflows-list
make workflows-install W=branch-cleanup PR=1
dev-init fetches the ncmake modules into ~/.cache/ncmake/; nothing of ncmake lives in the repository except that bootstrap. workflows-list prints every available template with its state (installed, modified, unmanaged, or blank for available). workflows-install takes one name or several in quotes; PR=1 branches, commits and opens the pull request, COMMIT=1 stops after the commit, and without either it only writes the files.
Note
The checkout is disposable. It exists for this one command and can be deleted afterwards — the bot needs nothing on any machine of yours.
main is covered by a repository ruleset named main: require passing checks, shaped like the one in the other repositories here:
| Rule | Effect |
|---|---|
| Restrict deletions |
main cannot be deleted |
| Block force pushes | no rewriting of published history |
| Require signed commits | every commit on main is verified |
| Require status checks to pass | REUSE compliance · Build and static checks · Release archive builds · DCO · Block unconventional commits |
The status check rule is strict: a branch must be up to date with main before it can merge. The bypass list is empty, so this applies to the owner as well — every change, down to a typo in a comment, arrives as a pull request.
Tip
A pull request that waits forever for a check is almost always a branch that was cut before that check existed. Rebase it onto main and the check will run.
