Building Blocks

Building Blocks is a library of your approved templates, connected to your CodeCargo organization. These templates serve as golden paths - that is, they are approved by your organization as the "right way" to get things done. Building Blocks originate from GitHub repositories and are editable by anyone with the proper GitHub permissions.

Currently Building Blocks supports the following block types:

• Workflows – GitHub Actions Reusable Workflows
• Actions – individual GitHub Actions
• Repository building blocks – an entire repository exposed as a single block, useful for Infrastructure-as-Code (for example, Terraform modules) and other templates. The repository's root README.md is rendered as the block's documentation.

In the future, Building Blocks will also support:

• GenAI Prompts

What are Building Blocks?

Building Blocks help you:

• Organize your approved templates in a single location
• Visualize, edit, and extend them using an AI-powered editor
• Link them to Projects to provide standardized automations and application stacks to your users

Building Blocks View

The main Building Blocks interface has a tab for each block type (Workflows, Actions, Repositories) plus Sources. Each tab shows its blocks as cards you can search and filter by repository. Each card shows:

• Name – The workflow, action, or repository name
• Description – A human-readable summary of what the block does
• Repository – The source repository the block comes from
• Version – The branch or tag the block is pinned to, or Latest Release
• Shared from – For blocks shared by another organization, that organization's alias

Sources

Building Blocks come from sources — GitHub repositories connected via the GitHub App that CodeCargo discovers blocks from. A single source can provide:

• Workflows – GitHub Actions Reusable Workflows discovered from the repository
• Actions – GitHub Actions discovered from configured action paths. Each path maps to exactly one action; subdirectories are not searched, so list each action's directory explicitly.
• A Repository building block – the source repository itself exposed as one block, with its root README.md rendered as documentation

Sources are managed from the Sources tab, where you can add a source, edit its configuration (including its action paths), and remove it. Each source card shows the version it tracks and how many of its discovered blocks are enabled. See Building Block Sources Permissions for who can see and manage sources.

A repository building block renders the repository's root README.md as its documentation:

Adding a Source

Add a source from the Sources tab (or Add Source when you have none yet):

Curating Discovered Blocks

When you add a Building Block source, CodeCargo discovers the reusable workflows and actions in that repository. Discovered blocks start disabled, so adding a source by itself leaves the catalog unchanged.

Enable individual workflows and actions on the source, or enable all of them at once. A block appears in the catalog only when both the block and its type on the source (workflows or actions) are enabled. You can also ask Dispatch to add a source and enable its blocks in a single plan.

To change which blocks are enabled later, choose Manage Building Blocks from the source's menu on the Sources tab.

Editing a Building Block

GitHub Actions Workflows that you import as Building Blocks are directly managed by GitHub. This means you can edit them in 3 places:

1. CodeCargo's GenAI Workflow Editor
2. GitHub
3. Your IDE of choice

To edit a workflow in our platform using our GenAI Editor, click on any workflow on the page.

Workflow Editor

The Workflow Editor has a few key features:

• Visualizer --> visual representation of a GitHub Actions Workflow including triggers, jobs, steps, and configuration
• Code Editor --> syntax-highlighted editor with schema awareness
• Preview --> view / accept changes
• Files --> change which file is present in the Code editor

Visualizer

• Toggleable via a tab switcher at the top
• Presents the workflow as a block-style job and step layout
• Click into any job or step to view inputs, conditions, or outputs

The visual layout helps non-YAML-native developers and reviewers understand workflow logic and structure.

Matrix Job Visualization

A job with a strategy.matrix is drawn with a Strategy node attached to it:

• Static matrices (values written out in the YAML) show how many combinations the matrix produces, for example 2 combinations
• Dynamic matrices (expressions like ${{ fromJSON(inputs.targets) }}) can't be counted until the workflow runs, so the node reads Dynamic matrix

When the visualizer has real run data, as in the CargoWall run visualizer, a matrix job lists each variant that actually ran, with its matrix values in the name.

Reusable Workflow Visualization

The visualizer automatically detects and displays reusable workflows:

• Job-level reusable workflows appear as special job nodes with a box icon and the workflow reference
• Workflow inputs and secrets are displayed in expandable sections when present
• Dependencies show which jobs the reusable workflow depends on
• Node heights automatically adjust to accommodate the additional workflow information

Reusable workflow jobs display their uses reference prominently, making it easy to identify which external workflows are being called.

Expert Workflow Agent

On the right side of the screen is a context-aware AI agent. This AI agent is purpose-built to be an expert GitHub Actions Workflow agent and is generally capable of the following:

• Understands the structure and intent of the workflow
• Can generate or refactor YAML
• Applies updates to both the code and visualizer in sync
• Accepts plain language prompts like:
  • “Add a step to cache dependencies”
  • “Change the Node version to 20.x”
  • “Make this reusable for multiple services”
• The Building Block and the GitHub repository it is stored in is loaded into context

Advanced AI Assistant Use-Cases

Since the AI assistant is purpose-built to be an expert GitHub Actions Workflow agent, it provides powerful tooling that can do the following:

1. Enhance the security of a workflow
2. Improve the runtime, efficiency, or cost of running a workflow
3. Change the core function of a workflow
4. Convert an Azure DevOps, Jenkins, or other pipeline into a GitHub Actions Workflow
5. Identify potential errors, security vulnerabilities, or issues that may impact a GitHub Actions Workflow
6. Apply any of the above changes across multiple workflows defined in a single Git repository

Linking Building Blocks to Projects

Once added to the catalog, Building Blocks can be referenced within Projects. As an example, from within a Project, you can create a Self-Service Workflow (using one of your Building Blocks) that lets your users trigger workflows on-demand. This encourages:

• Reuse of CI/CD best practices
• Standardization across teams
• Easier updates and governance

Building Block Sources Permissions

Access to Building Block sources requires specific permissions:

Sources Tab Visibility

The Sources tab appears only when you have:

• Permission to list Building Block sources (canListBuildingBlockSources)
• AND permission to update either workflows (canUpdateBuildingBlockWorkflow) or actions (canUpdateBuildingBlockAction)

Without update permissions for workflows or actions, the Sources tab is hidden since managing Building Blocks requires the ability to modify them.

Source Management Actions

Each source in the sources list has dropdown actions with specific permission requirements:

If you don't have any of these permissions, the dropdown menu is hidden entirely.

Cross-Org Building Block Sharing

You can share a building block source with other organizations in your GitHub enterprise, giving those organizations read-only access to the blocks it contains. This lets a central platform team maintain a single source of approved templates that multiple product organizations can consume without duplicating the source repository.

Sharing a Source (Provider Org)

To share a source with another organization:

1. Navigate to Building Blocks → Sources in your organization.
2. Open the actions menu for the source you want to share and click Manage Shares.
3. In the Share Building Blocks dialog, select or type the alias of the consumer organization and click Share.
4. The organization now appears in the shares list. Repeat for additional organizations.

To revoke access, open Manage Shares for the source and click Remove next to the organization. Removing the share stops that organization from seeing blocks from the source.

Using Shared Blocks (Consumer Org)

When another organization shares a source with yours, its building blocks appear automatically in your Building Blocks catalog alongside your own. Shared blocks display the provider organization's alias so you can identify their origin.

Consumption is read-only:

• You can browse, view details, and use shared blocks in Self-Service Workflows.
• You cannot edit, delete, or modify the source repository or its blocks.
• The available git ref for a shared block is pinned to the ref configured by the provider; you cannot select an arbitrary branch or tag from the provider's repository.
• Schema and ref lookups are similarly pinned to the provider's configured ref.

Pairs Well With