Adopt a8c-secrets for the demo app secrets

[mokagio]

See https://linear.app/a8c/issue/AINFRA-1549

Switches from .configure to a8c-secrets, building on top of what already established in terms of extracting outside the repo in #822.

In doing so, changes how the secrets decrypt build phase works a little bit. The rationale for the change came from @AliSoftware's comments in Automattic/pocket-casts-ios#4731, in particular the one about bypassing fastlane.

Here's what I propose:

• The build phase is the central hub for secrets decryption, which works especially well in project like this one or Pocket Casts where the only secrets left are app-specific. So, it makes sense for the app build to call a8c-secrets decrypt to acquire the secrets it needs.
• For open source apps, the process should allow external contributors to provide their own credentials. That is, not having access to a8c-secrets should not prevent building the app¹

The build phase flow is:

• If a8c-secrets available, assume internal contributor
  • Attempt to decrypt and copy to Derived Data, fail loudly if something doesn't work
• Else, if the external secrets exist, assume external contributor²
  • Copy to Derived Data
• Else, print high level³ instructions for both internal and external contributors

Footnotes

1. We might want to refine the external contributor flow to "can build with placeholder credentials," meaning, an external contributor should only need to provide the credentials that are absolutely required for the app to work. Example: A valid Sentry DSN is not necessary because crash logging should not be a requirement for external contributors. The demo app here does not use Sentry, but the point stands. ↩

2. Alternative: Have a more generic "local override" file instead of an explicit "external" one and have local take precedence, maybe with an echo "warning: Using local secrets override..." message. This would allow internal devs to override secrets if needed without having to jump through hoops to ignored a8c-secrets. I'm not sure how likely that scenario is on a day to day basis, though, so not sure if it's worth implementing with the risk of local secrets remaining in use unintentionally given how a warning is easy to miss. On top of that, we want secrets to stay outside the repository, but adding a prioritized mechanism for internal contributors to track secrets in the repo seems like it would open a bigger door for possible leakages than what "you need to work around a8c-secrets to make this happen" does. ↩

3. High level instructions instead of specific commands such as "run a8c-secrets keys import followed by a8c-secrets decrypt" to avoid the instructions drifting from the tool's API. Sending users to the tool's README keeps it as the single source of truth. ↩

[Copilot]

Pull request overview

This PR migrates the demo app’s secret materialization workflow from the legacy .configure/configure_apply flow to a8c-secrets, so internal contributors decrypt secrets via a8c-secrets while external contributors continue using the templated, gitignored secrets file.

Changes:

• Replace the build-phase secrets source with a8c-secrets which + versioned .a8c-secrets/Secrets.swift.age tracking, and avoid rewriting the derived Secrets.swift when content is unchanged.
• Update contributor-facing documentation and Makefile targets to use a8c-secrets.
• Remove the legacy .configure setup and encrypted artifact, and add repo metadata/public keys for a8c-secrets.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Sources/GravatarUI/GravatarUI.docc/GettingStarted.md	Updates internal contributor setup instructions to use a8c-secrets.
Scripts/build-phases/generate-secrets.xcfilelist	Tracks the versioned .age input so Xcode reruns the phase when secrets rotate.
Scripts/build-phases/generate-secrets.sh	Uses a8c-secrets which as primary source; adds “copy only if changed” behavior.
Makefile	Updates setup-secrets to run a8c-secrets decrypt.
Demo/Demo/Generated/README.md	Updates explanation of how Secrets.swift is generated for the demo target.
.gitattributes	Marks *.age as binary for Git attributes handling.
.configure-files/Secrets.swift.enc	Removes legacy encrypted secrets artifact.
.configure	Removes legacy .configure configuration file.
.a8c-secrets/Secrets.swift.age	Adds the versioned encrypted secrets source for a8c-secrets.
.a8c-secrets/repo-id	Adds a8c-secrets repo identifier metadata.
.a8c-secrets/keys.pub	Adds public recipient keys used for age encryption (dev/ci).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mokagio]

Note

Blocked: this PR is waiting on Automattic/a8c-ci-toolkit-buildkite-plugin#218 (and the stacked #220) to merge and ship in a toolkit release.

