2 min read

Azure DevOps

Last Updated - Platform 21.0 - SDK 16.0

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

Templates

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.

Pipelines

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

Tasks

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

Versioning

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:

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.

Create a new .yml file with a simple name describing what the pipeline is for. E.g. validate.yml for PR validation.
Add a repository resource reference to the PoqTooling repository.

resources:
  repositories:
    - 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

Add the variables.yml to your pipeline. This is required by most PoqTooling templates.

variables:
  - template: azure/variables.yml@tooling

Add the functionality to your pipeline. your own steps using PoqTooling tasks or extend a PoqTooling template.

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

variables:
  - template: azure/variables.yml@tooling
    parameters:
      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

Add your new pipelines to the Azure DevOps UI following our best practises guide.