microsoft / azure-pipelines-vscode

VS Code extension for working with Azure Pipelines YAML files

Azure Pipelines for VS Code

Get it on the VS Code Marketplace!

This VS Code extension adds syntax highlighting and autocompletion for Azure Pipelines YAML to VS Code. It also helps you set up continuous build and deployment for Azure WebApps without leaving VS Code.

Validation

Basic YAML validation is built in to VS Code, but now you can have syntax highlighting that's aware of the Pipelines YAML schema. This means that you get red squigglies if you say tasks: where you meant task:. IntelliSense is also schema-aware. Wherever you are in the file, press Ctrl-Space to see what options you have at that point.

By default, the extension will highlight known Azure Pipelines files in the root of your workspace. You can change the language mode at the lower right to work with one file at a time. Click the language picker, then choose "Azure Pipelines". If you have files which should always use this extension, set your user or workspace settings to match those file paths with this extension. For example:

{
    "files.associations": {
        "**/ci/*.yml": "azure-pipelines"
    }
}

Schema auto-detection

Out of the box, the extension has a generic schema file that includes only in-box tasks. You probably have custom tasks installed in your organization.

To provide the most relevant IntelliSense, the extension will automatically detect and use your organization's schema! All you need to do is follow the instructions when prompted.

If automatic fetching of the organization schema doesn't work, try signing out and signing back in using the Azure: Sign Out and Azure: Sign In commands from the VS Code command palette (Ctrl/Cmd + Shift + P).

Specific schema

If you need to use a specific schema, that is also possible.

1. Visit https://dev.azure.com/YOUR-ORG-HERE/_apis/distributedtask/yamlschema and save the output as my-schema.json.
2. Edit your workspace's settings.json to include this:

{
  "azure-pipelines.customSchemaFile": "./path/to/my-schema.json"
}

Document formatting

Since this extension defines a new file type ("azure-pipelines"), any YAML formatter you've installed no longer applies to pipelines documents. Hat tip to @mgexm and @dotnetcanuck for sharing how they restored this functionality. We'll demonstrate with the Prettier VS Code extension:

Add this to your settings.json:

"[azure-pipelines]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
},

Both format on save and the Format document command should now work!

Pipeline configuration

To set up a pipeline, choose Azure Pipelines: Configure Pipeline from the command palette (Ctrl/Cmd + Shift + P) or right-click in the file explorer. The guided workflow will generate a starter YAML file defining the build and deploy process.

You can customize the pipeline using all the features offered by Azure Pipelines..

Once the setup is completed, an automatic CI/CD trigger will fire for every code push. To set this up, the extension will ask for a GitHub PAT with repo and admin:repo_hook scope.

Telemetry

VS Code collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more. If you don’t wish to send usage data to Microsoft, you can set the telemetry.enableTelemetry setting to false. Learn more in our FAQ.

Troubleshooting failures

• Selected workspace is not a Git repository: You can configure a pipeline for a Git repository backed by GitHub or Azure Repos. Initialize your workspace as a Git repo, commit your files, and add a remote to GitHub or Azure Repos. Run the following commands to configure git repository:

  git init

  git add *

  git commit -m <commit-message>

  git remote add <remote-name> <remote-url>

• The current branch doesn't have a tracking branch, and the selected repository has no remotes: You can configure a pipeline for a Git repository backed by GitHub or Azure Repos. To add a new remote Git repository, run git remote add <remote-name> <remote-url>

• Failed to determine Azure Repo details from remote url: If you're configuring a pipeline for a Git repository backed by Azure Repos, ensure that it has a remote pointing to a valid Azure Repos Git repo URL.

Extension Development

If you are only working on the extension (i.e. syntax highlighting, configure pipeline, and the language client):

• Run npm install to install all necessary dependencies
• Run npm run watch to automatically rebuild the extension whenever you make changes
• Run the "Extension" debug configuration to launch a VS Code window using your modified version of the extension

If you are also working on the language server:

