In this tutorial, we are going to configure a GitHub repository to deploy iOS app releases to App Store Connect using GitHub Actions. We will create a GitHub Actions workflow that builds our iOS app project every time we push commits to GitHub and uploads our built app to App Store Connect every time we push a release tag.

在本教程中，我们将配置一个GitHub存储库，以使用GitHub Actions将iOS应用版本发布到App Store Connect 。 我们将创建一个GitHub Actions工作流程，该流程将在每次将提交推送到GitHub时构建iOS应用程序项目，并在每次按下发布标记时将构建的应用程序上传到App Store Connect。

We are going to keep things as simple as possible with regard to code signing and provisioning profiles. This should work well for simpler apps and projects with only one primary developer. If you work on a large team or your project includes multiple targets, you may benefit from taking a different approach.

关于代码签名和供应配置文件，我们将使事情尽可能简单。 对于只有一名主要开发人员的较简单的应用程序和项目，此方法应该可以很好地工作。 如果您在一个大型团队中工作，或者您的项目包含多个目标，则可以从采用其他方法中受益。

If you’d like to see a live example of a repository configured to use the workflow described in this tutorial, you can take a look at this project.

如果您想查看配置为使用本教程中描述的工作流的存储库的实时示例，可以查看该项目 。

工作流程假设 (Workflow Assumptions)

The GitHub Actions workflow described in this tutorial assumes that the repository it is running in contains a single Xcode project or workspace and that the first scheme of the project or workspace builds an iOS app.

本教程中描述的GitHub Actions工作流假设其运行的存储库包含单个Xcode项目或工作空间，并且该项目或工作空间的第一个方案构建了一个iOS应用。

The workflow also assumes that the iOS app target is configured as described below.

该工作流还假定按以下说明配置了iOS应用程序目标。

代码签名和配置文件 (Code Signing and Provisioning Profiles)

The situation with signing certificates and provisioning profiles used to be more confusing and toilsome. It has been a long ride, but with Xcode 11, things are pretty easy. Nearly every task that used to require a trip to the Apple Developer portal can now be handled from within Xcode. Signing certificates can be created from within Xcode’s preferences (for both development and distribution). Provisioning profiles are generated automatically when “Automatically manage signing” is enabled for the target.

签署证书和供应配置文件的情况曾经更加混乱和繁琐。 这已经很漫长了，但是有了Xcode 11，一切就变得很容易了。 现在，几乎所有以前需要访问Apple Developer门户的任务都可以在Xcode中处理。 可以从Xcode的首选项(用于开发和分发)中创建签名证书。 为目标启用“自动管理签名”后，配置文件将自动生成。

Having signing automatically managed is great for development, but it makes things more complicated in the context of a platform like GitHub Actions. Because the signing certificate and provisioning profile aren’t stored in the project repository — and because the project is built on a different host every time — automatically managed signing potentially results in a new certificate and corresponding provisioning profile being created every time the workflow runs. This leads to an explosion of certificates and profiles in the developer portal.

自动管理签名对于开发非常有用，但是在GitHub Actions这样的平台的情况下，事情变得更加复杂。 由于签名证书和配置文件未存储在项目存储库中，并且每次都在不同的主机上构建项目，因此自动管理签名可能会导致每次工作流程运行时都创建新的证书和相应的配置文件。 这导致开发人员门户中证书和配置文件的爆炸式增长。

There are a variety of approaches to deal with this complication. For instance, the fastlane project includes support for a code signing workflow that depends on encrypting the certificates and profiles and then keeping them in a separate git repository accessible to the CI system.

有多种方法可以处理这种并发症。 例如， fastlane项目包括对代码签名工作流的支持，该工作流取决于对证书和配置文件进行加密，然后将它们保存在CI系统可访问的单独的git存储库中。

The approach we will take in this tutorial is to store the signing certificate and provisioning profile as GitHub repository secrets. Our workflow will import the signing certificate into a keychain and write the provisioning profile to the filesystem before it builds the project.

我们在本教程中将采用的方法是将签名证书和供应配置文件存储为GitHub存储库密钥。 我们的工作流程会将签名证书导入到钥匙串中，然后在配置项目之前将配置文件写入文件系统。

项目设置 (Project Setup)

Feel free to leave “Automatically manage signing” enabled for the “Debug” build configuration of your iOS app target, but the setting must be disabled for your “Release” build configuration. By disabling automatically managed signing in the project, we ensure that we can test our signing and distribution process manually using the same certificate and profile as we use in the workflow.

