Publish a graft
To let other Orchard instances install your graft, sign it and publish it in one of three ways. An https address needs only a file host. A listing in the Extension Marketplace lets operators find the graft with orchardctl graft search.
- From any
httpsaddress. - From a tap: your own catalog of grafts.
- From the Extension Marketplace, as a community graft.
Sign a graft
Section titled “Sign a graft”A packed .graft is a tar.gz file with graft.json, the built code, migrations, a MANIFEST.json listing the SHA-256 of each file, and MANIFEST.sig, an ed25519 signature over that list.
graft keygen ~/.config/graft/key.pemgraft pack --key ~/.config/graft/key.pemThe command prints the public key. Operators add it to graftSettings.keys to trust your grafts.
In CI, set GRAFT_SIGNING_KEY to the base64 of the private key, instead of passing --key.
Share a graft from an https address
Section titled “Share a graft from an https address”-
Upload the
.graftfile to anhttpsaddress. Use a separate address for each version. -
Give operators this command:
sudo orchardctl graft add https://example.com/snippets-0.1.0.graftFor Helm values, they use the entry that
graft packprinted, withsourceset to the address.
The digest pins the exact file. If the file at the address changes, installs fail.
Run a tap
Section titled “Run a tap”A tap is a folder on an https host that people add once and then install from by name.
-
Create the tap:
graft tap init ./my-tap --name acme --key ~/.config/graft/key.pem -
Pack a graft with the same key, and add it to the tap:
graft pack --key ~/.config/graft/key.pemgraft tap add ./my-tap notes-0.1.0.graft -
Upload
./my-tapto a static host such as GitHub Pages, R2, or S3. -
Give operators these commands:
sudo orchardctl graft tap add acme https://grafts.example.com/orchardsudo orchardctl graft add acme/notes --apply
graft tap add refuses a file that is not signed with the tap’s key. It also refuses different bytes for a published version. Bump the version instead.
List a community graft
Section titled “List a community graft”Community grafts appear in the Extension Marketplace, labeled with their publisher. The code stays in your own repository.
-
Run
graft keygen, and store the private key as a GitHub Actions secret. -
Add a workflow that packs, signs, and attaches
<id>-<version>.graftto each GitHub Release:on:release:types: [published]permissions:contents: writejobs:graft:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: hackclub/orchard/.github/actions/graft-release@mainwith:key: ${{ secrets.GRAFT_SIGNING_KEY }} -
Open a pull request that adds
registry/community/<id>.jsonto the Orchard repository. For the file format, refer toregistry/community/README.md.
A maintainer reviews the first listing. After that, the Extension Marketplace checks for new releases every hour. It checks the signature, the file hashes, and that migrations do not change Orchard’s tables. It then publishes the release with no further review. A release that fails a check is skipped, and the previous version stays available.
Publish an official graft
Section titled “Publish an official graft”Official grafts live in the grafts/ directory of the Orchard repository. CI runs graft doctor and packs each graft. On merge, CI signs new versions with Orchard’s key and publishes them.
Published versions do not change, so each update needs a new version. Each graft is a release-please component. feat: and fix: commits that touch it add it to the next release pull request, which bumps package.json and graft.json. Merging that pull request publishes the new version.
To add a graft, add it to release-please-config.json and .release-please-manifest.json, like grafts/greenhouse.
Version compatibility
Section titled “Version compatibility”Each version lists the Orchard versions it works with in engines.platform. orchardctl installs the newest version that matches the instance.
Related resources
Section titled “Related resources”- Install grafts - What operators run to install your graft, and how trust works.
- Upgrade and roll back grafts - How operators move between your versions.