Setup CI pipeline for iOS projects on gitlab.com

ryanzzff — Sat, 10 Jul 2021 13:27:16 +0000

Overview

Setup CI pipeline with .gitlab-ci.yml
Adding badges for pipeline status and code coverage

Prerequisite

A macOS machine with Xcode and Xcode command line tools installed
The above macOS machine is registered as a GitLab runner
An iOS app with a testing scheme with test cases
Tools
- bundler (optional, if you have dependency for Ruby gems like cocoapods/fastlane, etc.)
- jq (optional, for processing the code coverage report)
- brew install jq

Key Terms of GitLab CI/CD

Pipelines are the top-level component of continuous integration, delivery, and deployment.
Jobs defines what to do, executed by runners
Stages defines when to run the jobs

Setup CI pipeline with .gitlab-ci.yml

stages:
  - prebuild
  - build

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - my-project-path/.bundle
    - my-project-path/vendor

install_dependencies:
  stage: prebuild
  script:
    - unset cd
    - cd my-project-path
    - bundle config set --local deployment 'true'
    - bundle install
  tags:
    - macos_11-2-3
    - xcode_12-4
    - ios_14-4

build_project:
  stage: build
  script:
    - unset cd
    - cd my-project-path
    - xcodebuild clean build test -project my-project.xcodeproj -scheme "CI" CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO
    - xcrun xccov view --report --json DerivedData/my-project-path/Logs/Test/*.xcresult > xcresult.json
    - cat xcresult.json | jq ".lineCoverage" -j | awk '{printf "XCTEST_COVERAGE=%0.2f%%\n",$1*100}'
  tags:
    - macos_11-2-3
    - xcode_12-4
    - ios_14-4

Structure of the configuration file:

line 1-3: defined a pipeline with 2 stages, prebuild and build

line 5-9: defined the paths that will be cached between the jobs

line 11-21: defined the install_dependencies Job

line 23-34: defined the build_project Job

line 28: build and test the Xcode project

line 29-30: gather the code coverage stat

Cache the dependencies between Jobs

my-project-path/.bundle is storing the bundle config
my-project-path/.vendor is storing the installed gems
${CI_COMMIT_REF_SLUG} is the branch or tag name for which project is built

Without cache, the gems installed in the prebuild stage will be deleted when the build stage is executed, even the Jobs are executed on the same machine

The example will share the caches across the same branch

The use of `unset cd`

when rvm is used, it will redefine the cd command as below:

cd () 
{ 
    __zsh_like_cd cd "$@"
}

When the cd command is used in the Job, it will throw ERROR: Build failed with: exit status 1 and exit immediately
unset cd is used to reset cd to be the shell builtin command
- it can be added before the step that used the cd command (as in the example)
- or can be added in .bash_profile

Other points to note

the tags must match the configs in the Runners section in gitlab.com -> project settings -> CI/CD
the file .gitlab-ci.yml should be placed in the root of the git repo
the DerivedData path is set relative to the Xcode project

Adding badges for pipeline status and code coverage

Pipeline Status Badge

To configure the pipeline status:

gitlab.com -> project settings -> General -> Expand the Badges Section
Add Badges with following settings:
- Name: Pipeline Status
- Link: https://gitlab.com/%{project_path}/-/commits/%{default_branch}
- Badge image URL: https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg

Code Coverage Badge

Get the code coverage report in JSON format after the project is built

xcrun xccov view --report --json DerivedData/my-project/Logs/Test/*.xcresult > xcresult.json
Print the code coverage to the job log

cat xcresult.json | jq ".lineCoverage" -j | awk '{printf "XCTEST_COVERAGE=%0.2f%%\n",$1*100}'

the above line is to

get the lineCoveragefield from the JSON
multiply the value by 100
convert the value in percentage
print the value with 2 decimal places

noted that the percentage sign % must be included for Test coverage parsing

Set the Test coverage parsing regular expression to grep the result in step 2.

gitlab.com -> project settings -> CI/CD -> Expand the General pipelines Section
In Test coverage parsing, fill in XCTEST_COVERAGE=(\d+.\d+%)

Add the badge like pipeline status

gitlab.com -> project settings -> General -> Expand the Badges Section
Add Badges with following settings:
- Name: Code Coverage
- Link: https://gitlab.com/%{project_path}/-/commits/%{default_branch}
- Badge image URL: https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg

References

Concepts

https://docs.gitlab.com/ee/ci/pipelines/

Configurations

Caching dependencies between jobs

https://docs.gitlab.com/ee/ci/caching/

Badges

Troubleshoot

ERROR: Build failed with: exit status 1

Using Cocoapods with Gemfile

ryanzzff — Sun, 16 Feb 2020 12:17:55 +0000

If you work in a team, it would be better if all team members have the same development environment. For instance, as an iOS developer, if we are using a different version of Cocoapods to install the 3rd party libraries, the generated Podfile.lock or the .xcworkspace file might be slightly different.

We can use a Gemfile to sync it:

Step 1. Create a file named Gemfile in the same directory of the Podfile and .xcodeproj

source 'https://rubygems.org'
gem 'cocoapods'

you may also specify the version of the cocoapods:

source 'https://rubygems.org'
gem "cocoapods", "1.8.4"

Step 2. Install bundler with gem in user directory

gem install bundler --user-install

Step 3. Install cocoapods with the version specified for the project (into the local relative path vendor/bundle)

bundle install --path vendor/bundle

To verify the version installed:

bundle exec pod --version

Step 4. Instead of using pod install, we now have to use a new command:

bundle exec pod install

Bonus:
We can open the .xcworkspace file automatically with Xcode right after pod install:

bundle exec pod install && xed .

Forem: ryanzzff