Azure-devops-docs: document the special azure-pipelines.yml file

[ForrestTrepte]

There is a special filename azure-pipelines.yml. If you place this in the root of your project, Azure DevOps will automatically create a build pipeline from this file. However, I haven't been able to find official documentation of this special filename.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 7458d5b2-1bb7-7d87-7ce6-2b0c430b0155
• Version Independent ID: edf5bbd3-a3f0-5426-e985-31290f8afd05
• Content: YAML schema - Azure Pipelines
• Content Source: docs/pipelines/yaml-schema.md
• Product: devops
• Technology: devops-cicd
• GitHub Login: @vtbassmatt
• Microsoft Alias: macoope

[vtbassmatt]

This doesn't belong in the schema doc. @davidstaheli over to you for triage.

[ForrestTrepte]

That makes sense. Putting this documentation in a different location would be fine.

[ForrestTrepte]

Use Azure Pipelines already mentions this filename as an example, but I'm not sure if that would be a good location for documenting the details about the special nature of that specific filename.

By the way, I also made a feature request asking to be able to have multiple files like this. If that's possible, it would be great to document it.

[davidstaheli]

Thanks for reporting this, @ForrestTrepte. We updated Azure Pipelines to detect the presence of this file, but ask if you want to use it, and also allow choosing a different file. Hopefully this will reduce the mystery.

[ForrestTrepte]

Hmm. For me, the key value of this file was that a repository would carry with it all the information needed to create your build pipeline. Just making the repository would automatically set up your build configuration without any manual steps performed by the user--very nice! We use this in the template that we use when new projects are created, and we'd prefer not to have extra steps (e.g. click Yes when such-and-such dialog appears). From my perspective, I would have preferred to document the naming convention and not to ask if you want to use it.

[davidstaheli]

Good point, @ForrestTrepte. And please allow me to clarify. We still automatically use the azure-pipelines.yml file when it is detected, but before the pipeline is created, a link is provided to -not- use the file and pick a different file instead. Regardless of whether the file is detected, some manual steps are necessary to set up the pipeline. :(

We like what you suggested in the feature request. One possibility we're considering is, if there is a folder named .azure-pipelines, pipelines would automatically be created for the pipeline files in that folder. Would that meet your needs?

[ForrestTrepte]

Ah, informing the user about the automatically-created pipeline and giving them a link to opt out sounds like a great way to make the feature more clear to users. Thanks for explaining, @davidstaheli.

For the feature request, placing multiple pipeline files in a special folder is a great solution. I like that I could organize and name them whatever I like within that folder.

I might prefer not to have a period at the beginning of a folder. Beginning with a period makes me think of .vs and .git folders that should be ignored or Unix files that are hidden, but these files would be quite important. Not a big deal though--I'd use the feature regardless of the folder name.

[davidstaheli]

Good point! Folder names .azure-pipelines and azure-pipelines could both be supported.

[atlaskerr]

@davidstaheli Is the .azure-pipelines feature supported yet?

[mcalsada]

@davidstaheli Is the .azure-pipelines feature supported yet?

@davidstaheli, Any updates?