Core Concepts
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 Worflows
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.
| Field | Description |
|---|---|
| Repository | Choose from any repo connected via GitHub App |
| Version | Select a branch, commit SHA, or tag |
| Path | Filepath to the .yaml workflow definition |
| Description | Human-readable summary of what the workflow does |
| Icon | Choose an emoji or icon to represent the workflow visually |
Reusable Workflow
Workflows must follow the GitHub Actions Reusable Workflow specification and the repository that the workflow is defined in must have appropriate permissions. If you do not have appropriate repository permissions set, you will still be able to import the workflow as a Buildling Block and create Self-Service Workflows; however, they will not execute properly.
Editing a Building Block
GitHub Actions Workflows that you ipmort as Building Blocks are directly managed by GitHub. This means you can edit them in 3 places:
- CodeCargo's GenAI Workflow Editor
- GitHub
- Your IDE of choice
To edit a workflow in our platform using our GenAI editor, click on any workflow on the page.
<< EDIT this section after editor changes deployed >>
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.
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:
- Enhance the security of a workflow
- Improve the runtime, efficiency, or cost of running a workflow
- Change the core function of a workflow
- Convert an Azure DevOps, Jenkins, or other pipeline into a GitHub Actions Workflow
- Identify potential errors, security vulnerabilities, or issues that may impact a GitHub Actions Workflow
- Perform the following for 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