2 min read

Azure DevOps

Last Updated - Platform 21.0.0 - SDK 16.0.0

PoqTooling supports Azure DevOps YAML pipeline templates in the azure directory.

File Overview
File Overview


The listed template pipelines below are composed of provided template tasks. You can build custom pipelines using the template tasks or directly extend a pipeline to gain it's functionality.

All templates require using the azure/variables.yml in your pipelines.

The variables.yml template requires a group to be set up in Azure DevOps named Secrets. It provides environment variables for all tasks and most can be overridden in the UI at queue time.


File PathDescription
azure/validate.ymlUse for PR validation. Generates the project then builds and tests the default target.
azure/simulator.ymlUse manually by QA to build and upload an xcarchive (with .app) to an artifact on the pipeline run.
azure/firebase.ymlUse to build and upload an ipa to Firebase.
azure/testflight.ymlUse to build and upload an ipa to TestFlight and notify Slack.


File PathDescription
azure/github/authorize.ymlUse to authorize your pipeline with a secret GitHub.Token variable.
azure/setup/generate.ymlUse to setup the agent, generate the project and optionally cache the SPM dependencies.
azure/xcode/archive.ymlUse to archive the app and upload the output as a pipeline artifact.
azure/xcode/validate.ymlUse to build and test the app.


The tooling repository is semantically versioned with special moving tags for CI/CD to match major versions.

When referencing the tooling repo you can use tags such as refs/tags/latest-v3 to take the latest release of that major version. We move these tags to the latest commits for every new release.

Add a YAML pipeline to your repository

To add a new YAML pipeline that uses the PoqTooling repo:

  1. Create or open the directory named .azure in the root of your repository. This is to organise your pipelines.

Azure DevOps does automatically pick up a single pipeline file in the root directory named azure-pipelines.yml. But maintaining a single pipeline that handles PR validation and rebuilding per destination can be painful.

  1. Create a new .yml file with a simple name describing what the pipeline is for. E.g. validate.yml for PR validation.
  2. Add a repository resource reference to the PoqTooling repository.
- repository: tooling
type: github
name: poqcommerce/Poq.iOS.Tooling
ref: refs/tags/latest-v3 # Change the version to match the latest major version.
endpoint: poqcommerce
  1. Add the variables.yml to your pipeline. This is required by most PoqTooling templates.
- template: azure/variables.yml@tooling
  1. Add the functionality to your pipeline. your own steps using PoqTooling tasks or extend a PoqTooling template.
  1. Customise the parameters of variables.yml and/or any of the used PoqTooling templates. Continue to next section.

For a full list of parameters check the notes at the start of the variables.yml file.

Most of the azure templates have notes at the start of their files.

Adding UI parameters to your pipeline

Runtime parameters can be exposed to the Azure DevOps queue time UI. They are strongly typed but cannot be optional which can be a pain.


Below are a few common parameter examples and their PoqTooling usage. For most of the PoqTooling supported parameters anyone running the pipeline may override them using custom variables.

For string type text parameters you can specify $(nil) to set an empty string. This can be set as the default value to make the fields somewhat optional.

Specify a fixed version of Xcode

A common problem before moving to YAML pipelines was the inability to specify the required version of Xcode with the code.

With YAML pipelines using the PoqTooling templates the default version of Xcode is shifted with major releases. This matches the SDK major releases which is the best possible case.

To fix the version of Xcode specify the version parameter of the variables.yml file. You may also need to specify the VM Image (supported images can be found here).

- template: azure/variables.yml@tooling
vmImage: macOS-11
xcodeVersion: 13.2

If you want to provide a choice in UI you can specify these as values of a parameter. These can be overridden manually using the custom variables Xcode.DeveloperDir and VM.Image.

Next steps