CloudBolt Content Navigator

Browse and sync CloudBolt content by human-readable name instead of Global ID.

CloudBolt stores content in git using ID-based directory names like BP-50pq8bqg/. This extension reads the metadata files in your local repo and shows content by name in the VS Code sidebar, so you can find and sync items without cross-referencing the CloudBolt UI.

Requirements

• A local clone of a CloudBolt content repository
• A dedicated CloudBolt development instance — it is recommended that each developer has their own instance to avoid conflicts when pushing content changes
• A personal access token or username/password credentials for that instance

Setup

1. Open your CloudBolt content repository in VS Code.
2. Set your instance URL: open the Command Palette (Cmd+Shift+P) and run CloudBolt: Set API Token (or CloudBolt: Set Password for username/password auth).
3. Set cloudbolt.instanceUrl in VS Code settings to your CloudBolt instance URL.
4. Run CloudBolt: Select Source Code Repository to link the extension to the correct repo configured in CloudBolt.

The CloudBolt panel will appear in the Activity Bar once a content repo is detected.

Python Typings

CloudBolt ships a set of .pyi stub files that enable type checking and autocompletion for CloudBolt APIs in your scripts and plugins. The latest version is always available on your development instance at /var/opt/cloudbolt/proserv/typings.

Download the typings from your instance

1. SSH into your CloudBolt instance and create an archive, following the symlink to capture the actual files.

Mac / Linux:

tar -chzf /tmp/cloudbolt-typings.tar.gz -C /var/opt/cloudbolt/proserv typings/

Windows:

cd /var/opt/cloudbolt/proserv && zip -r /tmp/cloudbolt-typings.zip typings/

2. Download the archive to your local machine (run from your content repo root):

Mac / Linux:

scp root@<instance-ip>:/tmp/cloudbolt-typings.tar.gz ./cloudbolt-typings.tar.gz

Windows (PowerShell):

scp root@<instance-ip>:/tmp/cloudbolt-typings.zip ./cloudbolt-typings.zip

3. Extract into your content repository:

Mac / Linux:

tar -xzf cloudbolt-typings.tar.gz && rm cloudbolt-typings.tar.gz

Windows (PowerShell):

Expand-Archive cloudbolt-typings.zip . && Remove-Item cloudbolt-typings.zip

This creates a typings/ directory in your repo root. It is excluded from git via .gitignore.

Note: Repeat steps 1–3 when you upgrade your CloudBolt instance to pick up any new or updated stubs.

Configure VS Code

Pylance's default stub path is typings, so no configuration should be required. To verify, open VS Code settings and confirm that python.analysis.stubPath is either not set or set to typings. Once the typings/ directory exists in the repo root, VS Code will pick up the stubs automatically on the next reload — providing type checking and autocompletion for CloudBolt APIs across all scripts in the repository.

Since the stubs do not include the underlying .py or .pyc source files, Pylance will raise a missing module source warning without the following setting in .vscode/settings.json:

{
    "python.analysis.diagnosticSeverityOverrides": {
        "reportMissingModuleSource": "none"
    }
}

Change Indicators

The tree shows how far each item is from being in CloudBolt. CloudBolt syncs from the git remote, so an edit only counts once it is committed and pushed:

Indicator	Meaning	What to do
M, modified colour	Edited in your working tree, not committed	Commit and push, then sync
↑, blue	Committed since the last sync	Run Refresh in CloudBolt
!, red	The last sync of this item failed	Check the CloudBolt output channel

Colour without a badge means an item is affected rather than edited — a blueprint whose plugin changed, a content type group holding a changed item, or the specific blueprint section that holds the affected dependency. Where an item is in more than one state, the one that blocks a sync wins, so uncommitted edits show ahead of unsynced commits.

The indicators update as you save, commit, pull, and sync — no manual refresh needed. Sync to CloudBolt on one item clears only that item (and whatever its sync carried along); Refresh in CloudBolt clears everything. Pulling a colleague's commits does not raise an indicator against their work, but your own committed work keeps its ↑ until you actually sync it — matching the git remote is not the same as being in CloudBolt.

Indicators are tracked per branch. CloudBolt syncs a branch at a time, so "last synced" only means anything relative to one: switching branches does not carry the other branch's sync state over, and syncing on one branch leaves the other's alone. A branch you have never synced starts clean, the same way a fresh install does — run Refresh All Content after switching to load that branch into your development instance.

Note that indicators are computed from git on your own machine, so they cannot see a sync a teammate ran. Reload Content Tree re-reads the workspace; it does not re-check CloudBolt.