随时为iOS应用目标的“调试”构建配置保留启用“自动管理签名”功能，但必须为“发布”构建配置禁用该设置。 通过禁用项目中的自动管理签名，我们确保可以使用与工作流中相同的证书和配置文件来手动测试签名和分发过程。

Disable the “Automatically manage signing” build setting now:

现在禁用“自动管理签名”构建设置：

Create an App Store identifier and a distribution provisioning profile. Depending on your app’s capabilities, you can create a provisioning profile using either a wildcard app identity or a specific app identity.

创建一个App Store标识符和一个分发设置配置文件 。 根据应用程序的功能，您可以使用通配符应用程序标识或特定应用程序标识来创建配置文件。

Download the profile.

下载配置文件。

Import the profile into the project using the “Provisioning Profile” menu in the “Release” build configuration:

使用“发布”构建配置中的“供应配置文件”菜单将配置文件导入项目：

Importing the profile will set the “Provisioning Profile” build setting to the name of the imported profile, the “Code Signing Identity” build setting to “iOS Distribution,” and the “Development Team” build setting to the team name associated with the provisioning profile.

导入配置文件会将“ Provisioning Profile”构建设置设置为导入的配置文件的名称，将“ Code Signing Identity”构建设置设置为“ iOS Distribution”，以及“ Development Team” 构建设置到与配置文件关联的团队名称。

Make sure you have an “iOS Distribution” or “Apple Distribution” signing certificate. Navigate to “Xcode > Preferences… > Accounts,” select your Apple ID, and click “Manage Certificates…” If you don’t see an appropriate signing certificate, you should create an “Apple Distribution” signing certificate using the +˅ button.

确保您具有“ iOS Distribution”或“ Apple Distribution”签名证书。 导航到“ Xcode>首选项...>帐户”，选择您的Apple ID，然后单击“管理证书...”。如果没有看到合适的签名证书，则应使用+˅按钮创建“ Apple Distribution”签名证书。

That’s it for the project configuration. You should probably try submitting your app to App Store Connect at least once manually using Xcode to verify that your project settings are correct.

项目配置就是这样。 您可能应该尝试使用Xcode至少一次手动将您的应用提交到App Store Connect，以验证您的项目设置正确。

GitHub的秘密 (GitHub Secrets)

There are five secrets we need to store in GitHub in order for the workflow to run successfully:

为了使工作流成功运行，我们需要在GitHub中存储五个秘密：

• The encryption password for the signing certificate data签名证书数据的加密密码
• The signing certificate data签名证书数据
• The provisioning profile data供应配置文件数据
• The App Store Connect usernameApp Store Connect用户名
• The App Store Connect passwordApp Store Connect密码

To add each secret to your GitHub repository, you will first need to navigate to the repository’s “Settings” tab. Then select “Secrets” from the sidebar. Click “New secret,” then enter the name of the secret and the value. Finally, click “Add secret.”

要将每个机密添加到GitHub存储库，您首先需要导航到存储库的“设置”选项卡。 然后从侧边栏中选择“秘密”。 单击“新机密”，然后输入机密名称和值。 最后，点击“添加秘密”。

SIGNING_CERTIFICATE_PASSWORD (SIGNING_CERTIFICATE_PASSWORD)

We must first choose an encryption password. You may choose any password you like, but if you’d like some inspiration, here is my favorite shell one-liner to generate a password, copy it to the clipboard, and print it:

我们必须首先选择一个加密密码。 您可以选择自己喜欢的任何密码，但是如果您想得到一些启发，请使用我最喜欢的shell一线生成密码，然后将其复制到剪贴板并打印：

< /dev/urandom \  LANG= \  tr -dc a-zA-Z0-9 \  | head -c 32 \  | pbcopy \  && pbpaste \  && echo

Paste the password as the value of the SIGNING_CERTIFICATE_PASSWORD secret.

将密码粘贴为SIGNING_CERTIFICATE_PASSWORD密码的值。

SIGNING_CERTIFICATE_P12_DATA (SIGNING_CERTIFICATE_P12_DATA)

To generate the encrypted certificate data, we will next export the certificate identity from the Keychain Access app. To do this, open the Keychain Access app, make sure your default “login” keychain is selected, and then select the “My Certificates” category. Select your “Apple Distribution” (or “iOS Distribution”) certificate from the list and choose “Export Items…” from the “File” menu. Leave the file format set to “Personal Information Exchange (.p12)” and click “Save.” Paste the value of the SIGNING_CERTIFICATE_PASSWORD secret when prompted for an encryption password. Then enter your local account credentials when prompted by Keychain Access.

