Xcode and Binary File Authentication

Configuring Xcode to be able to access your published XCFrameworks is often confusing. That is because Xcode, and really SPM, use different methods to access the git repo config info and the XCFramework binary zip file.

This is critical to understand. Just because you’ve authenticated to GitHub (or others) through Xcode does not mean you can access your binary XCFramework files. Xcode grabs config from a git repo, but then it also needs to grab the binary, and it will not use the same authentication to do so.

Repo Access

SPM packages are generally added through Xcode’s GUI. Open File > Add Packages in Xcode and search for the repo with your library. If it is private, you’ll need to authenticate through Xcode to get access. See the SPM docs for more details.

Binary Access

If the binaries are stored in a private server, you’ll need to configure auth access to them. Again, as mentioned in many places, the binary file access authentication is separate from the Xcode git repo authentication. Also, specifically with GitHub, even if your repo is public, you still need to authenticate to download binaries, though the following config.

You can authenticate to download binaries with a local ~/.netrc file or Mac Keychain Access. We generally use ~/.netrc.

Open or create ~/.netrc. This file tells curl and other tools how to authenticate to different servers. You’ll need the server’s address, and your login information.

The server on which you host your files must have a basic authentication option. Services like Amazon S3 and Google Cloud Storage do not provide this. To store your binaries on a service like these, you’ll need to create your own authentication server, or find a provider that handles this for you.

machine files.example.com
  login <user>
  password <pass>

GitHub is commonly where we store files. It is a bit of a special case for multiple reasons. First, even if your repo is public, you still need to add auth for binaries. Second, the servers are different depending on if you use GitHub Releases or GitHub Packages.

For GitHub Packages, you’ll need your GitHub username and a Personal Access Token that can read repo and read packages.

machine maven.pkg.github.com
  login <Github User>
  password <PAT>

For GitHub Releases, the username and PAT are the same, but the server is different:

machine api.github.com
  login <Github User>
  password <PAT>

SPM Error

If you are adding an SPM dependency and can access the repo but the download fails, it is almost certainly because of an error with access config. The error screen will look like the following:

Failed SPM Binary

You’ll need to fix ~/.netrc then attempt to add the package again. You should not click “Add Anyway”.