Skip to content

Legacy act workflows ​

Development preview

This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.

Legacy act workflows use GitHub Actions syntax and run through act. Most files copied from .github/workflows/ work unchanged. This document lists exactly what the coordinator accepts, what it refuses, and what it adds. Behaviour that only the operator controls is in configuration.md; the design reasoning is in architecture.md. For the model behind the events, read Understanding Grasp CI.

Deprecation and migration ​

Act execution is deprecated in favor of native Nix workflows. Act is disabled by default. Both embedded-act and socket-adapter remain supported in this release; existing workflows continue to run when an act backend is enabled. Select --act-runner embedded-act explicitly for local act execution, or retain an explicit --act-runner socket-adapter configuration. Coordinators with either backend enabled emit a startup warning. Nix processing remains enabled independently; act-only coordinators also set --nix-workflows=false as explained in the migration guide. No removal release has been set.

Use the migration guide to choose a provider, port workflows and verify results before retiring act. Native workflows use a different schema: copying or renaming an act YAML file does not convert it. During migration, keep each workload enabled in only one workflow system to avoid duplicate jobs or publication effects. When migration is complete, disable act dispatch and retire its independently configured adapter and Docker dependencies as described in that guide.

Where files live ​

text
.grasp/act/workflows/<name>.yml     # or .yaml

The legacy .ngit/act/workflows/ directory remains supported. When .grasp/act/workflows/ exists at the selected commit, only that act directory is discovered; otherwise the legacy directory is used. Move the whole directory together to avoid leaving workflows behind. This choice is independent of the native Nix directory, and signed results retain the actual path.

Files in .github/workflows/, .forgejo/workflows/, .gitea/workflows/, and .gitlab-ci.yml are detected but never executed. The separate directory lets one repository target Grasp CI without changing what its GitHub or Forgejo mirrors run, and lets you keep the two sets different when you want to.

Workflow files and their parent directories must be real files and directories, not symlinks. Discovery rejects links before reading their targets.

A coordinator reads the files at the exact commit that triggered the run, and every result names the file by path and by the SHA-256 of its content at that commit.

Nothing runs until service is requested ​

A coordinator advertises whether ordinary workflows are automatic or request-required. Under the default, request-required policy, push and pull request workflows wait until a maintainer publishes a standing Service Request naming that coordinator and the repository. The request is not tied to a commit; a Service Stop ends it. Manual triggers are one-shot and need no standing request. Maintainers request service from gitworkshop.dev or with ngit ci request, as described in Request service; the event shapes are in NIP.md.

Triggers ​

on: keySupportedNotes
pushYesFires when the signed repository state adds or moves a branch or tag
issuesYesOpened, closed/resolved and reopened issues; checkout uses the signed default branch
pull_requestYesFires on a Nostr PR or PR update; the PR head is the checkout
workflow_dispatchReplay onlyNot a trigger, but a manual run uses this event if the file declares it
scheduleNoNothing fires on a timer
Anything elseNoIgnored
yaml
on:
  push:
    branches: [main, "release/**"]
    tags: ["v*"]
    # Or use branches-ignore / tags-ignore, not both forms for one ref type.
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

Pull request activity types ​

pull_request follows GitHub's activity model. Without a types: key, a workflow runs on opened, synchronize, and reopened — the GitHub defaults. This applies equally to on: pull_request, list syntax, and an empty pull_request: mapping. The coordinator enforces activity filtering; act's event-name planner alone does not enforce types:. List types: to opt into other activity, notably ready_for_review for draft → ready transitions:

yaml
on:
  pull_request:
    types: [ready_for_review]

Nostr PR lifecycle events map onto activity types like this:

Nostr eventActivity typeDefault run?
PR (kind 1618)openedYes
PR update (kind 1619)synchronizeYes
Status draft (kind 1633)converted_to_draftNo
Status open after draft (kind 1630)ready_for_reviewNo
Status open after close (kind 1630)reopenedYes
Status closed/merged (kind 1632/1631)closedNo

Only statuses from the PR author or a confirmed maintainer count, and a status that restates the current state (e.g. a bare open on an already-open PR) runs nothing. Status events SHOULD tag the repository with an a tag so the coordinator's subscription finds them. In the job's event payload, github.event.action carries the activity type and github.event.pull_request.draft / merged carry the PR flags.

