playbooks

home / skills / vladimirbrejcha / ios-ai-skills / xcode-cloud

xcode-cloud skill

/xcode-cloud

This skill helps you set up and troubleshoot Xcode Cloud workflows and custom ci_scripts for iOS apps, including XcodeGen generation and tagging.

npx playbooks add skill vladimirbrejcha/ios-ai-skills --skill xcode-cloud

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
3.0 KB
---
name: xcode-cloud
description: Set up, configure, or troubleshoot Xcode Cloud CI/CD workflows and custom build scripts, especially for iOS apps using XcodeGen. Use for requests about Xcode Cloud setup, ci_scripts (ci_post_clone.sh/ci_pre_xcodebuild.sh/ci_post_xcodebuild.sh), build/test/archive automation, or tag-pushing after archives.
---

# Xcode Cloud

## Overview

Provide a repeatable setup for Xcode Cloud custom scripts, with ready-to-copy templates for XcodeGen generation and post-archive Git tagging.

## Quick Start

1. Identify the folder that contains the `.xcodeproj` or `.xcworkspace`.
2. Check whether the `.xcodeproj`/`.xcworkspace` is tracked in git. If it is generated and
   ignored, you must use `ci_post_clone.sh` (or commit the generated project).
3. Create `ci_scripts/` in that folder if missing.
4. Copy templates from `assets/`.
5. Customize variables noted in the templates.
6. `chmod +x ci_scripts/*.sh`.
7. In Xcode Cloud, add required secrets (for tagging) and ensure an Archive action exists.

## Workflow: XcodeGen + Tagging

### 1) Place scripts where Xcode Cloud expects them
Create `ci_scripts/` at the same level as the `.xcodeproj`/`.xcworkspace`. Xcode Cloud only recognizes the three official filenames; use `ci_pre_xcodebuild.sh` (or `ci_post_clone.sh`) for XcodeGen and `ci_post_xcodebuild.sh` for tagging.

### 2) XcodeGen project generation
Use `ci_post_clone.sh` if your `.xcodeproj`/`.xcworkspace` is generated and not committed.
Xcode Cloud validates the project path and schemes before `ci_pre_xcodebuild.sh` runs, so
pre-xcodebuild is too late in that setup.
Copy `assets/ci_post_clone.sh` to `ci_scripts/ci_post_clone.sh`.
Use `ci_pre_xcodebuild.sh` only when the project already exists in the repo.
Adjust the root detection if your `project.yml` is not at repo root.

### 3) Tagging after successful archives
Copy `assets/ci_post_xcodebuild.sh` to `ci_scripts/ci_post_xcodebuild.sh`.
Set `INFO_PLIST_PATH` (or provide it as an Xcode Cloud env var).
Set `TAG_PREFIX` if you want a custom prefix.
Ensure the workflow includes an Archive action; otherwise the script will no-op.
Add `GITHUB_TOKEN` as a secret environment variable in Xcode Cloud.

### 4) Make scripts executable
Run `chmod +x ci_scripts/*.sh` after adding or editing scripts.

## Template Assets

- `assets/ci_pre_xcodebuild.sh`: XcodeGen install + project generation (two-script setup)
- `assets/ci_post_clone.sh`: XcodeGen install + project generation (alternative)
- `assets/ci_post_xcodebuild.sh`: archive-only tag push using `GITHUB_TOKEN`

## Notes

- Use the `apple-docs-research` skill when you need official Apple documentation on Xcode Cloud behavior or environment variables.
- Keep logs free of secrets; use Xcode Cloud secret environment variables for tokens.
- Reference `references/xcode-cloud-notes.md` for quick reminders about doc lookups.
- If you see `Project <Name>.xcodeproj does not exist at <path>`, Xcode Cloud validated the
  project before your script ran. Fix by switching to `ci_post_clone.sh` or committing the
  generated project.

Overview

This skill helps set up, configure, and troubleshoot Xcode Cloud CI/CD workflows and custom build scripts for iOS apps, with ready-to-copy templates for XcodeGen project generation and post-archive Git tagging. It focuses on the three official Xcode Cloud script hooks and on practical fixes when generated projects are not present at validation time. Use it to make Xcode Cloud builds repeatable and safe for automated tagging and archives.

How this skill works

The skill provides templates and step-by-step guidance for placing ci_scripts/ at the same level as your .xcodeproj or .xcworkspace and for using the three recognized filenames: ci_post_clone.sh, ci_pre_xcodebuild.sh, and ci_post_xcodebuild.sh. It explains when to run XcodeGen (post-clone vs pre-xcodebuild), how to configure environment variables and secrets (e.g., GITHUB_TOKEN), and how to enable archive-only tagging after successful builds. It also includes common troubleshooting notes for validation errors and secrets handling.

When to use it

  • Setting up Xcode Cloud for a project that uses XcodeGen to generate the .xcodeproj/.xcworkspace
  • Adding automated Git tag creation and push after successful Archive actions
  • Troubleshooting "Project <Name>.xcodeproj does not exist at <path>" validation errors
  • Preparing scripts (ci_post_clone.sh, ci_pre_xcodebuild.sh, ci_post_xcodebuild.sh) and making them executable
  • Ensuring Xcode Cloud workflows have required secrets and Archive action configured

Best practices

  • Place ci_scripts/ at the same level as the .xcodeproj/.xcworkspace so Xcode Cloud can find official hooks
  • Use ci_post_clone.sh when the project is generated and not committed; Xcode Cloud validates project paths before pre-xcodebuild
  • Store tokens as Xcode Cloud secret environment variables (do not print secrets to logs)
  • Set INFO_PLIST_PATH and TAG_PREFIX via env vars so templates remain reusable across projects
  • Run chmod +x ci_scripts/*.sh after adding or editing scripts and test locally where possible

Example use cases

  • Generate .xcodeproj with XcodeGen during CI using ci_post_clone.sh, then proceed to build and test
  • Automatically create and push a semantic version tag after a successful Archive using ci_post_xcodebuild.sh and GITHUB_TOKEN
  • Fix validation error by switching from ci_pre_xcodebuild.sh to ci_post_clone.sh when the project is generated at clone time
  • Customize tag prefix and plist path via Xcode Cloud environment variables for multi-target apps

FAQ

Why does Xcode Cloud say the project doesn't exist even though my script generates it?

Xcode Cloud validates the project path and schemes before running pre-xcodebuild. If the project is generated at clone time, use ci_post_clone.sh so generation happens before validation.

Where should I store tokens used for pushing tags?

Add tokens (e.g., GITHUB_TOKEN) as Xcode Cloud secret environment variables and reference them in ci_post_xcodebuild.sh. Never echo secrets into logs.