The official CircleCI VS Code extension is a new way to interact with CircleCI.
This extension provides an interface to visualise 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, jobs statuses
- Viewing test outputs
- Downloading artifacts
- Approving jobs
- Re-running builds
- 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
It’s easy to get started with CircleCI for VS Code.
Install the extension from within VS Code, or download it from the marketplace
For this extension to work, you will need VS Code version
1.67 or above.
Authenticate into CircleCI through the login page.
You will need to be logged into app.circleci.com in order to
create a Personal Api Token.
If you are an Enterprise customer, you will first need to enter your self-hosted server URL at
the bottom of the Settings page.
Open a project that contains a valid circleCI configuration file (
manually select an existing CCI project
* Please note that you can skip steps 2 and 3 if you only want to use our in-file helper for
CircleCI configuration files
Configuring the extension
⚠️ Please note that the Pipelines Manager does not yet support Gitlab projects.
If you want to take full advantage of the capabilities of this extension, we recommend you take a
couple of minutes to configure it according to your needs.
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
You can customize the following parameters:
Choice of which pipelines you want to visualize and interact with
- You can select one project (this is automatically detected if you have a valid
circleci/config.yml file), but can be changed
- You can follow only your pipelines, or those authored by anyone
- You can follow all branches, or only your current branch
- You can decide to follow only pipelines that include workflows and jobs with specific statuses
Choice of what events you want to be notified of
- Changes of workflow status (for instance, you might want to receive a push notification when a
workflow fails, but not when it succeeds)
The Pipelines Panel
The Pipelines Panel lists your most recent pipelines, jobs and workflows, and lets you monitor their
status and interact with them.
For each object, you can trigger certain events on hover.
Pipelines are the top level tree item, and they contain your
workflows. Hovering over a Pipeline lets you:
- Open in browser, to view pipeline details in the CircleCI app on 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, on your default web browser
- Rerun workflow from start, to re-triggered the entire workflow
Jobs are nested under each Workflow, and can contain Tests
and Artifacts. Hovering over a Job lets you:
- Open in browser
- Approve job (only if Job is on hold)
- Cancel job (only if Job is running)
Within a Job, you can:
- Load tests, if you have configured test metadata to be available
- Load artifacts, to load any artifacts created by the Job. Once the artifacts are loaded, you
can download them by clicking on them.
You can set up notifications to warn you when a workflow in your Pipelines Panel has changed status.
If you are not following a workflow in the Pipelines Panel, you will never be notified about a
status change. For instance, if you have set in your configuration to follow only the “current
branch”, you cannot be notified of status changes relative to other branches.
We recommend not enabling notifications for status changing to “running”.
The Status Bar provides synthetic 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 - it 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.
This extension provides in-file assistance to writing, editing and navigating CircleCI Configuration
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 to avoid you
having to continuously switch to your browser to check the docs whenever you are editing your
configuration. That said, 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
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
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 extensions ability to link your workspace to a Git repository.
“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 canceled 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 anonymous usage data for product improvement purposes,
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 VS Code extension is licensed under the MIT license.
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.