The official CircleCI VS Code extension is a new way to interact with CircleCI.
This extension provides an interface to visualize and manage CircleCI pipelines directly from your
IDE, as well as providing contextual help when creating, modifying and editing CircleCI YAML config
files. This way, it avoids expensive context-switching between VS Code and your browser.
More practically, this extension allows you to:
- Authenticate and connect VS Code to CircleCI
- Browse and interact with your pipelines. Available actions include
- Viewing pipelines, workflows, and jobs statuses
- Viewing test outputs
- Browsing job logs
- Downloading artifacts
- Approving jobs
- Re-running builds
- Debugging jobs with SSH
- Be alerted through notifications when your workflows change status or need your attention
- Access in-file support when editing CircleCI YAML configuration files, including:
- Syntax validation
- Syntax highlighting
- Go-to-definition and go-to-reference
- On-hover documentation and usage hints
- Launch commands to validate config files statically, or against your org policy
It’s easy to get started with CircleCI for VS Code.
Install the extension
You can install the CircleCI extension from within VS Code, or download it from the marketplace.
⚠️ This extension is compatible with VS Code versions
1.85 or above.
Authenticate into CircleCI
Open the CircleCI Panel by clicking on the CircleCI icon on the activity bar on the left of your
screen, then click on “Log in”.
You will be prompted to enter a
Personal API Token. If you don't have one, you
can generate a new one for this purpose.
If you are an Enterprise customer, make sure to check the box and enter your self-hosted server
Setup your project
If your VS Code workspace contains one or more CircleCI projects, the extension will detect them
automatically, and the Pipelines Panel will be populated with your most recent pipelines.
If no project is detected, open the settings page (through the VS Code command
CircleCI: Open Settings, or by clicking on the settings icon (⚙️) at the top of the Pipelines
Panel), and select your projects manually.
Please note that your manual selection will only be persisted if no projects are detected
⚠️ Automatic project detection does not work for GitLab projects. Please select your project manually from the Settings page.
Configure your Pipelines Panel
By default, your Pipelines Panel will display all the latest pipelines run on your project.
However, you can configure it to show you only the pipelines you are interested in.
All configurations are available in the Settings page, which you can open with the command
CircleCI: Open Settings or by clicking on the settings icon (⚙️) at the top of the Pipelines
Specifically, you can choose to follow:
- Only your pipelines, or those authored by anyone
- All branches, only your current branch, or a specific branch. You can also select the checkbox
“Always display default branch”
- Only pipelines that include workflows and jobs with specific statuses.
You can set up pop-up notifications to warn you when a workflow in your Pipelines Panel has
By default, you will receive a pop-up notification every time one of the workflows in your
Pipelines Panel enters a failing status, or needs your approval.
If you wish to alter these defaults, you can:
- Mute notifications (a toggle button to change this setting is also available at the top of the
- Configure which workflow status changes you want to be notified about
Please note that you can only be notified about workflows that appear in your Pipelines Panel.
The Pipelines Panel
The Pipelines Panel lists all CircleCI projects detected in your workspace. For each project, it
shows the most recent pipelines, jobs and workflows, and lets you monitor their status and interact
For some tree objects, you can perform actions by clicking on the icons which appear when you hover
over the item.
Projects are the top level tree items, and they contain your pipelines.
If you don't follow a project, you can also use the panel to follow it.
are nested under projects. They are the CircleCI unit of change, and they contain your 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, on your default web browser
- Rerun workflow from start, to re-triggered the entire workflow
- Rerun workflow from failed, to re-triggered the workflow starting from the first failed job
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)
- Rerun the job with SSH (you can read more about this functionality in a later section)
- View job details
By expanding a Job, you can also:
- Load tests, if you have configured your tests to upload test results to CircleCI. Tests that
CircleCI has detected as flaky will be prefaced by the indication [FLAKY].
- Load artifacts, to load any artifacts created by the Job. Once the artifacts are loaded, you
can download them by clicking on them.
Re-run with SSH
You can re-run jobs with SSH directly from VS Code, either:
- through the Job Details page, by clicking on the green button on the top right:
- or by clicking on the action icon next to the job name in the Pipelines Panel.
In both cases, you will be presented with two options:
- Open SSH session in terminal
Open SSH session in remote VS Code window
This feature requires the official VS Code extension
Remote - SSH.
You can find more information on Remote Development using SSH in VS Code directly in the
VS Code docs.
To rerun 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. However, if you miss this step or want to modify it at a later time, you can
do so from the dedicated section of the settings page:
If the job you want to rerun uses parallelism, you will be able to select which job you want to SSH
You can read more about debugging with SSH on CircleCI
in the Docs.
The Status Bar provides summary information about the state of the CircleCI extension, your project
and your most recent workflow.
Specifically, you might see the following statuses:
- Not logged in - when clicking on the status bar, the login page will open
- No project - when clicking on the status bar, the settings page will open so you can select a
- Success / On hold / Failed, and similar workflow statuses - THIS refers to the status of the
top pipeline in your panel. When clicking on the status bar, the relative workflow will come into
focus on the CircleCI Pipelines Panel.
- No internet - when your internet connection is lost
This extension provides in-file assistance with writing, editing and navigating CircleCI
It is based on a CircleCI-specific Language Server, and offers:
- Rich code navigation through “go-to-definition” and “go-to-reference” commands. This is
especially convenient when working on large configuration files, to verify the definition of
custom jobs, executors parameters, or in turn view where any of them are referenced in the file.
Assisted code navigation also works for Orbs, allowing to explore their definition directly in the
IDE when using the go-to-definition feature on an orb-defined command or parameter.
- Contextual documentation and usage hints when hovering on specific keys, so as to avoid having
to continuously switch to the browser to check the docs whenever you are editing your YAML config.
Links to the official CircleCI documentation are also provided on hover - for easier navigation.
- Syntax validation - which makes it much easier to identify typos, incorrect use of parameters,
incomplete definitions, wrong types, invalid or deprecated machine versions, etc.
- Usage warnings - which can help identify deprecated parameters, unused jobs or executors, or
missing keys that prevent you from taking advantage of CircleCI’s full capabilities
- Auto completion, available both on built-in keys and parameters and on user-defined variables
You can access a full overview of all errors, warnings and hints proposed by the Config Helper in
the Problems tab of VS Code.
The Config Helper is based on a dedicated Language Server for CircleCI YAML files, which is Open
Source. You can view its source code, contribute and add issues directly on the project
Config validation commands
The extension 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 organization policies - if any are
Please note that this command is only available to Scale customers
View compiled version of current configuration file
This command resolves all orb references in your config file, and shows you the full-length
version of your config.
All these commands can also be invoked:
- by right-clicking on a CircleCI YAML file:
- by clicking on the CircleCI button on the top right corner of the page, when focusing on a
CircleCI YAML file. Please note that the button will not be visible if you are editing a
🆕 Test run your config (Open Preview)
NOTE: The ability to trigger a pipeline from VS Code with a unversioned config is currently in
Open Preview, and only available for projects integrated through the GitHub OAuth app, or
Bitbucket. To find out which GitHub account type you have, see the
documentation about GitHub OAuth app integration.
Trigger pipelines from VS Code to iterate on your CircleCI config without committing your trial and
error changes to your version control system. Run and validate your full pipeline, or select jobs
and workflows to validate individually. View the results of your test runs in the Pipelines Panel or
in the CircleCI web app, just the same as any other pipeline.
v2.0 or higher of the CircleCI VS Code extension
- A CircleCI account integrated through the GitHub OAuth app, or Bitbucket. To find out which GitHub
account type you have, check this docs page.
- Your org must have opted-in to this feature through Organization Settings. You may need to ask
your org admin to do so for you. See the section Feature controls below for more details.
- Your project must not make use of
dynamic configuration. This feature is disabled for
projects that use dynamic configuration.
NOTE: Unversioned config in CircleCI indicates that the
.circleci/config.yml on the branch
where the pipeline is running is ignored, and instead, the configuration file is overridden by a
custom configuration file passed as a parameter. The term “unversioned” refers to the fact the
config file is not versioned in the VCS. It is, however, stored in CircleCI along with the pipeline,
and it is available at any time in the CircleCI web app.
Please use caution when running pipelines with unversioned configuration, and take care to ensure no jobs with unintended effects are included in the run. For more details, see the section Security Implications below.
Access to this feature is controlled by an opt-in setting which only organization admins can control. Once your organization has opted-in, you can opt-out for each individual project. For more details, see the section Feature-controls below.
The following steps show how to test run a pipeline from the VS Code extension:
- Open VS Code and select the CircleCI logo in the sidebar. The Pipelines and Run panels
will be visible
- Expand the Run panel to view your projects.
- For each project, there is a button to trigger the config test run, and check boxes for each
workflow and job for you to choose which parts of your config you want to run. Select your
options, and click icon:play. Any local change you make to your
will be included in the test run.
- The pipeline is now visible in your dashboard in the CircleCI web app, at
app.circleci.com/pipelines/, and the Pipelines Panel in
the VS Code extension.
The ability to trigger pipelines from VS Code can be controlled at the org level and at the
Opt-in organization level setting. This can be changed only by organization admins, and
overrides project settings.
Organization Settings > Advanced > Allow triggering pipelines with unversioned config in the
Opt-out project level setting.
Project Settings > VS Code integration > Allow triggering pipelines with unversioned config in
the Web App.
Running pipelines with unversioned config can cause security vulnerabilities. Before enabling this
feature, please acknowledge the risks outlined in the
Here are some frequently encountered issues, and some clarifications on each of them.
“Your project could not be detected because no workspace is currently open”
You can fix this issue by opening a folder or workspace. Alternatively, you can select to follow a
CircleCI project manually from the Settings page.
The following errors concern the ability of the extension to link your workspace to a Git
“Your project could not be detected because we couldn’t find a Git repository associated with this workspace”
“Your project could not be detected because we were unable to get the list of git remotes”
“Your project could not be detected because we could not find default remote of your Git repository”
“Your project could not be detected because we were unable to get the URL of the Git remote XYZ”
When any of these errors occur, you might want to check that your workspace has a valid Git remote
URL. You can also fix this issue by selecting to follow a CircleCI project manually from the
“Your project could not be detected because CircleCI does not know this project”
This error indicates that the repository associated with your workspace doesn’t appear to be a
CircleCI project. If this is unexpected, verify the Git remote URL associated with your
repository, and ensure that you see this project on the CircleCI web app. You can also address
this issue by selecting to follow a CircleCI project manually from the Settings page.
“Your project could not be detected because you don't follow this project on CircleCI”
When you see this error, you might want to visit the
Projects page on the CircleCI app
and ensure that you “follow” the project associated with this workspace.
“connection to server is erroring. Shutting down server”
This message indicates that the CircleCI Language Server has crashed. This might be caused by an
unexpected parsing error. For this reason, it is likely that this issue will always occur on the
same file. If you identify a file that causes this error, it would be helpful if you could inform
us at XXXXXX (in the future on the LS open source repo)
When interacting with pipelines, workflows and jobs, you might see the following errors.
“Cannot refresh pipelines: [runtime error message]”
“Download failed [runtime error message”’
“Cannot rerun workflow because: [runtime error message]”
“Job approval failed: [runtime error message]”
Please keep in mind that one of the causes for any of the above error messages could be network
issues. If you see any of these messages repeatedly, we recommend you check your internet
The following errors should never occur. Should you see any of them and be able to reproduce them
appearing, it would be helpful if you could report this to us.
“Target entity can not be cancelled because it is not a workflow / job”
“Your project is not set up”
“Can not cancel your job because it has no job number”
If you find any bugs with this extension or want to provide feedback, you can contact us at
You can find more information about CircleCI on our
How to contribute
The Language Server upon which the Conifg Helper is based is Open Source. If you would like to
contribute to the project, feel free to open a PR or get in touch with us through the
Data and Telemetry
The CircleCI VS Code extension collects usage data for product improvement purposes, respecting the
telemetry.telemetryLevel settings provided by VS Code.
It can be opted out through the VS Code settings page.
By signing in to this extension, you agree to the
This project was made possible by the community surrounding it. You can find more information about
the people and projects which contributed to this extension in the file
We were also inspired by the great work done by community-built extensions:
© 2023 Circle Internet Services, Inc.