• Follow the first two steps above
• Clone the azure-pipelines-language-server repository alongside this repository
• Run npm link ../azure-pipelines-language-server/language-server
• Follow the instructions in the language server README to link the language service to the language server
• Add the azure-pipelines-language-server folder to your VS Code workspace
• Run the "Launch Extension & Attach to Server" debug configuration
  • Note: In order to attach to the server, the extension must be activated (in other words, make sure you are editing an Azure Pipelines file)
  • In case the attach request timeouts before the server can start, wait for it to start and then run the "Attach to Server" debug configuration

Contributing

See CONTRIBUTING.md if you want to jump in!

azure-pipelines-vscode's Issues

Unit test main method of schema generation server

steps not showing up after add container resources before jobs.

resources:
  containers:
    - container: ubuntu14
      image: ubuntu:14.04
jobs:
  - job: build_agent
    pool: 
      vmImage: ubuntu-1604
    steps:
      - checkout: self
      - script: './dev.sh layout'
        workingDirectory: src
      - script: './dev.sh package'
        workingDirectory: src
      - task: PublishBuildArtifacts@1
        inputs:
          ArtifactName: agent
          PathtoPublish: _package
  - job: test_agent
    pool:
      name: default
    container: ubuntu16

For tasks, switch to anyOf(if/then) construct

See json-schema-org/json-schema-spec#180 (comment) -- this might match our semantics a little better.

When matching an enum for validation, allow any casing

Schema in this extension can drift from what the server supports

Ideally we would generate the extension's schema from the server-side objects.

Support multiple schema versions, including from the server

We need to support multiple schemas. For instance, when YAML ships in on-prem, that version will be locked, but the service will continue to iterate. We'll need to package a snapshot of each static schema into the extension. (There's only one right now, the service.)

When a workspace has no associated schema, prefer the latest. Give the user a gesture, such as a command in the command palette, to change the association. (To investigate: can we inject a menu in the bottom status bar, alongside the language ID/line endings/encoding menus?)

One of the options - likely the most common - will be a schema from the server/service. The user can specify the Azure DevOps organization (or, eventually, the Azure DevOps Server instance) to use, log into it (using Azure Account if we can), and we'll grab the schema from a known endpoint. This will include the latest core schema, all custom tasks, etc.

We should cache what we retrieve from the server. We'll need to identify a cadence for refreshing it, since it does change periodically. I propose no more often than once a day, with a gesture to go pull a fresh copy as needed.

Telemetry: it would be nice to understand the % of users who keep the default (no association), how many pick a specific static schema, and how many switch to server schema. (We don't need to collect any identifying information about which server or anything, just how many switch to that feature.)

Template intellisense

Intelissense not working with a new file (without save)

The intelisense doesn't seem to be functioning when a file has not yet been saved

• Create a new file (Control N for example)
• Switch the language mode to Azure Pipelines

• Press control space
• No suggestions popup is shown

Workaround:

• save the file as dummy.yaml (it will be recognized as a yaml file)
• switch the type to azure pipelines in Select Language Mode filter)

intelissense now works

Update task schemas from m139

Allow any casing of task names

Bash, PowerShell, cmd syntax highlighting

In a bash block, we should switch to syntax highlighting Bash. Similar for the other script languages.

Activate using commands instead of always activating

Right now we activate on *, which is always.

What we want is to activate on language or onCommand:

https://code.visualstudio.com/docs/extensionAPI/activation-events#_activationeventsoncommand

Docker@1 task has bad enum for `command`

The Docker@1 task has an incorrect enum. It's using the long name of each option, not the actual command. I suspect (without looking) that all enum generation is broken this way.

Show connection information if choosing a connection

Connections are dynamically added per account. When selecting one in YAML, show the user autocomplete with their specific connections loaded from the server.

In CI, regen schema and fail if different than src. Don't use it!

When no schema in a oneOf array matches, it's hard to understand how to fix it

When the language server checks each entry for anyOf and none match, then it chooses an arbitrary branch to use for reporting errors. This can mean that if you mess up one property name, suddenly all your previously-correct properties are reported as not matching.

Add back templateConditionalStepInsertExpression

Caused lost intellisense at least for task name when added. Previous schema:

