How to Auto-Archive Xcode Cloud Build Artifacts: 2026 Guide

Apple says Xcode Cloud build information and artifacts can be accessed for up to 30 days. That makes the safe choice clear: download the files we need after the build, verify them, and store them under our team’s retention and access rules. Use Xcode or App Store Connect for occasional, reviewed exports; use the App Store Connect API when retrieval needs to be repeatable. Never treat an API response’s download address as a permanent link.

This runbook is for small teams that need to reproduce a past failure or preserve test evidence. It also helps CI engineers who need a dependable record of what a build produced.

Start by deciding what the archive must prove

Not every build needs every file saved. Choose retention based on the question the archive should answer later: what was released, why a test failed, or which symbols are needed to investigate a crash.

Xcode Cloud can provide build reports and logs, app archives or other build products, debug symbols, and test results. The exact artifacts depend on the workflow and build action. Apple’s Xcode Cloud setup and archiving guidance describes the available outputs and ways to download them.

Use these distinctions when setting the scope:

Release traceability: Keep the app archive or distributable output that the release process needs, along with the build identifier and source revision. Keep only the files needed to establish what was shipped.
Crash investigation: Retain relevant symbol files with enough build context to identify the matching binary. A symbol file without a reliable link to its build is difficult to use later.
Test reproduction: Save test results and the related build logs when a failure may need investigation. Results alone may not explain the environment or sequence that led to a failure.
Routine successful builds: Avoid archiving every available file by default. Unnecessary copies create storage, access-control, and cleanup work without necessarily improving traceability.

The archive should answer a specific operational question. If the team cannot say why a file needs to survive, leave it out of the default retention set and document when an exception applies.

Choose a retrieval path before the next build

Xcode Cloud artifact automation begins with a practical choice: human review or repeatable retrieval.

Manual export fits a low-volume workflow, an exceptional incident, or a release that must be reviewed before files enter long-term storage. A person can inspect the build report and select only the required outputs. The tradeoff is dependence on someone noticing the build and completing the export before cloud access expires.
API retrieval fits a recurring archive process. A job can identify the build action, retrieve its artifacts, download the selected files, and record the build context. The tradeoff is operational ownership: the team must maintain API access, protect credentials, handle failures, and verify the downloaded files.
A hybrid process is useful when automated retrieval handles routine outputs but a release owner decides which exceptional logs, test evidence, or symbols merit longer retention.

Keep the selection explicit. The API can expose artifact information, but that does not decide the team’s retention policy or guarantee that every available file is useful to the release process.

What is the Xcode Cloud artifact retention period?

Apple documents that Xcode Cloud build information and artifacts are accessible for up to 30 days. This describes the availability of those items through Xcode Cloud. It is not a recommended retention period for your own archive, nor does it define how long your organization must keep downloaded copies. See Apple’s Xcode Cloud documentation on build artifacts and archiving.

Treat the cloud window as a retrieval deadline, not as a backup strategy. If a build may be needed for an investigation, release audit, or test comparison, export the required artifacts before they are no longer available through the service. Then apply your own retention schedule in the storage system your team controls.

A separate limitation applies to API downloads: the artifact download address returned by the API is valid only for a limited time, as described in Apple’s CI artifact resource documentation. Save the file itself. Do not save the address as a substitute for the file, or build a process that expects the same address to work later.

Retrieve a build manually when review is part of the process

For an occasional export, start from the relevant build in Xcode or App Store Connect. Review the build report and its actions, then download the outputs needed for the archive. Apple documents manual downloads alongside API-based options in its Xcode Cloud configuration guidance.

Before closing the task, record the build identifier, source revision where available, workflow context, and the files saved. Give the archive a location with a clear owner. If a team member is responsible for export, make that responsibility explicit in the release or incident procedure; otherwise, a manual step can be missed without leaving a reliable record.

Manual handling has hidden costs. It can be delayed by handoffs, produce inconsistent folder names, or omit the logs needed to explain a test result. It also depends on access to the relevant account and on the person selecting the correct build. For a recurring workflow, use a written export procedure or move retrieval into an automated job.

How do we download Xcode Cloud artifacts with the App Store Connect API?

The App Store Connect API provides resources for Xcode Cloud workflows and builds. A typical retrieval sequence is to identify the relevant build and action, list the action’s artifacts, inspect the artifact details, then download the file while its address is still valid. Apple’s workflow and build API documentation describes the related resources. The build-action artifacts endpoint lists artifacts associated with an action, and the artifact detail endpoint retrieves an individual artifact resource.

Use the current Apple documentation as the source of truth for endpoint paths, response fields, and relationships. In particular, read the documented artifact attributes to identify the file name, type, and download address rather than assuming that fields or response shapes will remain unchanged. Apple’s CI artifact attributes reference is the source for those properties.

The operational sequence should look like this:

Find the target build using the workflow and build information available to the job.
Identify the build action whose outputs match the retention plan.
Request that action’s artifact resources.
Inspect each relevant artifact’s documented metadata and select the files to retain.
Retrieve the artifact detail needed to obtain its current download information.
Download the file promptly, then record the build and artifact context in the archive.

API access requires authentication. Apple documents how to create App Store Connect API keys and how to generate JWTs for API requests. Follow the current requirements for key creation, authorization, and request signing. Do not copy a private key into a repository, include a signed token in build logs, or send credentials as part of an artifact.

Build the post-completion download job