为了生成加密的证书数据，我们接下来将从Keychain Access应用程序导出证书身份。 为此，请打开“钥匙串访问”应用程序，确保已选择默认的“登录”钥匙串，然后选择“我的证书”类别。 从列表中选择“ Apple Distribution”(或“ iOS Distribution”)证书，然后从“ File”菜单中选择“ Export Items…”。 将文件格式设置为“个人信息交换( .p12 )”，然后单击“保存”。 当提示您输入加密密码时，粘贴SIGNING_CERTIFICATE_PASSWORD密码的值。 然后在钥匙串访问提示时输入您的本地帐户凭据。

Next, open a terminal window and find the p12 file on disk. Run the following command to base64-encode the file and copy it to your clipboard:

接下来，打开一个终端窗口，然后在磁盘上找到p12文件。 运行以下命令对文件进行base64编码，然后将其复制到剪贴板：

cat Certificates.p12 | base64 | pbcopy

Paste the copied text as the value of the SIGNING_CERTIFICATE_P12_DATA secret.

将复制的文本粘贴为SIGNING_CERTIFICATE_P12_DATA密码的值。

PROVISIONING_PROFILE_DATA (PROVISIONING_PROFILE_DATA)

We need to base64-encode the provisioning profile that we created and downloaded during the project setup and then copy it to our clipboard. Run the following command, replacing the profile.mobileprovision filename with the name of the provisioning profile you downloaded:

我们需要对我们在项目设置过程中创建和下载的配置文件进行base64编码，然后将其复制到剪贴板。 运行以下命令，将profile.mobileprovision文件名替换为您下载的供应配置文件的名称：

cat profile.mobileprovision | base64 | pbcopy

Paste the copied text as the value of the PROVISIONING_PROFILE_DATA secret.

将复制的文本粘贴为PROVISIONING_PROFILE_DATA密码的值。

APP_STORE_CONNECT_USERNAME (APP_STORE_CONNECT_USERNAME)

This secret should be set to the Apple ID of your developer account.

此机密应设置为您的开发人员帐户的Apple ID。

APP_STORE_CONNECT_PASSWORD (APP_STORE_CONNECT_PASSWORD)

This secret should be set to an application-specific password for your Apple ID account. Follow these instructions to create an application-specific password.

此机密应设置为您的Apple ID帐户的应用程序专用密码。 请按照以下说明创建应用程序专用密码。

关于身份验证的注意事项 (A Note About Authentication)

We need to use an application-specific password to authenticate to App Store Connect when running in the GitHub Actions context because the tool we are going to use to submit the app to App Store Connect doesn’t support the use of regular passwords when the account has two-factor authentication enabled. Two-factor authentication has been required for developer accounts with the “Account Holder” role since 2019.

在GitHub Actions上下文中运行时，我们需要使用特定于应用程序的密码对App Store Connect进行身份验证，因为当帐户使用该帐户时，我们将用于将应用程序提交至App Store Connect的工具不支持使用常规密码启用了双重身份验证 。 自2019年以来，对于具有“帐户持有人”角色的开发人员帐户，要求进行两步验证。

Instead of creating an application-specific password, we could create a separate Apple ID that doesn’t have two-factor authentication enabled. We would then add it to the team without the “Account Holder” role. This is potentially a more secure solution, but it requires more effort to set up and maintain. For this tutorial, we will use an application-specific password.

除了创建特定于应用程序的密码外，我们还可以创建一个单独的没有启用两因素身份验证的Apple ID。 然后，我们将其添加到没有“帐户持有人”角色的团队中。 这可能是一种更安全的解决方案，但需要更多的精力来设置和维护。 在本教程中，我们将使用应用程序专用密码。

工作流程脚本 (Workflow Scripts)

In order to keep the workflow file readable and to make the steps more debuggable, we are going to put some of our workflow step logic into separate script files. We will write three scripts and install them into a scripts directory adjacent to our workflows inside the .github directory. The first script will read the project file and set a workflow job environment variable. The second will set up a default keychain and import the signing certificate into it. The third will write the provisioning profile to disk.

为了保持工作流文件的可读性并使步骤更可调试，我们将把一些工作流步骤逻辑放入单独的脚本文件中。 我们将编写三个脚本并将它们安装到.github目录中与工作流相邻的scripts目录中。 第一个脚本将读取项目文件并设置工作流程作业环境变量。 第二个将设置默认钥匙串并将签名证书导入其中。 第三个将配置文件写入磁盘。

