Improved documentation (and potentially tooling) around iOS/Android deployment

[lazerwalker]

Hi!

I've noticed that a disproportionate amount of questions in the Discord are centered around setting up mobile deployment. Both the current GameCI deployment docs and Fastlane's own documentation assume strong familiarity with the iOS and Android codesigning and build processes, moreso than e.g. what the unity-builder docs assume about the Unity build pipeline. A lot of game devs hoping to deploy their GameCI-powered builds to iOS and Android don't have that familiarity. Bridging that knowledge gap could do a lot to reduce dev confusion, and I'd love to help with that.

On a basic level, I think it makes sense to revamp the GameCI mobile deployment docs (iOS and Android on both GitHub and GitLab) to provide a more explicit introduction to Fastlane, walking through how to set it up for a given platform in more detail than the docs currently do. I'm happy to take a stab at a draft of this, provided there's interest.

Additionally, I have a proof-of-concept project (https://github.com/lazerwalker/boatattack) that uses GH Actions to completely manage the iOS codesigning process, including doing initial certificate generation on a Mac runner without requiring manually operating a physical Mac. I'm in the process of adapting this to something more composable, most likely a set of Actions to generate codesigning certificates and store them in a git repo via match, build and codesign an iOS or Android project generated by Unity, and upload builds to TestFlight/App Store/Google Play. These would be mostly pre-configured "it just works" actions with a few configuration points, with additional direct access to the underlying code so people who want to fork and more heavily customize can do so beyond what you would expect from Actions parameters.

In short, this work aims to abstract away knowledge of Fastlane for happy-path scenarios, the same way the unity-builder action does for Unity's command-line interface.

I'm wondering if this is something that might potentially be worth including as "part of GameCI" (hosting the Actions in the GameCI GH org, and hosting docs on the main site). Technically, this isn't Unity specific, it's just a set of wrappers around Fastlane. But providing this tooling will be particularly valuable to game devs without iOS/Android native dev experience, and I think there's a great deal of discoverability value in having it live under the GameCI branding umbrella instead of off to the side.

So, I really have two questions:

1. If I were to put together a draft of updated deploy docs that were more targeted at folks unfamiliar with the iOS/Android codesigning processes or Fastlane, would that be welcome?
2. Is there tentatively interest in those mobile codesigning- and deployment-focused Actions? I'm obviously not expecting a firm answer when I can't yet point to concrete code, and there are questions around future maintenance plans, etc, but it would be good to get a general sense if this is something people think would even remotely be a fit for the GameCI org. Especially since any updates to the existing deployment docs would likely differ based on whether or not we have a more streamlined workflow to recommend to newcomers.

Let me know your thoughts!

[GabLeRoux]

Providing a new action would be a new point of maintenance which I am unsure of the implications right now. We sure can improve the documentation for iOS and Android deployment for both github and gitlab.

A quick win imho would be to point to actual getting started guides so we don't assume the users have knowledge of the tools being used anymore.

At some point, it's hard to create an action that fits all needs and technically speaking, we are already using an actual action to do fastlane things so I'm not exactly sure what the action would be doing. It's all about finding the right abstraction level.

We usually aim to provide examples for the simple happy paths and use existing tools with enough customization so it can fit most needs. I wish we could actually use github actions within gitlab (is it a thing? I don't know) as it would definitely reduce the amount of duplication we have and improve our parity between the services.

On the gitlab side of things, right now, it's just a bunch of shell scripts where users are invited to edit if needed and there is a csharp build script where people are invited to copy into their project (there are quite a few better ways).

All project usually have their small differences which makes all of this a bit hard to streamline (ex; android and iOS often have different bundle identifiers, ios requires storage of certificates and a repo with fastlane and not everyone stores it the same way, keystores and singing with android is not always done on Google Play side, etc.)

Now if a new action would simplify things for most cases, I do agree it would be interesting. Concerning gitlab, I don't exactly know what we should do.

[lazerwalker]

Re: linking to a getting started guide, I think what's tricky is the Fastlane documentation is (reasonably and correctly!) speaking to an audience of iOS and Android devs, which is an assumption we can't make. I'm proposing that I take a stab at a new "getting started" guide that assumes a Unity dev with no knowledge of Xcode or Android Studio.

I have answers to a lot of those (legitimately hard, important, and open-ended!) questions about how I think a set of happy path Fastlane actions would work, what can and can't be streamlined, and what the correct abstraction level is. But it seems to me like we're already at a point where me showing off working actions would be infinitely more productive than going back-and-forth here😅. Will loop back later on that when I have more to show.

[webbertakken]

To go forth, just once more, I'd like to express a slightly more supportive point of view;

On a basic level, I think it makes sense to revamp the GameCI mobile deployment docs (iOS and Android on both GitHub and GitLab) to provide a more explicit introduction to Fastlane, walking through how to set it up for a given platform in more detail than the docs currently do. I'm happy to take a stab at a draft of this, provided there's interest.

I think this is a very insightful idea. Making a slightly more rounded story that will get people from having a project to deploying a signed application, is most likely something many of our users are looking for.

@GabLeRoux makes a good point about that sometimes it's hard to sync GitLab pieces with our GitHub Actions (GHA) pieces. Therefor perhaps we should start by keeping this initiative completely scoped to GitHub Actions side of things. As GHA becomes bigger and GitLab is still evolving, perhaps reusing large parts of the actions (and maybe then also rationale, docs, etc) will become a thing in the future. And if so, every iteration we've made in GHA will likely be of some value.

If I were to put together a draft of updated deploy docs that were more targeted at folks unfamiliar with the iOS/Android codesigning processes or Fastlane, would that be welcome?

Personally I think that would be amazing.

I'm in the process of adapting this to something more composable, most likely a set of Actions to generate codesigning certificates and store them in a git repo via match, build and codesign an iOS or Android project generated by Unity, and upload builds to TestFlight/App Store/Google Play. These would be mostly pre-configured "it just works" actions with a few configuration points, ...

Again an excellent idea.

As for whether to host it inside the GameCI ecosystem: as the described use case is mostly concerning game developers who don't already have knowledge of each individual platform (unlike app developers who usually do), I think it's fair game to host and maintain these actions as part of GameCI, at least as a first iteration and based on the domain knowledge that we have.

As the community grows we have seen more and more support keeping the documentation and actions up-to-date. I see no reason why that wouldn't pollinate towards other actions if we were to house them.

Also note these efforts (including having control over the source code of proposed actions) could aid us when building so called composite actions, that we've been talking about creating in the future.

In conclusion I'd argue that we'd be very open to contributions on all proposed points (perhaps given that we keep all changes scoped to GitHub Actions side for now). Unless other core contributors think otherwise? cc: @GabLeRoux @davidmfinol @frostebite

[GabLeRoux]

I agree with Webber 💯. My point was indeed that it would be harder to do this with gitlab. That should not prevent us from going forward with Github Actions and making it easier for main use cases 👍

[davidmfinol]

I agree, and I'd add that a GitHub Action that manages deployments to the App Store and/or Google Play would be very useful even for developers who are familiar with xcode + fastane + the Android build pipeline.

I know a pain point for me is that iOS certificates are forced to expire once a year, and if we're able to have a GitHub Action that helps manage those certificates so that I wouldn't have to take manual action every year, I'd update my workflow to use that Action. And I'm sure I wouldn't be the only one.

[pietroF42]

@lazerwalker Any news on the updated deploy docs?

[lazerwalker]

I have a draft of iOS deploy docs almost ready to open a PR, but looking over the existing recommended Fastfile and Actions workflows is going to take some time to see if any changes are needed/recommended.

[pietroF42]

Amazing! I am quite keen to have a look, maybe the two sections can be split into two tasks/PRs? 🙃

[lazerwalker]

Forgot to tag this, but Android docs are #256.

My next immediate work is taking my work to automate generating iOS codesigning certificates and Match configuration and shrink that from two workflows to one (https://github.com/lazerwalker/BoatAttack/blob/master/.github/workflows/ios_setup.yml and https://github.com/lazerwalker/BoatAttack/blob/master/.github/workflows/generate_certs.yml, the latter has comments explaining why this is counterintuitively difficult). My current plan of attack is to do that work, and then reassess if it makes sense to produce an Action that does that work or merely update the iOS deployment documentation to include the contents of that workflow file.

That second bit will probably coincide with trying to think a bit more seriously about "okay, do premade Actions for uploading iOS/Android builds actually make sense, or does the time saved for beginner users vs cost of maintenance not quite make sense?"

[lazerwalker]

Cool, to just keep updating in here, I took a stab at combining those two workflows into one, and the act of doing it made me realize it's a bad idea. It's totally doable, but combining the two into one workflow means you still need a separate workflow to run once a year (or whatever) in order to regenerate certificates, since the init script fails out if it's already configured (and modifying that behavior would be doable, but probably inadvisable for a number of reasons).

At this point, I strongly suspect my one remaining action item is taking my two initialization workflows as-is (one that configures a Match repo, one that generates certs) and adding a section or two to the iOS deployment docs that includes those workflow files and explains how to use them.

[davidmfinol]

I think we've done a good job of supporting and documenting Android and iOS workflows, so closing this issue.