The Build Demo job currently fails with make: a8c-secrets: No such file or directory — A8C_SECRETS_IDENTITY is provisioned on the agent, but the binary is not installed. Rather than add a raw curl | bash bootstrap here (flagged as a supply-chain risk on pocket-casts-ios#4731), this repo will call the toolkit’s checksum-verified install_a8c_secrets once it is released, and bump CI_TOOLKIT in .buildkite/shared-pipeline-vars accordingly.

Posted by Claude Code (Opus 4.8) on behalf of @mokagio with approval.

---

Update: This has now been addressed.

[wpmobilebot]

📲 You can test the changes from this Pull Request in Gravatar Prototype Build by scanning the QR code below to install the corresponding build.

	App Name	Gravatar Prototype Build
	Build Number	2548
	Version	PR #824
	Bundle ID	com.automattic.gravatar-sdk-demo-uikit.prototype-build
	Commit	8105a96
	Installation URL	53l6gfu0gq0c8

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[mokagio]

@AliSoftware @iangmaia I'd appreciate your thoughts on this. Having basically built it from scratch (only previous iteration #821) I think it's a good place where to iron out how to best integrate a8c-secret via Xcode build phase. And given we have to run build phase because we need to decrypt the Swift secrets in the derived data folder, we might as well centralize in there as much as possible.

Thanks!

[mokagio]

This was not needed for CI builds, but it was on my machine. Of course, I double checked that I could run a8c-secrets decrypt successfully on my system.

[AliSoftware]

Alternative: Have a more generic "local override" file instead […] I'm not sure how likely that scenario is on a day to day basis, though, so not sure if it's worth implementing with the risk of local secrets remaining in use unintentionally given how a warning is easy to miss. On top of that, we want secrets to stay outside the repository, but adding a prioritized mechanism for internal contributors to track secrets in the repo seems like it would open a bigger door for possible leakages than what "you need to work around a8c-secrets to make this happen" does.

100% agree with the "cons" here. I think it's not worth it and also makes it too easy to do things wrong (local secrets, etc) so better avoid this.

[AliSoftware]

Left a suggestion to make the script more scalable from when we'll start adopting it in more repos. But not a blocker for this repo in particular.

[AliSoftware]

Thinking of scaling (especially when we'll be ready to adopt this technique for more repos): I wonder what would be the best way to handle multiple secret files.

1. Maybe we should write this code as a bash array + for loop, even if in the case of Gravatar-SDK-iOS there will be only one item, just so it's scalable
2. An alternative to hardcoding the list of files to decrypt could be to iterate of all the files in the directory returned by a8c-secrets which, i.e. all the decrypted files. But I don't think that'd be a good idea, because that could risk copying files that are there but we don't need in the Xcode project, and thus copying too much. So I think hardcoding the list of files in the generate-secrets.sh script is still the right move, even if that means that we'll need to keep this script in sync every time we might need to add a new secret file to the Xcode project. But we'll need to add said secret file to the .xcodeproj anyway too, so I think that's fine.

So something like this, maybe? (not tested)

SECRETS_FILES_NAMES=(Secrets.swift)
if command -v a8c-secrets >/dev/null 2>&1; then
  a8c-secrets decrypt --non-interactive >/dev/null \ || { echo "error: …"; exit 1; }

  for secret_file_name in "${SECRETS_FILES_NAMES[@]}" do
    secret_file=$(a8c-secrets which "${secret_file_name}") \ || { echo "error: …"; exit 1; }
    apply "${secret_file}"
  done
else
  for secret_file_name in "${SECRETS_FILES_NAMES[@]}" do
    basename = "${secret_file_name%.*}"
    extension = "${secret_file_name##*.}"
    external = ${SRCROOT}/Demo/${basename}.external-contributor.${extension}"
    if [ -f "$external" ]; then
      apply "${external}"
    else
      template = ${SRCROOT}/Demo/${basename}.template.${extension}"
      echo "error: No secret found for file '${secret_file_name}'. Internal contributors: install a8c-secrets and follow its setup instructions; see https://github.com/Automattic/a8c-secrets. External contributors: copy '${template}' to '${external}' and fill in your own credentials."
      exit 1
    fi
  done
fi

[mokagio]

Thinking of scaling (especially when we'll be ready to adopt this technique for more repos): I wonder what would be the best way to handle multiple secret files.

Good point. What do you think of passing the file names as arguments? That would allow us to have a single version of the script to either copy paste (i.e. keep in sync with the help of AI) or embed in a8c-secrets as a command. However, if we were to make it part of a8c-secrets we'd also need to both harden and make optional the external contributors worflow.

Regardless, using an array would definitely be a flexibility improvement. I'll keep it in mind through the adoption for when I'll run into a repo with more than one build-time secret to decrypt.

[AliSoftware]

Yep I like it. In fact, adding a dedicated a8c-secrets xcode-script-build-phase subcommand or the like to a8c-secrets — to DRY the logic of whatever script we end up using once we refined and set this up across our repos to find the best common denominator and logic that works well for all projects — was already in my list of ideas for the next stage of the project.

We're not totally there yet, but having the script be closer to being generic enough to become a single version of the script we can copy paste is definitively gonna get us closer to this 👍

[AliSoftware]

I was surprised to see the Serets.swift.age file in this PR be in clear and was about to suggest we add exactly that… but I see that you covered this already; so I'm guessing it will not be taken into account by GitHub until after this is merged into trunk 🙃

[mokagio]

That's the conclusion I came to as well...

[AliSoftware]

Doubly strange: If I look at Secrets.swift.age now that the PR has been merged:

• Not only does GitHub not show it as "This file is binary" despite this line in the .gitattributes
• But also it shows its content as looking like Japanese text… while the binary content of the .age file is definitively not looking like that (even if it were misinterpreted with the wrong text encoding).
  • In fact, the .age file format specification shows that .age files start with a plain ASCII text header (age-encryption.org/v1 as its first line, then a mix of plain text + Base64 data) before its actually-binary payload post-header.
  • So it's a mystery how even those first bytes of the file, which end up being regular ASCII text, end up making GitHub interpret those as Japanese characters… 🤷