Skip to content

How code blocks work

A code block is a working service, captured so that any product can start from it. This page explains what a block is made of, why installing one arrives as a git branch, how a block's versions and release levels work, how changes flow back to the block, how a block carries its own skill, and where feedback goes. For the commands, see Use code blocks.

A versioned snapshot of a working service

A block is a service's build files, with infra/ split out, plus its protos, templated so that the names fit whichever product installs it. Installing a block into a service gives that service the block's contract, code and Terraform at one version, with the product's own identifiers filled in. You start from something that already defines, builds and deploys, not from an empty folder.

Some blocks generate their files from a typed configuration instead of a plain template: you pass the configuration when you install, and the block's skill documents its shape.

A block can be installed into many services, and more than once into the same service. Each installation is an instance of the block, which records the version it is on.

Install and upgrade arrive as a branch

Generating a block's files needs the block's templates, its configuration and the product's identifiers, so installs and upgrades run on the platform rather than on your laptop. The result is committed to a block/* branch in both of the repositories a service lives in: the product's build repository and the build environment's definitions repository. The CLI then merges that branch into the main branch of both and pushes.

Arriving as a branch is deliberate. Your code and the block's meet in an ordinary git merge, so a conflict is something you resolve with the tools you already use, and history shows exactly what the block changed. You can also stop before the merge and do it later. An upgrade travels the same way, from the instance's version to a newer one. Uninstalling deletes the instance's unmerged block branches; files already merged into your main branch stay, because by then they are your code.

After an install, the block's protos are part of your service, so the usual loop follows: define, build, deploy.

Versions and release levels

Each published version of a block is an immutable snapshot taken from pushed commits in both repositories, never from your working tree, so local edits and local environment files (.alis, .env*, key.json) are never part of a block.

Each version also carries a release level, which says how much to trust it: Stable, Release Candidate, Beta, Alpha or Experimental in the console (GA, RC, BETA, ALPHA, EXPERIMENTAL in the CLI). Installs default to the latest stable version, and the console lists blocks by level.

Version numbers follow the levels. A block's first version is 1.0.0. Publishing a stable version either promotes the pre-release in flight or moves the minor version on; a pre-release continues its own track (2.0.0-rc1, then 2.0.0-rc2). Asking for a major, minor or patch bump counts from the latest stable version, so the pre-releases leading up to a release share its number.

Changes flow back to the block

The service a block was first published from is its source, and it publishes new versions from the latest commits on its trunk. A service that installed the block can publish too: it says which commits to take, from its trunk, from its contribution, from a branch, or from two pinned commits. That is how an improvement made where the block is used finds its way back to everyone who installs it. A dry run shows the exact commits and changes before anything is published, and publishing an installation that has not changed is refused unless you mean it.

A block carries its own skill

Instructions for using a block belong with the block, so a block's .skill/ folder is its skill. When a version is published, the .skill/ folder of the most stable version becomes the skill block-<block-id> in the Skill Store, kept in step with every release. An agent about to configure or deploy an installed block loads that skill, and the instructions it follows are the ones written for the code it has. This is also why buildable code belongs in a block rather than in a skill: a skill is a document, and a block keeps the document and the code from drifting apart. How skills work explains how a block skill's access follows the block's.

Feedback reaches the people who can act on it

There are two kinds of feedback, and they go to different people.

  • About one block. Feedback on a specific block, from its Help page or alis blocks feedback, reaches that block's owners as a conversation in Support, and their replies arrive there. More feedback on the same block lands on your open conversation.
  • About code blocks themselves. A bug in how code blocks work, rather than in one block, goes to the Alis Build team through Log a ticket.

The block's owners are the ones who can change the block; the Alis Build team is who can change the system around it.