Azure Pipelines in action pt. I - making the most of a bad hand
While writing this thing I realized I've not tried hard enough to find working tools and workflows. Guess I gave up somewhere along the way... Anyway, here's a 'beginning of 2025' edition of the pain points I have when working with Azure Pipelines and how one might make it more tolerable - and get in shape at the same time!
Despite going at it for five years, I still dislike Azure Pipelines. Mostly because of accursed YAML, but there are also some interesting design choices, causing workarounds to cascade everywhere in complex workflows. I'll note these in the later parts of this series when we'll see some actual pipelines.
Despite that the biggest pain point for me has been the development process itself, which, when naively developing, using templates, is roughly:
- Implement your new change to your template repo
- Update your test repo with the relevant changes and point to the new template
- Run the pipeline - notice a bunch of syntax mistakes or typos and spend a few cycles of 1-3 to move on
- Run the now seemingly working pipeline to the point of the new functionality - notice some error in the logic, limitation in the environment etc. Work around, and repeat a few cycles of 1-4 (since 3 became relevant again when you dared to touch the pipeline
This has kicked me in the gut in the form of "This should take 5 minutes. It cannot possibly take more than 20" to proceed to taking the entire day. Having done this enough times, I no longer think anything will be a 5 minute job and prepare accordingly.
If you work as a digital plumber, I recommend a demanding physical regimen of
whenever I'm working on pipelines and waiting for one more iteration to complete, I do squats/pushups/whatever
You'll be in shape in no time!
The tooling
The best combo for writing the pipelines seems to be VS Code with Azure Pipelines extension. I'm using Rider for everything else and have been too stubborn to switch (for this one thing), but since there's no good tooling over at JetBrainsland I think I've had enough of the torture. I just installed the relevant plugins to VSCode, and though it feels like admitting defeat, I'll let you know how it goes..
For other editors, Rider included, you should at minimum have YAMLLint to catch the most egregious syntax errors (I really hate whitespace delimited languages...). As the name implies, it can also be used to lint the files for a unified style between developers and editors. Rider seemingly has the Azure Pipeline YAML schema available, but in my experience, it just gives warnings of illegal elements in place where they're not, and does not really give any useful errors of any sort.
If you need to update a single file, be it a template file or the actual pipeline, I currently tend to go directly to the pipeline editor directly. It has the context knowledge of your referenced templates, and you can one-click validate the entire call chain. A couple of caveats:
- in order to access the pipeline editor, you must first create a pipeline. Editing YAML in the repos view has none of this context. This is a bit of extra work, but as I pointed out before, I don't skimp on preparations anymore...
- if you're developing a new template file, all parameters need to have values, or the validation will fail before getting to anywhere useful. So
default: asdit is - just remember to not commit these. - multifile editing is a pain unless the files you're editing are referenced from a single file. Then you can just validate the top-level file and all the references are validated with it.
The process
Expect your pipeline to fail. Seriously, this is a really important mindset so you can start doing the optimizations at the start, instead of slowly peeling away the cruft, one run at a time.
In practice this means that if you have a pipeline that does A -> B -> C -> D -> E and you're looking to add F, don't even try appending it to the chain and just expect it to work, since it won't. Instead, develop F with as few dependencies as possible: if the pipeline you're developing is doing a dotnet build, npm build, bicep installations etc. but you're just appending functionality for modifying the appsettings.json file inside the build artifact, skip or remove all unrelated stages/jobs/tasks and just do A->F. This saves your time and does not waste compute.
Conclusion
Working on Azure Pipelines can be an excruciating process, but with proper tooling and mindset the pain can be relieved. Tooling is very important here, so learn from my mistakes and pay attention to it from the start.
I'm glad I started writing this post since it made me pay attention to new ways of working - I just completed a PR that formatted all our templates to a single style thanks to the VS Code setup described above + Prettier + Format Files. This API approach for pipeline validation also seems interesting. This is just the kind of rewiring I was hoping for!