Workspace Settings (.vscode/settings.json)

The extension only activates in workspaces whose root holds one of the recognized content folders (opening the CloudBolt panel or running any CloudBolt: command activates it too). In a repository with no CloudBolt content folders the extension stays idle — it registers no file watchers, scans nothing, and writes no settings. It writes to .vscode/settings.json only in repositories that contain CloudBolt content — a workspace with no recognized content folders is left untouched. In a content repository it adds file and search exclusions:

{
    "files.exclude": {
        "**/*_metadata.json": true,
        "**/*.jpeg": true,
        "**/*.jpg": true,
        "**/*.png": true
    },
    "search.exclude": {
        "**/*_metadata.json": true,
        "**/*.jpeg": true,
        "**/*.jpg": true,
        "**/*.png": true
    }
}

These hide CloudBolt metadata files and embedded images from the Explorer and search results — the extension surfaces that information through the tree view instead. Exclusions you added yourself are preserved; VS Code's own defaults (**/.git, **/node_modules, …) are never written into your repo, and any that an earlier version of the extension copied there are removed.

Friendly Editor Tab Titles

Content files are named after their Global ID on disk, so a tab reading PLG-50pq8bqg_script.py says nothing about what the plugin does. The extension keeps custom editor labels in sync with the names in metadata, so the tab reads Create Azure VM.py instead. Names also show up in Quick Open — Ctrl+P and type Create Azure VM finds the script.

These patterns go in your own settings.json, not the repository's, keyed by absolute path:

{
    "workbench.editor.customLabels.patterns": {
        "/Users/you/git/content-repo/plugins/PLG-50pq8bqg/PLG-50pq8bqg_script.py": "Create Azure VM.${extname}",
        "/Users/you/git/content-repo/extensions/EXT-abc123/**/*.*": "Cost Panel — ${filename}.${extname}"
    }
}

The mapping is derived entirely from metadata that is already committed, so a copy in the shared .vscode/settings.json would add no information — only a generated block that conflicts every time two branches rename content. Keeping it in user settings leaves the repository untouched.

The list is regenerated from the workspace whenever the extension activates, on Reload Content Tree, after a sync, when a _metadata.json file changes, and when the branch changes — so renaming an item in CloudBolt and pulling updates its tab title. Entries for deleted items are dropped, entries for content repos you have deleted from this machine are cleaned up on the next activation, and label patterns you wrote yourself are never modified. Set cloudbolt.friendlyTabTitles to false to turn the feature off and remove its entries.

We recommend committing .vscode/settings.json to your content repository. This ensures every developer on the team gets the same file hiding behavior from the moment they open the repo, without needing to activate the extension first. It also prevents the file from showing up as an untracked change after first activation.

Content in a Subdirectory

By default the extension expects the content folders (blueprints, plugins, …) at the root of the workspace folder. If your repository keeps them somewhere else, point cloudbolt.contentRoot at that directory — relative to the workspace folder:

{
    "cloudbolt.contentRoot": "content"
}

This belongs in the repository's .vscode/settings.json so everyone on the team gets it. Git operations still run against the repository root; only scanning, file watching, and tab titles follow contentRoot.

One caveat: VS Code decides whether to activate an extension before any extension code runs, and it can only check the workspace root — so a nested layout will not activate the extension automatically. Open the CloudBolt panel once per window, or run any CloudBolt: command, and everything works from there.

Configuration