A manual run, from ngit ci trigger or GitWorkshop's retry button, replays any file regardless of its on: clause. It runs under workflow_dispatch if declared, otherwise under push or pull_request, and its results say manual. Issue-only act workflows must declare workflow_dispatch to support manual runs; a manual run does not synthesize an issue identity or lifecycle payload.

Issue activity ​

Both act and native Nix workflows support:

yaml
on:
  issues:
    types: [opened, closed, reopened]

Without types, all three supported activities match. Comments, edits, labels, deletions, and draft statuses do not fire issue workflows. Kind 1621 produces opened; a transition to kind 1631 (resolved) or 1632 (closed) produces closed; kind 1630 after either produces reopened. Open, resolved and closed are distinct states: switching between resolved and closed also produces closed, with the new state's reason. Only restatements of the same state are ignored. Only the issue author or a current confirmed maintainer may change its status, following the existing PR status rule.

Issue roots share the repository-coordinate PR activity filter. Status events use the existing status kinds and must carry a repository a tag for discovery, just like PR statuses. The coordinator resolves the referenced root to distinguish issues from PRs; it does not add per-issue subscriptions. Events must be within the shared 30-minute activity window. Older roots and status history may be fetched as context for a recent transition, but that context never starts historical jobs.

Workflow discovery and checkout use the exact signed default-branch commit selected at admission. Issue content and status text cannot select a branch, commit or clone URL. Missing default-branch state waits within the activity deadline; it never falls back to an arbitrary checkout. Standing execution policy and the existing confirmed-maintainer secret rules apply; an external issue author does not gain secrets by opening or closing an issue.

Act receives github.event.action, issue.id, issue.title, issue.body, issue.user.id, issue.state, issue.state_reason, sender.id, and nostr_event_id. IDs are Nostr event IDs/public keys, not GitHub numbers or logins. Closed reasons are completed for resolved and not_planned for closed; open/reopened payloads have a null reason. These strings are untrusted event data. Native Nix context is documented in Nix workflows.

Ref filters ​

