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 Makefile, once:

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

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. → Building and packaging

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 — what you test is what a release ships. → Building and packaging, Installation

5. Fetch the developer modules

The workflow and App Store 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. → Workflows, App Store

6. Install the CI workflows

make workflows-list
make workflows-install W="release reuse lint-php lint-info-xml lint-php-cs psalm-matrix block-unconventional-commits"
git add .github/workflows/

Commit the workflows together with their .ncmake-workflows.json lock file, and merge. → Workflows

7. Keep the workflows current (optional)

Install the updater and set up the GitHub App it authenticates with, and you get a pull request whenever a managed workflow drifts from upstream:

make workflows-install W=workflow-updater

→ Workflow updater, GitHub App (and GitHub PAT for the token background)

8. Have merged branches cleaned up (optional)

Tick Automatically delete head branches in the repository settings, install the shipped branch-cleanup.yml, or both. → 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. 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: create and push the signed vX.Y.Z tag

Publish the GitHub release so the release workflow attaches the tarball, then:

make publish GH=1

→ Releasing, App Store

From here on

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