Create .github/scripts/set-env-from-xcodeproj.sh:

创建.github/scripts/set-env-from-xcodeproj.sh ：

This script determines the name of the first scheme in the project and then reads the value of the PRODUCT_NAME build setting. It uses the set-env workflow command to set a job-level environment variable of the same name. The environment variable will be used in later steps of the workflow.

该脚本确定项目中第一个方案的名称，然后读取PRODUCT_NAME构建设置的值。 它使用set-env 工作流命令来设置相同名称的作业级环境变量 。 环境变量将在工作流的后续步骤中使用。

Create .github/scripts/import-certificate.sh:

创建.github/scripts/import-certificate.sh ：

This script creates a new keychain, makes it the default, unlocks it, and configures it to stay unlocked. Then it base64-decodes signing certificate data from the SIGNING_CERTIFICATE_P12_DATA environment variable and imports it into the keychain using a decryption password that comes from the SIGNING_CERTIFICATE_PASSWORD environment variable. Finally, some keychain magic is sprinkled on top.

该脚本创建一个新的钥匙串，使其成为默认的钥匙串，对其进行解锁，并将其配置为保持解锁状态。 然后，它的Base64解码来自签名证书数据SIGNING_CERTIFICATE_P12_DATA环境变量，并使用来自解密密码进口入钥匙扣SIGNING_CERTIFICATE_PASSWORD环境变量。 最后， 一些钥匙链魔术散落在上面。

Create .github/scripts/import-profile.sh:

创建.github/scripts/import-profile.sh ：

This script creates the ~/Library/MobileDevice/Provisioning Profiles directory and then base64-decodes provisioning profile data from the PROVISIONING_PROFILE_DATA environment variable and into the file profile.mobileprovision.

此脚本创建~/Library/MobileDevice/Provisioning Profiles目录，然后从PROVISIONING_PROFILE_DATA环境变量将base64解码的配置文件数据base64解码到文件profile.mobileprovision 。

Run the following command to mark the scripts as executable:

运行以下命令以将脚本标记为可执行文件：