branches, branches-ignore, tags, and tags-ignore accept exact names, *, prefix*, and prefix/**. Combining an include and an ignore filter for the same ref type is invalid on GitHub and the coordinator treats it the same way: the workflow does not run. A push with no filters runs for every branch and tag; declaring only branches excludes tag pushes, and only tags excludes branch pushes. PR branch filters match the immutable root PR's b target branch, falling back to the signed repository default when absent. Revisions and status-triggered runs inherit that target; branch-name is a source checkout suggestion and does not choose the target.

Path filters ​

paths and paths-ignore use GitHub glob syntax (*, **, ?) on both triggers. Inside paths, ! patterns exclude files; positive and negative sets are matched independently, so order-sensitive re-inclusion is not supported. A paths list must contain at least one valid positive pattern; invalid globs and exclusion-only lists fail closed and never match.

Path filters are not evaluated for tag pushes. For a push, the changed set is the diff from the previous commit at that ref. For a PR it is the diff from the merge base with the PR target branch. Its exact tip comes from the latest accepted repository state's signed ref tag. Without an explicit PR target, the default comes from signed HEAD; if unavailable, path comparison can resolve the target clone server's HEAD, falling back to master then main. An explicit target with no signed tip stays unknown and never falls back to a different branch. Contributor-provided PR clone URLs supply the PR history but never choose the base. When the changed set cannot be computed (first push of a branch, a force push that discarded the old commit, an incomplete repository state, or a PR more than 256 commits from its base) the workflow runs as if it had no path filter.

runs-on decides who runs the file ​

A coordinator claims a workflow as a whole file, and only when it supports the runs-on labels of every job. A file nobody can serve is skipped silently: no run, no result, no error. That is deliberate, so a coordinator on the right platform can pick it up instead.

  • Labels must resolve statically: a string, a list, group.labels, or a matrix.<key> expression over a static matrix, including include entries. Any other expression makes coordinators skip the file.
  • A list is satisfied by any one label. Matching is case-insensitive.
  • ngit-ci's default labels are ubuntu-latest, ubuntu-24.04, and ubuntu-22.04. Operators may add others, such as ubuntu-24.04-arm.
  • macOS and Windows labels cannot be served. Jobs run in Linux containers.

Check what your coordinator advertises before choosing labels: Choose a coordinator.

More than one architecture ​

Use one file per architecture: ci.yml with runs-on: ubuntu-latest and ci-arm.yml with runs-on: ubuntu-24.04-arm. Each file is claimed by the matching coordinator, and clients combine the independently signed results per commit.

A single file whose jobs span architectures, or whose matrix.os axis does, runs only where one coordinator supports every label at once. Avoid cross-architecture needs, such as a release job that needs both build-amd64 and build-arm64: job chaining is resolved inside one act invocation, so that fan-in can never be split across machines. Splitting a file across coordinators by needs-connected job groups is on the roadmap.

Jobs ​

  • Independent jobs run in parallel, up to the executing host's CPU count.
  • needs: ordering and needs.<job>.outputs.* work as on GitHub.
  • A static strategy.matrix works; matrix values built from expressions do not.
  • There is no chaining across files or across runs.
  • The whole run is subject to the coordinator's timeout, 30 minutes by default. On expiry the workflow concludes timed_out and a diagnostic Job Result named ngit-ci timeout diagnostic (job id __ngit_ci_timeout__) carries the partial output: setup, VM boot, checkout, Docker readiness, and workflow steps. It is not a job you declared.

Step timings ​

Give meaningful id and name values to steps you want to compare across runs. Job Results include bounded step summaries recovered from act's structured terminal records, with labels from secret-masked log messages and measured execution durations. Separate compilation and execution into different workflow steps when that distinction matters (for example cargo test --no-run followed by the same cargo test command and flags).

Start offsets are omitted because act's captured timestamps are wall-clock values, not monotonic offsets. Missing/truncated records can leave summaries incomplete; an absent step does not establish that it did not run. Pre/post and composite actions receive distinct generated identifiers where necessary. Full logs and the event's log tail remain available as before. See the Job Result format.

Refused by default ​

The operator owns the job container, so under the default policy these are refused, and the refusal is published as a startup_failure Workflow Result rather than a silent skip:

DeclarationDefault outcome
container: or services: with options or volumesRefused
Any container: or services: when the operator sets container optionsRefused
Job-level uses: (reusable workflows)Refused
Composite actions used from a stepAllowed

An operator who trusts workflow authors can switch to the workflow policy, which restores act's native behaviour. See job container policy.

The runtime environment ​

  • Jobs run in act's catthehacker/ubuntu:act-* images, not GitHub's runner VMs. A GitHub-compatible full runner image is over 18 GB and bundles third-party and proprietary software; act's lighter images deliberately do not reproduce it. Tools you expect may be missing or differ in version, path, or service configuration. Install what you need with a setup action or a package step.
  • Put actions/checkout before any step that reads the repository. It maps to the coordinator's checkout of the trigger commit, with Git metadata. The step is required when the coordinator copies workspaces through the Docker API, as the supplied Compose deployments do. Checking out a different private repository does not work.
  • Outbound network access is available. There is no container daemon, so docker commands fail unless the operator opted in.
  • These variables are set on every job:
VariableValue
GITHUB_SHAThe commit that ran
GITHUB_REFThe Git ref for a push, or refs/pull/ngit for a PR unless the trigger supplied one
NGIT_CI_REPOSITORYThe repository coordinate, 30617:<pubkey>:<identifier>
NGIT_CI_TRIGGER_EVENTThe id of the Nostr event that triggered the run

For a tag-triggered run, the exact refs/tags/<name> ref is present in the checkout. Annotated tags retain their tag object, message, tagger, and date. The checkout remains shallow, so unrelated history and refs may be absent.

There is no GITHUB_TOKEN and github.token is empty. Actions that require a token need an explicit value; see the cache note below.

To use ngit or a nostr:// remote inside a job, add the setup action, which installs ngit and git-remote-nostr from a checksum-pinned manifest and also works on GitHub-hosted runners:

yaml
- uses: danconwaydev/setup-ngit@v3
  with:
    version: 3.0.0    # optional

Secrets ​

The secrets context is populated only with names provisioned for this repository, and only when the run's trigger was authored by a confirmed maintainer: a push, or a PR or PR update authored by a maintainer. A third-party PR always runs with empty secrets, so a workflow that must work for contributors cannot depend on one. Anything not provisioned is empty, so everything else the job needs must be fetchable anonymously. Maintainers provision values from gitworkshop.dev, encrypted to the coordinator as a kind-29846 Repository Secret Update, or the operator supplies them out of band; see Configure secrets and per-repo secrets.

Names match [A-Z_][A-Z0-9_]*. Names that collide with runtime variables are rejected, including PATH, HOME, CI, DOCKER_HOST, NIX_CONFIG, and anything starting GITHUB_, NGIT_CI_, RUNNER_, or ACTIONS_.

One name is special. If a maintainer provisions GH_READ_TOKEN, the coordinator also writes it into NIX_CONFIG as a GitHub access token for authorised runs, so locked flake inputs of type github fetch without a workflow change. It authenticates nothing else, and it remains available as ${{ secrets.GH_READ_TOKEN }} for steps that configure other tools. See GH_READ_TOKEN and Nix GitHub inputs.

If the repository's secrets are bunker-sealed and the decryption bunker does not respond, a run that was authorised to receive them fails with startup_failure rather than running without secrets. The published diagnostic Job Result carries the reason.

Artifacts ​

actions/upload-artifact@v4 and download-artifact work within one run. When the operator has enabled Blossom uploads, files are published through direct artifact tags or artifacts manifests according to the packaging rules below. Blossom URLs commit to SHA-256 hashes; a later consumer can fetch and verify the published files.

The official upload action may print a GitHub-shaped artifact-url. Under ngit-ci this is compatibility output from act, not a public download URL: act first stages the artifact on its per-run local server, then ngit-ci uploads the files to Blossom after the workflow finishes. Use the URLs in the signed Job Result for public downloads.

The coordinator matches each staged archive to the runtime outputs of the concrete job that uploaded it, including individual matrix jobs, so a Job Result advertises only its own files. Uploads hidden inside a composite action or reusable workflow need the upload step's outputs to stay visible, or the export fails rather than attributing files to the wrong job. Third-party Loom adapters must implement the optional artifact-streaming extension in execution-adapter-protocol.md to carry uploads. Without Blossom enabled, pass data between jobs with outputs or combine steps into one job.

Artifact storage configuration ​

With storage omitted, the default uses individual Blossom files and direct artifact tags below 25 files across the job's newly exported outputs. At 25 or more, outputs without overrides are bundled into one catch-all ZIP and manifest, published with one artifacts tag. Existing groups passed through from an earlier result retain their tags without repacking and do not contribute to this threshold. If the result would exceed its event-size budget sooner, use manifests early. There is no workflow setting to force a tag format. See the manifest contract and storage tradeoffs.

Per-artifact overrides remove those files from the automatic catch-all:

  • storage: individual keeps separate Blossom blobs, useful for nsite reuse. At the job-wide threshold (or event-size limit), these files use a manifest without a ZIP; otherwise they use direct tags.
  • storage: archive always produces a separate ZIP and manifest, even below the threshold. Without package, this group contains just that named artifact.
  • package: <identifier> groups artifacts into a named package, with its own manifest and artifacts tag. With storage omitted, an explicit package uses a ZIP regardless of count; individual instead produces a blob manifest. Artifacts sharing a package must agree on storage (omission and archive both select ZIP storage here). Conflicting settings are configuration errors.

The optional tag fields carry the manifest's file count and, for explicit packages, its identifier. The catch-all has no package identifier. Artifact names and filenames remain in the manifest, independent of packaging. Counts and package labels help display and configuration matching; content validation still requires the manifest. ZIP exports use deterministic packaging.

For act, the job-level ngit.artifacts map is keyed by the exact runtime actions/upload-artifact name. It configures public export without adding inputs to the standard action or changing act's internal upload-artifact/download-artifact handoff. Names without an override use the automatic catch-all policy; they do not each create a separate archive. ngit-ci removes these settings from a private execution copy before act's schema validation; the checkout and signed workflow hash retain the original file. Settings are scoped to the selected workflow: do not put ngit metadata in separately referenced reusable workflow files, which act reads unchanged.

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    ngit:
      artifacts:
        site:
          storage: individual
        test-results:
          package: diagnostics
    steps:
      - uses: actions/checkout@v4
      - run: ./build-and-test
      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: dist/site/
      - uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-results/

Artifact export is complete or fails the job: missing files, unsafe paths, limit violations, and failed uploads never produce a successful partial inventory. The configured per-file and per-job file-count limits still apply. Staged act exports are additionally bounded to 100,000 files and 256 MiB of uncompressed files across a workflow; each uploaded blob is limited to 256 MiB.

The exporter preserves the action's artifact name and relative member paths. The act transport ZIP may be unpacked or repacked for publication according to this setting. Files inside it that are themselves .zip, .tar.gz, or other archives remain ordinary files; their contents are not recursively unpacked.

Public outputs and PR previews ​

Ordinary job outputs become public output entries on the Job Result:

yaml
jobs:
  preview:
    runs-on: ubuntu-latest
    outputs:
      nsite_preview: ${{ steps.publish.outputs.url }}
    steps:
      - id: publish
        run: |
          # Publish the preview, then expose its public URL only after success.
          preview_url=https://preview.example
          printf 'url=%s\n' "$preview_url" >> "$GITHUB_OUTPUT"

The coordinator publishes that value on the job's kind-9841 event as ["output", "nsite_preview", "https://preview.example"]. Only literal values and a direct steps.<id>.outputs.<name> expression resolve. Each value is limited to 8 KiB and a job to 64 KiB of outputs in total; files belong in artifacts. An output that was declared but never set is published as omitted with a reason (missing, oversized, or unresolved) instead of an empty string, and an empty value is a real output. Output values are public Nostr tags: never put a credential in one.

Nsite preview convention. An output named nsite or starting nsite_ whose value is the URL of a successfully published nsite is recognised by GitWorkshop as a pull request preview and shown with an "Open nsite preview" button and an untrusted-content warning, because the PR's code controls the value. Create a fresh Nostr identity inside the job rather than injecting a maintainer key; the signed CI result is the durable link between the PR, the commit, and that disposable identity. ngit.dev's own documentation workflow does exactly that with ngit account create --local followed by ngit nsite publish. Choose Blossom servers that accept ephemeral upload identities and treat limited retention as acceptable; if the upload or the manifest publication fails, fail the job without setting the output. Long-lived production sites still need a maintainer-authorised signer and belong in trusted runs.

Caching ​

The coordinator runs an actions/cache-compatible server by default, scoped by repository and by trigger author's trust, so a third-party PR never reads or writes the maintainer cache. Use actions/cache@v4 or nix-community/cache-nix-action as usual, and mark cache steps continue-on-error: true so a coordinator with caching disabled still runs the job:

yaml
- uses: cachix/install-nix-action@v31
  with:
    nix_path: nixpkgs=channel:nixos-unstable
- name: Restore Nix store cache
  continue-on-error: true
  uses: nix-community/cache-nix-action@v7
  with:
    primary-key: nix-${{ runner.os }}-${{ hashFiles('**/*.nix', 'flake.lock') }}
    restore-prefixes-first-match: nix-${{ runner.os }}-
    token: unused
