Skip to content

Use code blocks

Install a code block into a service to start from a working, versioned snapshot of another service, keep it upgraded, and publish your own service as a block for other products.

A code block is a service's build folder (with infra/ split out) plus its protos, templated so that any product can install it. Install and upgrade run on the platform: the generated files are committed to a block/* branch in both the product's build repo and the build environment's definitions repo, and the CLI merges that branch into the main branch of both repos and pushes.

Prerequisites

  • A service to install into, with both repositories cloned.
  • The block id. Browse blocks in the console at /build/blocks (tabs Stable, Release Candidate, Beta, Alpha, Experimental) or list them with the CLI.

Browse

Shell
alis blocks list acme.sh.orders.v1
alis blocks versions <block-id>

list shows the service's installed blocks and the blocks available to it; versions lists a block's versions, newest first. A block's console page has About, Documentation, Versions, Instances and Help.

Install

alis blocks install <block-id> acme.sh.orders.v1
  • --version 1.2.0 installs a specific version (default: the latest stable).
  • --build-folder <folder> places the block's build files under a subfolder of the service (default ./).
  • --no-merge skips the local merge; run alis blocks merge <block-id> later.
  • --async returns the operation; resume with alis operations wait, then run alis blocks merge (a wait never merges).

Blocks with a dedicated service, such as resources, generate their files from a typed config: pass --config <file> (JSON or YAML, - for stdin). Missing config fails fast with CONFIG_REQUIRED. The block's skill documents the schema: alis skills load block-<block-id>.

When the result's next names the block's skill, load it before configuring or deploying. Then continue the normal loop: alis define (the block added protos), build and deploy.

Upgrade and uninstall

Shell
alis blocks upgrade <block-id> acme.sh.orders.v1
alis blocks uninstall <block-id> acme.sh.orders.v1

upgrade moves the instance to --version (default: the latest, GA preferred) through the same block branch and merge; --config replaces a dedicated-service block's stored config. uninstall deletes the instance's unmerged block branches; files already merged into the main branch stay. Use --instance blocks/<id>/instances/<n> when a block is installed more than once.

Send feedback

alis blocks feedback <block-id> "The install left the bucket name unset"

Feedback reaches the block's owners as a conversation; repeat feedback on the same block lands on your open thread.

Publish your service as a block

Shell
alis blocks accounts
alis blocks create <block-id> acme.sh.orders.v1 --display-name "Orders" --account accounts/<id> --tagline "Order capture and fulfilment"

create uploads the current files as the block's first version, registers the service as the block's source and scaffolds .skill/SKILL.md in the service folder; commit that file. The block id is immutable. Local environment files (.alis, .env*, key.json) are never uploaded.

Keep building the source service, push, then cut versions:

alis blocks publish <block-id> acme.sh.orders.v1 --release-level BETA --notes "Adds refunds"

--release-level is GA, RC, BETA, ALPHA or EXPERIMENTAL. The source service publishes from its trunk's latest commits; a service that installed the block must choose --from trunk, --from contribution or --branch <name>, or pin both commits with --define-commit and --build-commit. The .skill/ folder of the most stable version becomes the registry skill block-<block-id>. The TUI's ShiftB and ShiftP actions offer the same with a per-file review step.