"templateConditionalStepInsertExpression": {
"type": "object",
"patternProperties": {
"^\${{.*}}$": {
"type": "array",
"items": {
"$ref": "#/definitions/step"
}
}
},
"minProperties": 1,
"maxProperties": 1
}

Task identifiers don't have to come from a preset list

There's a preset list of task identifiers. In reality, the task name can be practically anything since tasks can be created and installed by anyone, not just Microsoft.

Add command to clear schema cache.

Task pane / insert task

For common tasks, offer a quick way to insert the task and its most common inputs.

Intellisense doesn't work until you save the file

Update extension YAML schema to match latest server schema

Cancel and timeout fields go to job?
Add parallel under strategy

Intellisense for macro expressions and object expressions

Macros are string replacements using $( )

Object expressions use the form $[ ]

Make sure anything in /buildtools doesn't get included in release build for extension?

Schema too liberal: accepts both `jobs` and `steps` at the root

To work around bugs in the language server, the schema currently allows both 'jobs' and 'steps' at the root. These should be mutually exclusive.

Language server fails to match when `jobs` and `resources` are both at root

Using the attached schema, the attached .yml should validate. At the root of the schema, it should match "#/definitions/jobsAtRoot" because of the jobs keyword. It fails to match and VS Code complains that jobs is unexpected.

If I temporarily remove both "#/definitions/jobAtRoot" and "#/definitions/phaseAtRoot", it validates. Also if I remove the resources keyword, it validates.

Update the logic to store JSON from the server(each sprint) in a folder with the extension so that we have a history and versioning there

We won't package it with the extension.

Intellisense for build variables

Would be nice to have the agent.*, build.*, and system.* series as suggestions in appropriate places.

Fix integration tests

Task enum list of name + major version needs to be generated.

Configure GitLens in extension

Configuring GitLens was working and now it seems to require configuring in the workspace instead of the extension. We would prefer to configure it in the extension so we don't have to force the user to do it.

We were looking into this because GitLens has over 8.5 million installs so it's likely our users will be using it.

Schema is baked into yaml-schema-service, should be a separate file

The bulk of the schema is hand-generated, and we use yaml-schema-service / generate-yaml-from-json to insert tasks into it. Ideally the base schema would be a templatized file independent of the code, and we would use a simple token replacement to insert the task parts.

Run schema generation when we compile

add `batch` (boolean) to `trigger`

Tasks which require no inputs give an error about matching multiple schemas

Example:

steps:
- task: NuGetToolInstaller@0

By adding one of the non-required inputs, the error goes away.

Update display details for inputs.

Show required inputs, misc other details in the description, and links to more docs (where applicable).

Need to ensure phase and variable names are unique

We can add uniqueItems constraints on arrays such as variables. May need to get a bit more crafty on phases, since it's an object property that has to be unique.

Pipelines files don't have a nice icon

Pipeline on the left, plain YAML on the right.

Convert to using headless integration tests

Phases don't have to be named

Phase names are optional. This shouldn't flag an error:

Run integration tests from command line and in CI

Understand variable scopes

When you add an env: expression, those variables become available for use in scripts. We need to recognize those and allow them for autocomplete.

Even more interesting: a ##vso command can write a new output variable. That variable is available in downstream steps.

Template support

• Hyperlink to template parts elsewhere in the workspace
• Teach the extension about parameters for intellisense
• Help generating a template ("factor out as template"?)

View installation statistics for extension

Use App Insights or some other built in mechanism to see extension install counts.

https://medium.com/@almenon214/adding-telemetry-to-your-vscode-extension-f3d52d2e573c

Investigate node-keytar

There is a README line that says "Currently this library uses libsecret so you may need to install it before running npm install."

Does this mean any machine that uses code that uses their lib on linux needs this installed? If so, seems problematic.

https://github.com/atom/node-keytar

When inserting a task, go ahead and drop in common inputs

Conditionals in notes for task inputs

In scripts, intellisense for ##vso commands

Run server side tests

They have already been copied in, we need to run them.

Intellisense for available vmImages