- name: Restore Rust build cache
  continue-on-error: true
  uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/git
      ~/.cargo/registry
      target
    key: rust-${{ runner.os }}-${{ hashFiles('**/Cargo.toml', 'Cargo.lock', 'flake.lock') }}
    restore-keys: |
      rust-${{ runner.os }}-

The token: unused placeholder is required: cache-nix-action reads its token input unconditionally, its default is the empty github.token, and without a value both phases abort. Any non-empty string works because the token only reaches GitHub through the action's purge feature, which is off by default; do not enable purge. Treat cache contents as an optimisation, never as an input to correctness or secrets. The partitions are described in Cross-run build cache.

Running the same workflow on GitHub ​

A coordinator runs only the workflow paths it advertises, under .ngit/<runner-format>/workflows/, so it never touches .github/workflows/ and the two systems run side by side. A check that must run on both exists in both places. Differences to expect when you copy a file across: no GITHUB_TOKEN, lighter images, refused container: blocks, and whole-file claiming by runs-on.

Reading the results ​

For each run, a coordinator publishes a Workflow Progress marker (kind 39842) while the run is queued or in progress, a Job Result (kind 9841) per job, and a Workflow Result (kind 9842) with the conclusion. All of them name the commit, the workflow path with its SHA-256, and the normalised trigger, and clients such as gitworkshop.dev show them against commits and PRs. When several coordinators cover different platforms, each publishes its own signed result. The event shapes are in NIP.md.

If nothing ran, the usual causes, in order: no watching coordinator supports the file's runs-on labels, the trigger or its filters did not match, or runs-on could not be resolved statically. A file the coordinator refused produces a startup_failure result, not silence. See When no run appears.