Curvenote CLI

Curvenote Actions reference

The reusable workflows live in curvenote/actions and are called with uses: curvenote/actions/.github/workflows/<name>.yml@v1. Pin @v1 to receive compatible fixes automatically. For complete setups, see the single article and multiple articles configurations.

Secrets¶

Both secrets are required by draft and submit; push needs only CURVENOTE.

Secret	Value	Notes
`CURVENOTE`	`${{ secrets.CURVENOTE_TOKEN }}`	A Curvenote API token, stored as a repository or environment secret. Its user must be on the site’s team and allowed to submit (and to publish, for `publish: true`).
`GITHUB`	`${{ secrets.GITHUB_TOKEN }}`	Provided by GitHub automatically; nothing to create.

Permissions¶

Workflow runs on	Permissions	Why
A pull request (`pull_request`, `pull_request_target`)	`contents: read`, `pull-requests: write`	Read the code; comment on the pull request
A push or manual run (`push`, `workflow_dispatch`) with `submit`	`contents: write`	Comment on the commit
Any trigger, with `comment: false`	`contents: read`	No comment is written

Inputs for `draft` and `submit`¶

Input	Default	Description
`venue`	required	The Curvenote site to submit to, e.g. `scipy`.
`kind`	required	The submission kind, as configured on the site (case-sensitive).
`collection`	site default	The site collection to submit to. Quote numeric values, e.g. `'2026'`.
`path`	`.` (repository root)	Folder(s) to build, comma-separated. A trailing `/` means every immediate subfolder, e.g. `papers/`; subfolders starting with `.` or `_` are skipped.
`exclude`	none	Repository-relative folders to skip, in the same format as `path`.
`include-unchanged`	`false`	Build every folder matched by `path`, not only folders with changes.
`id-pattern-regex`	`^([a-zA-Z0-9-]{36})$`	Pattern every built `project.id` must match. IDs must also be unique and use only letters, digits, `-` and `_`. The default accepts a UUID.
`enforce-single-folder`	`false`	Fail when a pull request changes more than one `path` folder, or changes files outside them.
`label`	none	Run only when the pull request has one of these labels (comma-separated). Add `labeled` to the trigger’s `types`. Has no effect outside pull requests, where the workflow then never runs.
`comment`	`true`	Post a summary comment on the pull request or commit.
`comment-title`	`Curvenote Preview`	Title that identifies the comment to update. Set distinct titles when one workflow file calls `draft` or `submit` more than once; no title may be a prefix of another.
`ref`	the triggering ref	Branch, tag or SHA to check out.
`debug`	`false`	Run the CLI with debug logging.
`typst` / `images`	`true`	Use the full CLI image, with Typst, fonts and image tools. Set both to `false` for the smaller, faster slim image.
`fonts`	`fonts-noto`	Debian font packages for Typst PDF builds. Packages other than the default are installed at run time.
`strict`	`false`	`submit` only. Skip the submission when checks fail.
`publish`	`false`	`submit` only. Publish the submission immediately, with no review step. The token’s user must be allowed to publish. Don’t use it where untrusted authors control what is merged or labeled.

Push a work¶

push.yml uploads your content to Curvenote as a work, without submitting it to a site. You can submit the work later, or use it as a site’s landing content:

name: Curvenote push
on:
  push:
    branches: ['main']
jobs:
  push:
    uses: curvenote/actions/.github/workflows/push.yml@v1
    with:
      path: landing                 # optional: subfolder to push (default: repository root)
      landing-content: '<SITE>'     # optional: set as the site's landing content (site admins)
    secrets:
      CURVENOTE: ${{ secrets.CURVENOTE_TOKEN }}

push also accepts debug, typst, images and fonts. This documentation’s own landing page is published this way.

Troubleshooting¶

“The project IDs are not valid or are not unique”. A built folder has no myst.yml, has no project.id, or has an ID that doesn’t match id-pattern-regex, or two folders share an ID. The log names each folder. Fix the folder, or exclude it.
“Changes are made outside of a single folder”. enforce-single-folder is on and the pull request touches several articles, or files outside path. Split the pull request.
Nothing happens on a pull request. Check that the pull request has the label and that the trigger includes types: [labeled, …]. Also check that the workflow file is on the target branch: pull_request_target always runs the target branch’s version.
A fork pull request gets no preview. pull_request runs from forks don’t receive secrets. Use pull_request_target with a label, as described in Security and forks.
Comments overwrite each other. Two jobs in one workflow file share a comment-title. Give each a distinct title.

Set debug: true for verbose CLI logs. Each run also uploads the CLI logs as an artifact named submit-<id>.

Abbreviations¶