The API provides a way to retrieve build artifacts; it does not establish that Apple will trigger your archive job at a particular moment. Connect retrieval to the event or process your team already uses to detect a completed build, and make the job resilient to a build that is not yet ready for retrieval.

Use this implementation sequence:

Choose the trigger. Connect the archive job to your existing build-completion handling or a controlled polling process. Record how the team determines that a build is ready. Do not assume a trigger guarantee that Apple has not documented.
Load credentials securely. Keep the API key and signing material in your approved secrets manager or protected CI settings. Limit who and what can read them. Use the authorization model documented by Apple rather than embedding credentials in scripts or shell history.
Resolve the build and action. Use the workflow and build resources to find the build being processed, then inspect its actions. Keep the identifiers from the response so later requests refer to the same build.
Enumerate and filter artifacts. Request the artifacts for the selected action. Compare their documented metadata with the retention plan. Record which outputs were selected and why.
Download immediately. Use the current address returned for the artifact while it is valid. Handle failed requests as failures; do not silently mark the archive complete because the metadata request succeeded.
Write a manifest. Save the build identifier, action context, source revision when available, artifact names and types, retrieval time, and download outcome alongside the files. This makes later searches less dependent on remembering how a directory was named.
Report completion. Expose a clear success or failure result to the team’s normal CI monitoring. A failed archive should remain visible for follow-up rather than disappearing in a log that is later discarded.

Keep retries bounded by the availability of the artifact address and your service’s current API rules. When a download fails, obtain fresh artifact information as appropriate instead of retrying an old address indefinitely. The exact error handling and backoff depend on your API client and CI environment; test them against the current Apple API behavior.

How should Xcode Cloud logs and test results be saved?

Logs and test results should be saved with enough build context to make them useful later. Put related files in one archive unit or connect them through a manifest. Include the build and action identifiers, workflow context, source revision when available, and a short reason for keeping the output.

Do not assume that a test result file alone will explain a failure. Preserve the corresponding build logs when they are needed to understand the build or test action. Similarly, retain symbols only when your support or crash-investigation process needs them, and associate them with the binary they describe.

Keep access narrow. Build logs and artifacts may reveal internal project information. Avoid printing API tokens or private-key material to CI output. Separate the credentials used to retrieve artifacts from the storage credentials used to write the archive, where your infrastructure allows it. That limits the damage if one part of the workflow is exposed.

If an archive must be shared for a specific investigation, use a controlled sharing path and record who can access it. Do not make a whole archive bucket or directory broadly accessible just because one team member needs a file.

Verify every archive before marking the job complete

A successful API response does not prove that the downloaded file is complete, readable, or the intended output. Treat verification as part of the job, not as optional cleanup.

Use this checkable runbook for each new workflow:

[ ] Confirm that the selected build and action match the intended workflow and source revision.
[ ] Confirm that the artifacts selected match the team’s release, debugging, or test-evidence policy.
[ ] Confirm that each download finished successfully and that the local file is non-empty where an empty file would be invalid.
[ ] Open or inspect the file with an appropriate tool for its type; do not rely only on its file name.
[ ] Confirm that logs and test results can be read by the people responsible for later investigation.
[ ] Confirm that the manifest links the stored files to the build and action context.
[ ] Confirm that no credentials, signed tokens, or private-key data appear in the saved logs or manifest.
[ ] Confirm that a failed download is reported and can be retried or escalated before the cloud artifact becomes unavailable.

Use a real project workflow for acceptance. Run a build that produces the kinds of outputs your team intends to retain. Verify the API retrieval path, the manual fallback if one is required, the stored files, and access permissions. Then test retrieval from the archive location rather than assuming that a successful upload means the files can be used.

Set a retention policy the team can operate

Decide how long each class of file should remain in your own storage based on release traceability, incident response, test reproduction, and organizational requirements. Assign a cleanup owner and document how exceptions are handled. Apple’s cloud availability period and your team’s archive policy serve different purposes; one does not automatically define the other.

Keep the policy practical. Logs may need different access rules from release archives. Test evidence may be relevant only for a specific investigation or release process. Symbols need to remain associated with the build they support. State which items are retained, where they are stored, who can access them, and what event permits deletion.

Recheck the process when Apple changes API documentation or artifact behavior, or when the team changes its build workflow. In particular, verify the current authentication requirements, resource fields, and download behavior against Apple’s API documentation for Xcode Cloud workflows and builds. The API response is an implementation detail to validate, not a permanent contract to guess from an old script.

When a Mac environment belongs in the archive workflow

Downloading artifacts through the App Store Connect API does not, by itself, require a separate Mac host. Keep that part in the CI environment that already has secure API access if it can retrieve, store, and verify the files.

A Mac becomes relevant when the workflow also needs macOS tools to inspect, sign, process, or validate project outputs. In that case, compare the existing setup with a Mac environment based on the work it must perform. A non-Mac host may not run required macOS tooling; maintaining a dedicated physical Mac adds hardware ownership and upkeep; a remote Mac adds network and access-control considerations. For short-lived validation or post-processing, a rented Mac can avoid purchasing hardware, while sustained heavy workloads or workflows requiring local physical interfaces may favor a dedicated machine.

If the archive process needs a separate macOS environment, review the available Mac plans and confirm the connection and access details in the metalvnc help center. If retrieval and verification already run reliably on existing infrastructure, adding a Mac would add complexity rather than solve an archive problem.