CircleCI

The official CircleCI VS Code extension is a new way to interact with CircleCI.

This extension provides an interface to visualize and manage CircleCI runs 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 runs. Available actions include
  • Viewing runs, 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
  • Autocompletion
• Launch commands to validate config files statically, or against your org policy

Getting started

It’s easy to get started with CircleCI for VS Code.

1. 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.

2. 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 can also sign in to CircleCI from VS Code's Accounts menu.

   Select “Log in with your browser” to authenticate via your browser. Alternatively, you may select “Use a personal API token” to authenticate with a Personal API Token. If you don't have one, you can generate a new one for this purpose: the button next to the token's input opens the page.

   If you are an Enterprise customer, select “Log in to a CircleCI Server” and enter your self-hosted server URL. Enterprise customers must authenticate using a Personal API Token.

3. Setup your project

   If your VS Code workspace contains one or more CircleCI projects, the extension will detect them automatically, and the Runs Panel will be populated with your most recent runs.

   If no project is detected, select your projects manually with the VS Code command CircleCI: Select projects, or by clicking on the status bar's "No project".

   Please note that your manual selection will only be persisted if no projects are detected automatically.

   A checkout linked to a project with circleci project link is linked to it here too: its .circleci/info.yml says which project it is, ahead of its git remote, and its project's runs are listed first. A standalone project, whose slug is made of IDs (circleci/<org-id>/<project-id>), can't be told from a git remote, so this is how to have it found. Choosing a project with the Runs Panel's project button writes the same file in the project's checkout, and linking one in the terminal lists its runs straight away.

   ⚠️ Automatic project detection does not work for GitLab projects. Please select your project manually with the `CircleCI: Select projects` command.

4. Configure your Runs Panel

   By default, your Runs Panel lists the latest runs of your current branch. The buttons at the top of the Runs Panel filter them:

   • Branch: your current branch, the default branch, all branches, or My runs, the runs you triggered in every project
   • Status: only runs with a status, such as failed or running
   • Created: only runs newer, or older, than an hour, a day, a week...
   • Reset filters, shown when any filter is set, goes back to your current branch's runs

   The filters in use are shown above the runs. If your workspace has more than one CircleCI project, the project button chooses whose runs are listed; its Other project... chooses from every project in your organizations, standalone ones included.

5. Configure notifications

   You can set up pop-up notifications to warn you when a workflow in your Runs Panel has changed status.

   

   By default, you will receive a pop-up notification every time one of the workflows in your Runs 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 Runs Panel)
   • 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 Runs Panel.

   

The Runs Panel

The Runs Panel lists the most recent runs of the CircleCI project detected in your workspace, newest first, with their workflows and jobs, and lets you monitor their status and interact with them.

For some tree objects, you can perform actions by clicking on the icons which appear when you hover over the item.

Run

Runs are the CircleCI unit of change, and they contain your workflows. Each shows its number, its commit's subject and its status, with its branch, revision, how long ago it was created and who triggered it. Click Load more runs, at the bottom of the list, to see older ones.

Hovering over a Run lets you:

• Open in browser, to view run details in the CircleCI app
• Open the run's configuration

Workflow

Workflows are nested under each Run, 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

Job

Jobs are nested under each Workflow; click one to open its page, with its 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 on a page of its own:
  • Steps: the job's steps beside the selected step's output, streamed while it runs. Right-click a step to open its output in an editor.
  • Tests: once the job ends, its tests, failures first. Filter them by outcome and name, sort them by a column, and select one to see its message.
  • Artifacts: what the job stored, as a file tree. Open one in VS Code, download a file, a folder or all of them, or open one in your browser.
  • Resource Usage: CPU and memory use against the resource class's limits, and each execution's min, mean, max and peak. Hover a chart to see each execution's use at that moment. A peak under half on both says a smaller resource class would do.
  • The page's title bar refreshes the job, reruns its workflow, cancels it and opens it in your browser. Under ... are rerunning it with SSH, SSH into it, and its run's compiled config.

