Start Building for Free

VS Code extension overview

3 weeks ago4 min read
On This Page

The CircleCI Visual Studio Code extension enables you to manage your CircleCI pipelines directly from VS Code.


The VS Code extension includes:

  • The Pipeline Manager, which lets you view and manage pipelines within the IDE (integrated development environment). The pipeline manager allows you to identify issues and take immediate action on your pipelines without switching between VS Code and your browser.

  • The Config Helper, which provides in-file help with navigating, writing, and editing configuration files.

Install the VS Code extension

For installation and setup instructions, visit the VS Code Marketplace page, or search for the official CircleCI extension on the Extensions tab in the VS Code.

Pipelines panel

The pipelines panel provides a visual interface for managing your pipelines. The panel lists your most recent pipelines, workflows, and jobs in a project, and lets you monitor their status as well as interact with them.

Screenshot of side panel with pipeline information

For each object, you can trigger certain events on hover.


Pipelines are the top-level tree item in the panel, and they contain your workflows. Hovering over a pipeline lets you:

  • Open in browser, to view pipeline details in the CircleCI app in your default web browser


Workflows are nested under each pipeline, and contain jobs. Hovering over a workflow lets you:

  • Open in browser, to view workflow details in the CircleCI app, in your default web browser

  • Rerun the workflow from start, to re-trigger the entire workflow

  • Rerun the workflow from failed, to rerun only the workflow’s failed jobs


Jobs are nested under each workflow, and can contain tests and artifacts. Hovering over a job lets you:

  • Approve the job (only if the job is on hold)

  • Cancel the job (only if the job is running)

  • Re-run the job with SSH (refer to the Re-run with SSH section below for more information)

  • View job details

    Screenshot of side panel with job details

Expanding a job also lets you:

  • Load tests, if you have configured test metadata to be available. Tests that CircleCI has detected as flaky will be prefaced by the indication [FLAKY].

  • Load artifacts, if any are created by the job. Once the artifacts are loaded, you can download them by clicking on them.

Re-run with SSH

There are two ways to re-run jobs with SSH directly from VS Code:

  • Open the job detail page, then click the SSH button on the top right.

    Screenshot of side Panel with job details
  • Or, hover over the job in the pipelines panel, and click the SSH action button next to the job name.

    Screenshot of side Panel with rerun otpions

In both cases, you will be presented with two options:

  • Open an SSH session in the terminal.

  • Open an SSH session in a remote VS Code window.

    Using a remote development window requires the official VS Code Remote - SSH extension. You can find more information on remote development in VS Code using SSH in the VS Code docs.

To re-run your job with SSH, you will first have to set the path to your GitHub or Bitbucket SSH key. The first time you attempt to re-run with SSH, the extension will guide you to select the path of the relevant SSH key. If you had skipped this step, or want to modify the path at a later time, you can do so from the SSH section of the CircleCI VS Code extension settings.

If the job you want to re-run uses parallelism, you will be able to select which parallel run you want to SSH into.


You can set up notifications to warn you when a workflow in your pipelines panel has changed status.

Screenshot of a notification pop-up for a failed workflow

If you are not following a workflow in the pipelines panel, you cannot be notified about a status change event. For instance, if you have set the extension to follow only the current branch, you cannot be notified of status changes for other branches.

Status Bar

The status bar provides information at-a-glance about the status of the CircleCI extension, your project, and your most recent workflow.

Screenshot of the status bar

The status bar can display the following statuses:

  • Not logged in: Upon clicking on the status bar, a CircleCI login page will open.

  • No project: Upon clicking on the status bar, the settings page will open so you can select a project.

  • Success / On hold / Failed, and other workflow statuses: this refers to the status of the top (that is, the most recent) pipeline in your panel. Upon clicking on the status bar, the associated workflow will come into focus on the pipelines panel.

Config helper

The VS Code extension also provides in-file contextual help for your CircleCI configs, including:

  • Rich code navigation through “go-to-definition” and “go-to-reference” commands. Hover over a job name or executor parameter to verify its definition or view where they are referenced elsewhere in the file. You can also explore the definition of orb-defined commands or parameters.

    Screenshot showing the definition available on hover
  • Contextual documentation and usage hints when hovering on specific keys. This helps you avoid having to frequently switch to your browser to check the documentation when editing your configuration. Links to the official CircleCI docs are also provided on hover, for easier navigation.

    Screenshot showing the contextual information on hover
  • Syntax validation. This helps you identify typos, incorrect use of parameters, incomplete definitions, wrong types, invalid or deprecated machine versions, etc.

    Screenshot showing the synthax highlightning when an error is identified
  • Usage warnings. This helps you identify deprecated parameters, unused jobs or executors, or missing properties that prevent you from taking advantage of CircleCI’s full capabilities.

    Screenshot showing code highlightning to warn on an unused job
  • Auto completion. This is available with both built-in keys and parameters as well as user-defined variables.

    Screenshot showing two suggestions to autocomplete the line of code

Config validation commands

The config helper also provides two commands that help you statically validate your YAML config files without having to run a pipeline.

  • Validate current configuration file

    Corresponds to the CLI command circleci config validate, and verifies statically that the config file is well formed. Please note that this command only validates this file for structure and syntax errors, but not for semantic error (e.g. "This job does not exist").

  • Validate current configuration file against org policy

    Corresponds to the CLI command circleci policy decide, and verifies that the configuration file complies with your organisation policies (if any are set).

Both of these commands can be run by:

  • Opening the VS Code Command Palette.

  • Right-clicking anywhere within an opened .circleci/config.yml file.

  • Clicking on the CircleCI button on the top right of the editor when you have a `.circleci/config.yml`open. Note that the button will not be visible if you are editing any other file.

Open source language server

The config helper is based on a dedicated language server specific for CircleCI YAML files, which is open source. You can view its source code, contribute and add issues directly on the project repository: circleci-yaml-language-server.

You can also integrate the language server into any editor which supports the Language Server Protocol, and build your own plugin to benefit from config helper capabilities in your favourite editor.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.