Do apple-app-site-association files work with GitHub Pages (i.e. site.github.io)?

Nope, I haven't been able to make it work with GitHub Pages alone. If you don't care why you can skip this next bit.

Why GitHub Pages alone can't suffice

As far as I've found out, GitHub Pages alone will not serve up a file at .well-known/apple-app-site-association with Content-Type: application/json. Apple's validation tool wouldn't pass. It requires:

• .well-known/apple-app-site-association to be served (you can test with curl -v mysite.com/.well-known/apple-app-site-association)
• It must be served with a Content-Type: application/json header.
• There cannot be any redirects; i.e. must work without adding -L to your curl command.

Here's the solutions I tried using only GitHub pages that all failed:

1. First thing I figured out was adding .nojekyll to the top directory of the repo so that .well-known/apple-app-site-association could be served.trying to redirect with a symlink apple-app-site-association to apple-app-site-association.json
   • It was still served as Content-Type: octet-stream
2. Creating the directory/file structure .well-known/apple-app-site-association/index.json
   • This fails Apple validation because mydomain.com/.well-known/apple-app-site-association redirects to mydomain.com/.well-known/apple-app-site-association/ before returning the correct content and correct content-type header.

Cloudflare/CDN atop GH Pages Solution

However, I was also using Cloudflare to CDN the static pages my GitHub Pages site hosted. You can set this up at the free level and probably should if your page gets any real traffic. You could pick another CDN probably, but it will need custom routing of some kind that supports the content-type/no-redirect stuff Apple demands. In Cloudflare, I was able to effect this for free (unless I got a ton of traffic) with the free tier of their Workers. You can probably adapt the rest of this to your preferred CDN if you use another atop your GitHub Pages site.

From the "Workers" page on Cloudflare, click "Manage Workers" then "Create Worker." Copy/paste and the following JSON as needed (it contains your apple-app-site-association JSON):

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

/**
 * Respond to the request
 * @param {Request} request
 */
async function handleRequest(request) {
  return new Response(JSON.stringify(
  // This is actually your JSON. Because this is JavaScript, you can also add in comments if you like.
{
  "applinks": {
    "details": [
      {
         "appID": "Q94XRK95RT.io.beatscratch.beatscratchFlutterRedux",
         "paths": [ "/app/", "/app"]
      }
    ]
   }
}) + "\n"
, {
  headers: {
      "content-type": "application/json",
    },
  status: 200
  })
}

Note that I had to use the JSON structure from here. This got the above-linked validator to display "Error no apps associated with url" which sounds bad... but things work.

I named the Worker apple-app-site-association but you can name it whatever you like. You can then route my-site.com/.well-known/apple-app-site-association to the Worker.

Looks like once the app has been uploaded and installed via TestFlight strong passwords and the association file is accessed.

It works!

As of 2021 this currently works for me with a custom Github Pages domain even though:

• github pages does not serve apple-app-site-association with the correct json content-type -- it's octet-stream instead of application/json.
• the apple validation tool fails the universal link test

If you redirect from the apex domain to www then you'll probably need to specify the full www.yourdomain.com in your app config, not yourdomain.com.

Make sure this returns the file.

curl -v '<the_domain>/.well-known/apple-app-site-association'

You need to add the _config.yml file to the root of your GitHub page, then the <domain>/.well-known/apple-app-site-association can be accessed properly.

// _config.yml
include: [".well-known"]