CocoaPods の終了に備えて、cocoapods‑keys から Arkana + SPMへ移行する

はじめに

CocoaPods は 2026 年 12 月でアーカイブ化（read‑only モード）される予定だ。リポジトリを更新できなくなるため、新しい SDK やセキュリティパッチを受け取るには Swift Package Manager（以下 SPM）への移行が必須となる。

これまで cocoapods‑keys プラグインで機密情報（API Key など）を Keychain に保存し、ソースへハードコーディングしない運用を行ってきた。しかし cocoapods‑keys は CocoaPods 依存であるため、SPM へ切り替えるとそのままでは利用できない。

cocoapods‑keys の README で案内されている「Arkana」は CLI ツールかつ SPM に対応しており、CocoaPods 依存から脱却できる点が大きな利点である。

本記事では cocoapods‑keys から Arkana へ機密情報の管理を移行し、Xcode Cloud でも動かすまでの手順をまとめる。

動作環境

• macOS 15.4.1（24E263）
• Xcode 16.2
• Homebrew 4.4.31
• CocoaPods 1.16.2

前回の記事「cocoapods‑keys でシークレットを安全に扱う」で作成したサンプルプロジェクトをそのまま流用する。まだ試していない場合は先にそちらを読むと今回の差分が把握しやすい。

1. Arkana をインストール

まず依存を入れ直す。CocoaPods を残したままでもよいが、cocoapods‑keys はコメントアウトして無効化する。Arkana は最新 2.x 系の方がKotlin 生成・Flavors 対応などが追加されており、より高機能だが、Xcode Cloud 標準ランナーに入っている Ruby が 2.6 系のため、Ruby 2.6 で動作する最終版 1.4.0 を指定する。

# frozen_string_literal: true

source "https://rubygems.org"

gem "cocoapods"
# gem "cocoapods-keys", ref: "818f9d2"   # ← もう使わないのでコメントアウト

# Arkana 1.4.0 は Ruby 2.6 環境で動作する最終版
gem "arkana", "1.4.0"

Gemfile を保存したら bundle install を実行する。Arkana v1.5.0 以降は Ruby 2.7 以上が必須であるため、CI 側が Ruby 2.6 のままであれば、Arkana 1.4.0を使用するしかないだろう。

2. cocoapods‑keys を削除

Podfile に残っている plugin 'cocoapods-keys', … のブロックをまるごと削除する。

plugin 'cocoapods-keys', {
  :project => "SampleCocoaPodsKeys",
  :keys => [
  "ApiKey",
  "ApiBaseUrl"
  ]
}

古いキャッシュを綺麗にするため次のコマンドを実行しておく。

bundle exec pod deintegrate
bundle exec pod repo update
bundle exec pod install

これでプロジェクトから cocoapods‑keys を完全に取り除けた。

3. Arkana の設定ファイルを用意する

鍵の名前と環境を宣言する .arkana.yml、そして実際の値を置く .env をプロジェクト直下に配置します。.env は機密情報が入るため、必ず .gitignore に追加する。

ここでは内容を詳しく解説する。

3‑1. .arkana.yml

package_manager: spm
import_name: ArkanaKeys

environments:
  - Debug
  - Release          # Build Configuration に合わせて必要なら追加

environment_secrets: # 環境ごとに異なる鍵
  - apiKey

global_secrets:      # どの環境でも共通
  - apiBaseUrl

3‑2. .env

apiKeyDebug=api1234
apiKeyRelease=api5678
apiBaseUrl=https://example.com/api

3-3. arkana を実行してSPMパッケージを作成する

ファイルを保存したら bundle exec arkana を実行する。

ArkanaKeys/ というローカル Swift Package が生成されれば成功だ。SPM を採用している場合は File → Add Packages → Add Local… で内側の ArkanaKeys フォルダを追加する。

4. 既存コードを書き換える

旧 Keys フレームワークを利用していた箇所を ArkanaKeys に差し替える。主に import とプロパティ名のみが変わる。

import ArkanaKeys
import SwiftUI