Re-run with SSH

You can re-run jobs with SSH directly from VS Code, either:

• through the job's page, with Rerun Job with SSH under ... on its title bar:

• or by clicking on the action icon next to the job name in the Runs Panel.

In both cases, the SSH session opens in a VS Code terminal:

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 choose a key with the CircleCI: Choose SSH Private Key... command, or set its path in the extension's SSH settings, which the CircleCI: Open settings command opens.

If the job you want to rerun uses parallelism, you will be able to select which job you want to SSH into.

You can read more about debugging with SSH on CircleCI in the Docs.

Status Bar

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, you'll be asked how to log in
• No project - when clicking on the status bar, a list of your projects will open so you can select a project manually
• Success / On hold / Failed, and similar workflow statuses - THIS refers to the status of the top run in your panel. When clicking on the status bar, the relative workflow will come into focus on the CircleCI Runs Panel.
• No internet - when your internet connection is lost

Project and Org Secrets

Below the Runs Panel, two panels list the secrets your selected projects' builds get:

• Project Secrets lists each project's environment variables. Its toolbar adds one, refreshes them, or opens the project's settings in the web app.
• Org Secrets lists the contexts of each project's organization, each opening to its environment variables. Its toolbar creates a context, refreshes them, or opens the organization's settings in the web app. The contexts load a page at a time.

CircleCI only shows the last few characters of a value once it's saved. Hover or right-click a variable to update or delete it, or right-click it to copy its name. Hover or right-click a context to open its page, add a variable to it, open it in the web app, or delete it.

Context pages

A context's page opens in an editor tab, as a new context does once it's created. Like the context's page in the web app, it lists the context's environment variables, and the restrictions on who can use it: to members of groups (except in standalone organizations), to projects, and to pipelines whose values match expressions. Each list has a toolbar to add to it, and to change or remove what's selected; right-click a row for the same, or to copy it. Use the arrow keys to move through a list, Enter to update a variable, and Delete to delete what's selected.

A group restriction is picked from the organization's groups. A project restriction is picked from its projects, which are searched by name as you type. An expression restriction is typed in an editor of its own, which completes the pipeline values a restriction can use, and marks what's wrong with the expression as you type. Add it with the ✓ in the editor's title bar, or Ctrl+Enter (Cmd+Enter on a Mac).

Config Helper

This extension provides in-file assistance with writing, editing and navigating CircleCI Configuration files.

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 repository: circleci-yaml-language-server.

Config validation commands

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

1. 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).

2. 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 set. Policies are given the project and the branch you have checked out, as they would be for a run.

   Please note that this command is only available to Scale customers

3. 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 different file.

Troubleshooting

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 a CircleCI project manually with the CircleCI: Select projects command.

• The following errors concern the ability of the extension 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 a CircleCI project manually with the CircleCI: Select projects command.

• “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 a CircleCI project manually with the CircleCI: Select projects command.

• “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 runs, 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 connection.

• 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”

Need support?

How to contact us

If you find any bugs with this extension or want to provide feedback, you can contact us at cci-vscode-feedback@circleci.com.

Documentation

You can find more information about CircleCI on our official documentation.

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 circleci-yaml-language-server repository.

Additional resources

Data and Telemetry

The CircleCI VS Code extension collects usage data for product improvement purposes, respecting the isTelemetryEnabled and telemetry.telemetryLevel settings provided by VS Code.

It can be opted out through the VS Code settings page.

Privacy Policy

By signing in to this extension, you agree to the CircleCI Privacy Policy.

Contributing

The extension is developed on GitHub: see CONTRIBUTING.md to build it or contribute a change.

Acknowledgements

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 CREDITS.md.

We were also inspired by the great work done by community-built extensions:

• Jody's Extension for CircleCI
• CircleCI Status
• vscode-circleci
• circleci-conig-validator
• Local-CI