Step by step

Step by step

The whole life of an app with ncmake, in the order you meet it. Each step links to the page with the full detail; this page is the map.

1. Add ncmake to the app

Commit the bootstrap stub as your GNUmakefile, once:

curl -fLO https://raw.githubusercontent.com/ernolf/ncmake/main/bootstrap/GNUmakefile
git add GNUmakefile

That single file is all your repository carries. → Getting started

2. Run make and read the help

make

The first run fills the per-machine cache from GitHub; after that it is offline. make with no target prints the annotated help with your app id, version and certificate status detected from the app itself. → How ncmake understands your app, Target reference

3. Build and package

make build      # composer + npm, each in a throwaway container
make dist       # stage the runtime file set and pack the tarball

The tarball lands in build/artifacts/dist/<app_id>-<version>.tar.gz. The lock file decides between npm, pnpm and yarn, the bundler is whatever your build script runs, and the container images are kept current and removed again on their own. → Building and packaging, Build tools

4. Deploy to a test instance

make build && make rsync TARGET=/var/www/nextcloud/apps OCC=1     # reachable host
make build && make cp    TARGET=<container>:/var/www/html/custom_apps OCC=1   # container / AIO

rsync, cp and dist all deploy the identical staged file set, so what you test is what a release ships. → Building and packaging, Installation

5. Fetch the developer modules

The audit, workflow, App Store and integrity targets are developer modules, fetched once per machine:

make dev-init

From now on make help also shows the module targets, in this app and every ncmake app on the machine. Optionally, make skill-install puts the ncmake skill where an AI assistant finds it. → Target reference, AI assistant

6. Check the app

make consistency-audit   # do the metadata files agree with each other
make php-compat          # does it run on the PHP its servers run (after make build)
make build-verify        # does the committed build output come from the source beside it
make bundle-report       # what a browser loads per page
make build-audit         # what in the checkout makes it that size

All of them only report; none changes the app. → Checkout audit, Bundle analysis

7. Install the CI workflows

make workflows-list
make workflows-install W="release workflow-updater branch-cleanup lint-shell reuse lint-php lint-info-xml lint-php-cs psalm-matrix block-unconventional-commits" PR=1

An app with a frontend adds lint-eslint, its node workflow and lint-vue-imports. PR=1 commits the workflows together with their .ncmake-workflows.json lock file and opens the pull request. → Workflows

8. Let the workflows maintain themselves (optional)

Set up the GitHub App the updater authenticates with, and workflow-updater opens a pull request whenever a managed workflow drifts from upstream. branch-cleanup deletes merged branches, alone or together with GitHub's Automatically delete head branches. → Workflow updater, GitHub App, Deleting merged branches

9. Onboard to the App Store (once per app)

make csr         # generate the key, print the CSR to submit upstream
make register    # register id and certificate once the certificate is issued

→ App Store

10. Mark the app as signed (optional, once per app)

make integrity-enable    # copies the public certificate to .ncmake/certificate.crt
git add .ncmake/certificate.crt

From then on every release carries appinfo/signature.json, the hash list the Nextcloud server's integrity check reads: make tag produces it locally, where the key is, and the release workflow verifies it before it packs. → Integrity signature

11. Cut a release

make version     # on main: bump, branch ncmake/release/X.Y.Z, sync lockfiles
make changelog   # on the release branch: generate the section from conventional commits
# push, open the PR, merge
git pull
make tag         # on main: check the changelog, create and push the signed vX.Y.Z tag

make version also takes a pre-release such as X.Y.Z-rc.1. Publish the GitHub release so the release workflow attaches the tarball, then:

make publish GH=1

→ Releasing, App Store

12. Between releases and after them

make changelog without a pending version bump collects the new entries under ## [Unreleased], so the next release section is half written already. When an older release line needs fixes, make stable-branch opens stableX.Y from its newest tag. → Releasing

From here on

The updater keeps your workflows current, branch cleanup keeps the repository tidy, and each new release is step 11 again. Everything else stays derived from the app, so there is no scaffolding to maintain. → Why ncmake