Build Building Blocks

Build Building Blocks

Open Build building blocks from the Migration Plan journey when a source converts pipelines and builds building blocks, and those pipelines need building blocks. When they do not, the step is not on the journey.

The step tracks the releases to build in the building block home before the waves that call them. Its purpose names that org. Progress is how many building blocks are ready out of the total, and the step is due when the next unfinished release is due.

The Overview counts the same building blocks on the Building blocks ready tile. Each release's due date is listed with what is coming up, and how many building blocks that release holds.

What the Plan Builds

The building blocks are the ones the pipeline families need, for pipelines whose source converts and builds building blocks. A wave needs the building blocks of the repositories in that wave.

At SLSA Build level 3, the plan also counts a builder for each kind of artifact published by a pipeline that is not in a family. See One-Off Pipelines at Build Level 3. SLSA provenance and CargoWall add no building block of their own. See Pick Features.

Building Blocks Named After a Replaced Tool

A building block whose name contains a tool from Replacements on Pick Features is flagged. The row reads Replaced by the plan: the tool, then what replaces it, such as Artifactory → GitHub Packages. The plan does not change the building block to the replacement.

Plan again plans that building block's pipeline families again, so they use the replacement. It shows when you can start planning and the building block has families. If planning is already running, plan again once it finishes. If none of those families needs building blocks now, nothing starts.

A band counts how many are flagged. Show only those lists just those building blocks. Show every building block clears the filter. The building block's name has to contain the replaced tool's words, in order, as whole words. A tool named only inside another word is not flagged.

One-Off Pipelines at Build Level 3

A one-off is a pipeline the plan converts and builds building blocks for that is not in a family. When the plan's SLSA provenance is on at Build level 3, a one-off calls a type builder for each kind of artifact it publishes. A type builder is a reusable workflow in the building block home that builds and publishes that artifact, then attests it in a second job. A pipeline in a family does not call one: that family's primary building block is its builder.

The plan writes one type builder per kind when you plan building blocks, without spending AI, including when no family is left to plan. The kinds are a container image, an npm package, Maven artifacts, NuGet packages, a Python package, and release files, named Image builder, npm package builder, Maven package builder, NuGet package builder, Python package builder, and Release files builder. They follow the plan's SLSA setting, not a value set only for one wave. Below Build level 3, or with SLSA off, no one-off calls a builder, and one already written does not count.

On a wave's Building blocks ready stage, the wave names each type builder its one-offs call, how many call it, and whether it is ready. Only those pipelines wait on it. The wave does not. A wave that needs only these type builders still requires a connected building block home, and each destination org has to be able to use building blocks. The stage does not add an item for the builders. A kind with no builder yet is counted until the next time you plan building blocks.

A one-off the scan could not place is counted apart, and gets builders once you answer what it publishes (see What These One-Offs Publish): a Jenkins job, a classic build, or an Azure DevOps YAML pipeline the scan did not read in full, including one whose template it could not follow. The scan looks for publishing tasks and for docker push, npm publish, mvn deploy, dotnet nuget push, and twine upload run as a command, not in a comment, an echo, or later on another command's line.

While a type builder has not been approved, planning again writes its description from the plan's own lines. Approve it to keep an edit. A builder no one-off needs anymore is removed while it has not been approved and is not being built. One you approved stays until you remove it.

Build Commands

A type builder runs only that kind's standard tool. When a one-off's build is more than that, such as compiling, testing, or code generation before packaging, put those commands in a script committed to the caller's repository. The workflow passes the script to every builder it calls as build-script, a path from the repository's root, not from the working directory. The path is a fixed value, never a command or an expression. Leave build-script empty and the builder runs the standard build alone.

The script runs after checkout and before the pack or publish step. It runs in the build job, which has no id-token permission. The job that attests the build runs none of the caller's code.

The path has to name a file inside the repository. The builder refuses an absolute path, a path that contains .., or a path that leaves the checkout.

Each call is pinned to its builder's commit. The calling job has no steps of its own. A builder that covers more than one kind is called once. Editing the mapping away from a type builder drops the builder calls and the script.

A pipeline in a family does not use build-script. Its primary building block is its builder, and the shared build logic stays in the block.

Publishing a Python Package at Build Level 3

PyPI's trusted publishing binds only to the workflow in the caller's repository. It cannot bind to a reusable workflow, so at Build level 3 a Python package is not published by its builder.

