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:

• GitHub Actions Reusable Workflows

In the future, Building Blocks will also support:

• GitHub Actions
• Infrastructure-as-Code
• 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 is a table showing key metadata:

Columns:

• Name – A user-friendly alias for the Building Block
• Location – The full GitHub repo path to the workflow file
• Linked Self-Service Workflows – The number of Self-Service Workflow referencing this Building Block

Importing a Workflow as a Building Block

Click "Add Workflow" to open a side-panel input form.

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

The visualizer automatically expands matrix jobs to show individual job variants:

• Static matrices are expanded based on the matrix configuration in your workflow YAML
• Dynamic matrices (using expressions like ${{ fromJSON(inputs.targets) }}) display as strategy nodes with expansion indicators
• Each expanded job shows its specific matrix values in the job name
• Dependencies are automatically rewritten to connect to all expanded variants

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.

Strategy Nodes

For workflows with matrix strategies that cannot be statically analyzed, the visualizer shows strategy nodes that indicate job expansion will occur at runtime. These nodes display:

• The original job name
• An indicator showing the job will expand into multiple variants
• Connections to dependent jobs

Expert Workflow Agent

On the right side of the screen is a context-aware AI agent. This AI agent is fine-tuned 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 fine-tuned 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, 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) to provide your users to 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 Manage Shares dialog, type the alias of the consumer organization and click Add.
4. The organization now appears in the shares list. Repeat for additional organizations.

To revoke access, open Manage Shares for the source and remove the organization from the list. Revoking a share stops the consumer org from seeing new blocks from that source, but the share entry remains visible to you until you delete it.

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.

Shared blocks are only visible if your organization also has the cross-org sharing entitlement enabled.