Setting	Description
cloudbolt.instanceUrl	URL of your CloudBolt instance (e.g. https://my-cloudbolt.example.com)
cloudbolt.authMode	token (recommended) or userpass
cloudbolt.username	Username — only used when authMode is userpass
cloudbolt.tlsVerify	Set to false for on-premise instances with self-signed certificates
cloudbolt.sourceCodeRepoId	Set automatically by CloudBolt: Select Source Code Repository
cloudbolt.contentRoot	Directory holding the content folders, relative to the workspace folder (default: the workspace root)
cloudbolt.friendlyTabTitles	Show human-readable content names on editor tabs instead of Global ID file names (default true)

Supported Content Types

• Blueprints
• Plugins
• Shared Modules
• Resource Actions
• Server Actions
• Orchestration Actions
• Flow Control Actions
• Recurring Jobs
• Webhooks
• Continuous Infrastructure Tests
• UI Extensions
• MCP Tool Actions

Source Code Repository

CloudBolt uses a Source Code Repository (SCR) to know where to pull content from when syncing. The SCR must be configured in your CloudBolt instance before using this extension, and it must point to the same remote git repository as your local clone.

To configure the SCR in CloudBolt:

1. In the CloudBolt admin UI, go to Admin → Source Code Repositories
2. Add a repository entry pointing to your content repo's remote URL (e.g. your GitHub/GitLab remote)
3. Ensure your CloudBolt development instance has network access to that remote

Once the SCR exists in CloudBolt, link the extension to it:

1. Open the Command Palette and run CloudBolt: Select Source Code Repository
2. Pick the repository from the list — the extension saves the selection and shows it in the status bar

When you sync, the extension tells CloudBolt to pull from the current branch of that remote repository. This means your changes must be committed and pushed to the remote before syncing — local-only changes will not be included. The extension will warn you if it detects unpushed commits before proceeding.

Dependency Tree

Content items are expandable in the tree to show their dependencies:

• Blueprints expand into labeled sections — Deployment Items, Management Actions, Teardown Items, Discovery Plugin, and Parameter Generated Options. Each section lists its named items, which expand further to show the individual plugins or actions they reference.
• Actions and other types expand to a flat list of their dependent plugins and modules, grouped by content type.
• Plugins and Shared Modules are leaves — they appear as dependencies of other items but do not expand further.

All dependencies are resolved from your local repo and shown by human-readable name. If a dependency exists in CloudBolt but not in the local repo, it is shown as [Unknown: <global-id>].

Refresh All Content

Refresh All Content pushes every item in your local repo to CloudBolt in a single job. It is most useful in two situations:

Setting up a new development instance When you first configure a development instance, it will not have any of the content from your repo. Running Refresh All populates the instance with everything on the current branch, giving you a consistent baseline to develop and test against.

Starting work on a new feature branch (optional) When you check out a new branch, your development instance may still reflect the previous branch. Running Refresh All at the start of your session ensures the instance is in sync with the branch you are working on before you begin making changes. This step is optional — it is only necessary if the branch contains content differences that would affect your testing.

In both cases, the current branch must exist on the remote before running Refresh All — push it first with git push -u origin <branch> if you have not already.

Pull Requests

A second pane below the Content tree lists the repository's open pull requests and shows what content each one changes by name. Reviewing a content pull request on github.com means reading paths like plugins/PLG-50pq8bqg/PLG-50pq8bqg_script.py; here the same change reads Create Azure VM.

The pane appears only when the repository's origin remote points at github.com, and it asks you to sign in with VS Code's built-in GitHub account the first time. No GitHub token is stored by this extension.

Category	What it shows
Local Pull Request Branches	Open pull requests whose head branch also exists in your local clone
Waiting For My Review	Open pull requests that requested your review
Created By Me	Open pull requests you opened
All Open	Every open pull request, most recently updated first

Expand a pull request to see the content it changes, grouped by content type exactly as the Content tree groups it. Items whose change touches a single file open their diff on click; items with several changed files expand into rows named for what each file is — Script, Metadata, Icon — rather than the Global ID file name. Changes outside the content folders are collected under Other Files.

Clicking any of those opens a read-only side-by-side diff in the editor, with both sides fetched from GitHub. You do not need to check the branch out, and the tab is titled with the content name rather than the Global ID.

The pull request tab

Click a pull request to open its own tab: title, state, branches, changed-file and line counts, the full description, and who has reviewed it or been asked to. The review controls live here too — Start Review before one is open, then Approve, Comment, and Request changes with a summary box once it is. Checkout and Open on GitHub are on the same tab.

On a pull request you opened yourself, only Comment is offered: GitHub does not allow approving or requesting changes on your own work.

Reviewing

Existing review comments appear as inline threads on the diff, in the same place they sit on github.com. You can reply to a thread, start a new one on any line, edit or delete your own comments, and resolve or unresolve threads.

The pull request tab also carries the Conversation: existing discussion and review summaries, with a box to comment on the pull request itself rather than on a line. Merge, close and reopen are there too, with the merge method (merge commit, squash, rebase) chosen before a confirmation step; a branch with conflicts says so instead of offering a button that would fail.

Each changed file has a viewed checkbox in the tree. It is stored on GitHub, not locally, so your progress through a large pull request follows you to the web UI and back.

Select lines in a diff and choose Suggest a Change to propose a concrete replacement. The comment opens pre-filled with a suggestion block that the author can apply in one click. Next Unresolved Review Thread and its counterpart move between outstanding feedback across every file in the pull request.

To review properly, start a review first — either from the pull request tab, or with the Start Review button on the comment box, which opens the review and attaches that first comment to it. The comment box follows the review state: Start Review and Add Comment before one is open, Add to Review once it is. Comments added while a review is open are held as pending: labelled as such and visible only to you. Finish with Submit Review…, available from the pull request tab, the comment thread toolbar, and the pull request's right-click menu. Approving asks for confirmation first, since it posts publicly under your name. With no review in progress, a comment posts immediately.

Comments written against a commit that has since been rewritten cannot be placed on any line of the current diff. Rather than guessing a line and attaching real feedback to unrelated code, those are listed in the tree under their file as outdated, with the original diff hunk in the tooltip.

Running a pull request's content

Use the Refresh in CloudBolt icon on a pull request's row, or the same entry in its right-click menu, to load the content it changes onto your development instance, so you can actually run a colleague's work before approving it. CloudBolt pulls from the git remote and the pull request's branch is already pushed, so nothing is checked out and your working tree is untouched.

The payload follows the same rule as the Content tree: a changed item that belongs to a parent is synced by submitting the parent, because pulling a parent brings its dependencies with it. Content the pull request adds, which is not in your clone yet, is submitted on its own.

Afterwards your instance holds that branch's content rather than yours. The status bar says so — CloudBolt · my-repo · PR [#7](https://github.com/CloudBoltSoftware/cloudbolt-vscode-plugin/issues/7) — because nothing else can: the change indicators are derived from git, which has no idea what was last pushed to an instance. Click it, or run CloudBolt: Restore My Branch to the Instance, to load your own branch back; the marker clears once that finishes.

Checking out a pull request

Right-click a pull request and choose Checkout Pull Request to fetch the contributor's branch and switch to it — useful when you want to run their content against your own CloudBolt development instance before approving. Run CloudBolt: Refresh All Content afterwards to load it.

Checkout refuses to run when you have uncommitted changes, rather than carrying them onto someone else's branch. The branch you were on is remembered: CloudBolt: Return to Previous Branch takes you back.

Performance

Nothing is fetched until you ask for it. The four categories render with no network call at all; expanding one costs a single request, and expanding a pull request costs one more. Results are cached for five minutes — use the refresh button in the pane's title bar to pick up newer pull requests sooner.

Limitations

• Reviews are matched to you individually, not to your teams. Waiting For My Review lists pull requests that requested you specifically; one that asked a team you belong to, without naming you, does not appear there, and a team asked to review is absent from the Reviewers list on the pull request tab. Such a pull request is still listed under All Open, so nothing is hidden — it is just not pre-filtered for you. This is deliberate: reading teams requires the read:org scope, and the extension asks only for repo, so signing in grants it no access to your organization's membership.
• github.com only. GitHub Enterprise Server uses a different API and sign-in, so the pane does not appear for those remotes.
• Names come from your clone. Content a pull request adds is not on your disk yet, so it is listed by Global ID with a warning icon until you check that branch out.
• Comments live on the diff. With a pull request checked out, its files in your working tree show no comment threads — review happens in the diff view.
• Single-line comments. A new comment anchors to one line; multi-line selections are not yet supported.
• No merging. The pane does not merge pull requests, and it does not sync a pull request's content to CloudBolt as a single action — check the branch out and use Refresh All Content.

Commands

Command	Description
CloudBolt: Set API Token	Store a personal access token in the system keychain
CloudBolt: Set Password	Store a username/password credential
CloudBolt: Clear Credentials	Remove stored credentials
CloudBolt: Select Source Code Repository	Pick the source code repo configured in CloudBolt
CloudBolt: Refresh All Content	Push all locally changed items to CloudBolt
Reload Content Tree	Re-read the local repo and refresh the tree view
CloudBolt: Sign in to GitHub	Authorize the pull request pane
Refresh Pull Requests	Re-fetch the pull request pane (title bar button)
CloudBolt: Return to Previous Branch	Switch back to the branch you were on before checking out a pull request
CloudBolt: Restore My Branch to the Instance	Load your own branch back onto the instance after refreshing a pull request
Next Unresolved Review Thread	Jump to the next unaddressed comment, across every file in the pull request
Previous Unresolved Review Thread	The same, backwards

Right-click any content item in the tree to Sync to CloudBolt, or use the sync button in the toolbar to push all pending changes at once.

A pull request's row carries icons for Refresh in CloudBolt, Checkout Pull Request, and Open on GitHub. Right-clicking adds Open Pull Request, Start Review, and Submit Review… alongside the same three.