The Python package builder builds the sdist and the wheel and attests them. It publishes nothing, and it takes no registry token and no index URL. The build job uploads the sdist and wheel as the workflow artifact python-dists. The workflow outputs that name as dists-artifact. The calling workflow's own job downloads that artifact and publishes it. That job is not a building block, and it is not a step of the builder.

When a pipeline family publishes a Python package, its primary building block follows the same rule. It builds and attests, and the publish stays a job of the calling workflow.

An image, an npm package, Maven artifacts, and NuGet packages publish from their own builder, and that builder takes a registry token.

When a One-Off Waits on Its Type Builders

The conversion leaves a one-off out until every builder it calls is planned, registered in the home, and callable from the orgs that one-off moves to. A builder counts once its workflow is registered in the home. The one-off keeps the mapping it already has. Other pipelines in the wave are not held for it. On the wave's Convert callers stage, choose Set up again once those builders are ready and callable.

The conversion then maps it to create its own workflow that calls the first of those builders in the home. The rest are additional building blocks on the same mapping. The order is fixed, so planning again does not change which builder the workflow calls: image, then npm, Maven, NuGet, and Python, then release files. An edit you make to the mapping is kept, as on any mapping onto building blocks.

A one-off the scan could not read stays out until what it publishes is known. A family that needs building blocks and was planned without saying whether it publishes stays out too, including a family planned before that was asked. Plan that family again on Review pipeline families. Below Build level 3, a family is not held for this.

Building Block Releases

Choose how the plan schedules releases on the Releases card. New plans start with All up front.

With As waves need them, each wave in order gets a release (Release 1, Release 2, and so on) holding the building blocks it needs that no earlier release holds. A wave that needs nothing new gets no release. The release is due two days before that wave's callers start.

With All up front, one release named All building blocks holds every building block the plan needs. It is due two days before the first callers that need any of them.

A release starts early enough to finish on its due date. As waves need them, the plan allows 10 days, or 1.6 days per building block rounded to the nearest day, whichever is longer. All up front, it allows 14 days, or 1.7 days per building block rounded to the nearest day, whichever is longer.

Callers are the pipelines that wave converts. When repositories move first, callers start at the beginning of the wave's convert window. When repositories and pipelines move together, callers start at the window's start, three days later if repositories move, or four days later if they are also rewired, and no later than the end of the window. A wave with no convert window yet does not date a release. The move window alone does not. All up front, the due date follows the first callers that already have a date.

A start or due date set on a release replaces that part of the estimate. The estimated due date is always before callers start. Only a date set on the release can make it late.

Open a Building Block's Blueprint

On this step, and on a wave's Building blocks ready stage, click a building block's name to open its blueprint. The name is a link when the building block has a blueprint and the building block home is connected. The page is in that home, under Building Blocks, and it has no tab of its own. A name with no blueprint yet, or a home that is not connected, is not a link.

The page shows the name, the kind, and where the blueprint stands: Blueprint drafted, Approved, Being built, Build failed, or Ready. It names the repository and path it is built in, or says there is no repository yet. Plan is what the build follows.

Once the blueprint is a building block, choose Open followed by that building block's name to go to it. Open Editor opens its workspace while one exists.

Choose Edit when you can update blueprints in that organization and the blueprint is not being built and is not already built. Read the plan here before you approve the blueprint.

Building Blocks has to be available on the home's plan. If it is not, contact that org's CodeCargo administrator. A blueprint another organization holds is not found here.

When the Step Is Done

Done when:

• Every release finishes before its wave's callers start. A release is late when its due date is after those callers start.
• No release is behind schedule. The plan expects building blocks to become ready in a straight line from all of them on the start date to none on the due date. The release is behind when more than one building block is still to build above that line. One building block of slack means a day without a merge does not mark it behind.
• Every building block is ready, shown as how many of the total. A building block is ready when it is registered in the building block home.
• Every likely duplicate building block is merged or kept separate. This item appears only after a pair has been flagged, and it stays open until you merge the two or keep them apart.

The step is Done when every item is met. It needs you when a release is late, a release is behind schedule, or a likely duplicate is still undecided. Building blocks that are not ready yet, on their own, leave the step in progress.

The building block home is first needed on the day the earliest release starts, unless a wave moves repositories into that org by then. See When the Building Block Home Is Needed.