chmod a+x .github/scripts/*.sh

工作流程 (The Workflow)

Create .github/workflows/deploy.yml:

创建.github/workflows/deploy.yml ：

This workflow is triggered in two ways. It is triggered whenever new commits are pushed to the master branch and whenever a new release tag is pushed to the repository (release tags are, by convention, any tags starting with the letter “v,” as in “v1.2.3”). The initial steps will run regardless of how the workflow is triggered, but the last two steps in the workflow will only be run when the workflow is triggered by a release tag.

该工作流以两种方式触发。 每当将新的提交推送到master分支和将新的release标签推送到存储库时，就会触发该事件(按照惯例，release标签是任何以字母“ v ”开头的标签，如“ v1.2.3 ”)。 无论如何触发工作流，初始步骤都将运行，但是工作流中的最后两个步骤仅在发布标记触发工作流时才运行。

The workflow begins by checking out the same commit of the project as the one that triggered the workflow run.

工作流首先签出与触发工作流运行的项目相同的提交。

Next, the workflow runs our set-env-from-xcodeproj.sh script to set the PRODUCT_NAME environment variable.

接下来，工作流运行我们的set-env-from-xcodeproj.sh脚本来设置PRODUCT_NAME环境变量。

The workflow then runs our import-certificate.sh script and passes in the SIGNING_CERTIFICATE_P12_DATA and SIGNING_CERTIFICATE_PASSWORD secrets to the script as environment variables of the same names.

然后，工作流运行我们的import-certificate.sh脚本，并将SIGNING_CERTIFICATE_P12_DATA和SIGNING_CERTIFICATE_PASSWORD机密作为名称相同的环境变量传递给脚本。

After that, the workflow runs our import-profile.sh script and passes in the PROVISIONING_PROFILE_DATA GitHub secret to the script as an environment variable of the same name.

之后，工作流程将运行我们的import-profile.sh脚本，并将PROVISIONING_PROFILE_DATA GitHub机密作为同名环境变量传递给该脚本。

The workflow then builds the app using the build_app action from the fastlane tool. The fastlane tool comes pre-installed on the GitHub builder hosts. We aren’t using a Fastfile in our project or defining fastlane as a dependency — we’re just taking advantage of the convenience of the action and tool to simplify our workflow. If we wanted more control, we could replace this simple command with complex invocations of xcodebuild archive and xcodebuild -exportArchive. But for our purposes, using fastlane is much easier.

然后，工作流使用fastlane工具中的build_app操作构建应用程序。 fastlane工具预先安装在GitHub构建器主机上。 我们不在项目中使用Fastfile或将 fastlane 定义 为依赖项 -我们只是在利用操作和工具的便利性来简化工作流程。 如果需要更多控制，可以用xcodebuild archive和xcodebuild -exportArchive复杂调用替换此简单命令。 但是出于我们的目的，使用fastlane要容易得多。

Next, the workflow uploads the build logs as a GitHub Actions artifact. The logs might be useful for diagnosing a failed build. By saving them as an artifact, they remain available for download after the job completes.

接下来，工作流将构建日志作为GitHub Actions工件上传。 日志可能对诊断构建失败很有用。 通过将它们另存为工件，它们在作业完成后仍然可以下载。

There are two final release steps that the workflow executes if the workflow was triggered by a release tag.

如果工作流由发布标签触发，则工作流将执行两个最终发布步骤。

First, the workflow uploads the iOS App Store package (ipa) and debugging symbols (dSYMs) that were output by the build step as GitHub release assets. The GITHUB_TOKEN secret is passed to the script as an environment variable. While preserving these assets isn’t strictly necessary, they might come in handy someday. The ipa might be useful if the automated upload to App Store Connect fails and you need to retry manually. The dSYMs might be useful if you ever want to symbolicate a user crash report.

首先，工作流上传iOS App Store软件包( ipa )和调试符号( dSYMs )，它们是在构建步骤中作为GitHub发布资产输出的。 GITHUB_TOKEN秘密作为环境变量传递到脚本。 尽管严格地保留这些资产不是必需的，但是有一天它们可能会派上用场。 如果自动上传到App Store Connect失败并且需要手动重试，则ipa可能有用。 如果您想用符号表示用户崩溃报告，则dSYMs可能很有用。

Then, the workflow uploads the ipa to App Store Connect. Once the app has been uploaded successfully, it will be available for use with TestFlight and submission to the App Store. The APP_STORE_CONNECT_USERNAME and APP_STORE_CONNECT_PASSWORD secrets are passed to the script as environment variables of the same names.

然后，工作流将ipa上传到App Store Connect。 成功上传应用程序后，即可将其与TestFlight一起使用并提交到App Store。 APP_STORE_CONNECT_USERNAME和APP_STORE_CONNECT_PASSWORD机密作为具有相同名称的环境变量传递到脚本。

The final two release steps depend on the PRODUCT_NAME environment variable that we set earlier in the workflow from the project’s build settings. By using this pattern, we avoid hard-coding any details about the project into the workflow and ensure that the same workflow can be used across multiple project repositories.

最后两个发布步骤取决于我们之前在工作流中通过项目的构建设置设置的PRODUCT_NAME环境变量。 通过使用此模式，我们避免将有关项目的任何详细信息硬编码到工作流中，并确保可以在多个项目存储库中使用同一工作流。

Commit the scripts and the workflow and push them to GitHub, then go to the “Actions” tab of your repository to see the workflow running.

提交脚本和工作流程并将其推送到GitHub，然后转到存储库的“操作”选项卡以查看工作流程正在运行。

下一步 (Next Steps)

With this workflow installed, any time you push new commits to your project’s GitHub repository, you should see your workflow run and you can verify that your project builds successfully before tagging the commit for release.

安装此工作流程后，每当您将新提交推送到项目的GitHub存储库时，您都应该看到工作流程正在运行，并且可以在标记提交以供发布之前验证项目是否成功构建。

If your project includes tests, then you might want to consider adding an additional step to the workflow (before the “Build app” step) that runs your project tests and returns an error if any of them fail. Adding a testing step will give you additional feedback after each push and will prevent you from accidentally releasing a build that fails any tests. For example, you could add a step that runs fastlane run run_tests.

如果您的项目包含测试，则您可能需要考虑在工作流程中添加一个附加步骤(在“构建应用程序”步骤之前)，以运行您的项目测试并在其中任何一个失败的情况下返回错误。 添加测试步骤将在每次推送后为您提供其他反馈，并防止您意外发布无法通过任何测试的内部版本。 例如，您可以添加一个运行fastlane run run_tests的步骤。

This concludes the tutorial. I hope you learned something. Happy coding!

本教程到此结束。 我希望你学到了一些东西。 编码愉快！