feat: Support multiple SSH private keys in Picasso reusable workflow

[magajh]

Context

Until now, Picasso only supported a single SSH_PRIVATE_KEY secret to authenticate against private repositories during the build process.

This works well when only one private repository is involved. However, in real-world use cases we increasingly need to:

• Clone multiple private repositories
• Install private Python packages from private Git repos
• Use multiple deploy keys, each scoped to a different repository

Since GitHub deploy keys are repository-scoped, a single SSH key is not sufficient in these scenarios.

This PR extends Picasso to support multiple SSH private keys in a clean and backwards-compatible way.

---

What was implemented

We introduced support for a new optional secret:

• SSH_PRIVATE_KEYS (multiline)

This secret can contain one or more SSH private keys concatenated together:

-----BEGIN OPENSSH PRIVATE KEY-----
(key 1)
-----END OPENSSH PRIVATE KEY-----
-----BEGIN OPENSSH PRIVATE KEY-----
(key 2)
-----END OPENSSH PRIVATE KEY-----

Picasso now:

• Supports both SSH_PRIVATE_KEY (legacy, single key)
• Supports SSH_PRIVATE_KEYS (multiple keys)
• Loads both if provided
• Only initializes the SSH agent when at least one key is present

This change is fully backwards compatible.

---

Why this approach

Multiple alternatives were evaluated before deciding on this design.

Alternative considered: fixed number of keys (e.g., 5 slots)

One option was to:

• Define multiple secrets in the reusable workflow interface:

  • SSH_PRIVATE_KEY_1
  • SSH_PRIVATE_KEY_2
  • ...
  • SSH_PRIVATE_KEY_5

• Concatenate them internally.

Pros:

• Explicit
• No multiline secret required

Cons:

• Arbitrary limit (5? 10?)
• Expands the public API surface of the reusable workflow
• Forces us to maintain a fixed maximum
• Less flexible long-term

---

Alternative considered: dynamically passing secret names

Another idea was to:

• Allow the caller to pass a list of secret names
• Dynamically resolve those secret names inside the reusable workflow

However, reusable workflows have important constraints:

• Secrets must be declared explicitly in workflow_call.secrets or passed via secrets: inherit
• There is no true support for iterating over secrets dynamically
• There is no native looping construct in GitHub Actions YAML
• It is not straightforward to dynamically resolve an arbitrary number of secrets by name when their count is unknown

While GitHub supports some indexed secret access patterns, building a fully dynamic, unbounded secret resolution mechanism inside a reusable workflow becomes complex, and harder to maintain.

In particular:

• We would still need to define an upper bound (N keys)
• Or introduce complex intermediate scripting logic

---

Why the multiline secret is the cleanest solution

The chosen approach:

• Introduces a single additional secret: SSH_PRIVATE_KEYS
• Allows an arbitrary number of SSH private keys
• Has no limits
• Keeps the YAML logic minimal and predictable
• Maintains full backwards compatibility

---

Important note about deploy keys

When using GitHub deploy keys, each key should include the repository SSH URL in its comment:

ssh-keygen -t ed25519 -C "git@github.com:owner/repository.git"

This allows webfactory/ssh-agent to correctly associate keys with repositories and avoid authentication failures when multiple deploy keys are loaded.

This has been documented in the README update included in this PR.

---

Impact

• Backwards compatible
• No breaking changes
• Enables cloning/installing from multiple private repositories
• Improves flexibility for more complex build scenarios

This is a minor version feature addition.

[Gi-ron]

LGTM!