struct ContentView: View {
    private let env    = ArkanaKeys.Debug()   // Debug または Release
    private let global = ArkanaKeys.Global()

    var body: some View {
        VStack {
#if DEBUG
            Text("API KEY: \(env.apiKey)")
            Text("BASE URL: \(global.apiBaseUrl)")
#endif
        }
    }
}

インポート名やクラス名は .arkana.yml の import_name、生成時のプロジェクト名によって変わるため自分の環境に合わせて読み替えること。

実行後のスクリーンショット。

5. Arkana をビルド前に自動実行する

.env を変更した直後や CI 環境ではビルド前に Arkana を走らせ、最新の Keys を再生成する必要がある。Xcode プロジェクトの Build Phases → Run Script に次の 1 行を入れると自動化できる。

bundle exec arkana

.env を頻繁に変更しない場合は、Run Script を外して手動実行でも問題ない。

6. Xcode Cloud で Arkana を動かす

Xcode Cloud の macOS ランナーは Ruby 2.6 + RubyGems 3.0.3 というやや古い環境で動く。システム領域は書込不可のため、Bundler をユーザ領域に入れる。

#!/bin/zsh
set -euo pipefail

cd "$CI_PRIMARY_REPOSITORY_PATH/SampleCocoaPodsKeys"

# 書き込み権限がないためエラーが発生する。Bundler をユーザ領域にインストールさせる
export GEM_HOME="$HOME/.gem"

# どのRubyを使用しているか確認する
echo "🔎 Ruby executable: $(which ruby)"
echo "🔎 Ruby: $(ruby -v)"
echo "🔎 RubyGems: $(gem --version)"

# Bundler をインストールする (Gemfile.lock の BUNDLED WITH と合わせる)
BUNDLER_VERSION="2.4.22"
gem install bundler -v "$BUNDLER_VERSION" --no-document --quiet
bundle install --quiet 

# ArkanaKeys パッケージを生成する
bundle exec ruby -e "puts '🔎 Arkana version: ' + Gem.loaded_specs['arkana'].version.to_s"
bundle exec arkana

CI (Xcode Cloud など) では「Environment Variables」に apiKeyDebug などを登録しておく。

実例: 個人アプリでの Arkana 活用例 (RevenueCat)

Arkana が実際に役立つ例として、個人アプリで使用している RevenueCat SDK の API キーを移行してみた。

# .arkana.yml 抜粋
global_secrets:
  - revenueCatApiKey

revenueCatApiKey=appl_REVENUE_CAT_API_KEY

アプリ側は次のように書き換えるだけで完了だ。

Purchases.configure(withAPIKey: ArkanaKeys.Global().revenueCatApiKey)

Arkanaは .env が存在しない場合、環境変数を参照するため、CI では同じキーを環境変数として渡しておくと、.env をコミットしなくても安全にビルドが通る。

まとめ

• CocoaPods が read‑only 化すると cocoapods‑keys は更新できなくなってしまう
• Arkana では、SPM + CLI で、(まったく同じ手法ではないが)機密情報の管理を引き継げる
• 必要ファイルは .arkana.yml と .env の 2 つ。ビルド前に bundle exec arkana を実行するだけで完了。
• Ruby 2.6 ランナーでは Arkana 1.4 系が上限。Ruby 2.7 以上に切り替えたら 2.x 系へ上げて機能拡張（Kotlin 出力・Flavors など）を利用できる。

現在 cocoapods‑keys を使っているのであれば、CocoaPods 終了まで時間はあるが、早めに移行フローを試しておくと安心だろう。

(2025/05/14追記)Xcode Cloudで最新のArkanaを使うためにビルド環境のRubyをアップデートする

本記事で、Arkana最新版がRuby 2.7以上を要求していると書いた。Xcode Cloudでも任意のバージョンのRubyをインストールできることがわかったので別途記事を書いた。この方法を利用すればArkanaの最新版を導入できた。

https://dev.classmethod.jp/articles/xcode-cloud-custom-ruby-version/