[FEATURE] Private skill and plugin sources in the v1alpha3 API #2815

📋 Prerequisites

• I have searched the existing issues to avoid creating a duplicate
• By submitting this issue, you agree to follow our Code of Conduct

📝 Feature Summary

Support private git, OCI and S3 artifact sources for AgentTemplate skills and plugins, as v1alpha2 does today.

❓ Problem Statement / Motivation

• The released v1alpha2 API supports private skill sources. skills.gitAuthSecretRef takes a Secret with a token key for HTTPS or ssh-privatekey for SSH, skills.imagePullSecrets covers OCI, and S3 reads AWS credentials from the init container environment (go/api/v1alpha2/agent_types.go:140-166, as of v0.10.1).
• The v1alpha3 API on main has no equivalent. ArtifactSource carries only oci, git, bucket and path (go/api/v1alpha3/agenttemplate_types.go:161), and the runtime fetches with no credential at all (go/core/pkg/agentplugins/materialize.go:174-227). Every private source fails.
• The implementation still exists and has no caller. skillsinit.Run, SetupGitAuth and MergeDockerConfigs were orphaned by 059c01b (refactor: simplify runtime images and add lifecycle e2e #2498), which deleted the only caller. feat: load Agent Plugins in Go runtime #2500 re-used the fetch primitives and not the auth setup, and neither commit message mentions it.
• Anyone moving from v1alpha2 to v1alpha3 with a private skill repository loses a working feature. No released tag contains 059c01b, so this can be settled before v1alpha3 ships.
• The only workaround is a long-lived token in harness.spec.env. That is resolved to a plaintext literal before the Substrate boundary, because ate-api EnvVar accepts literals only, and it is then readable by every process in the sandbox.

💡 Proposed Solution

• Add an auth field to ArtifactSource, referencing Secrets in the same namespace, covering the git, OCI and S3 cases that v1alpha2 already covers.
• Fetch in the controller rather than in the runtime, and give the runtime the materialized content as a read-only volume. The sandbox then needs no credential and no egress, which also removes the startup fetch that blocks readiness in [BUG] Git, OCI, and S3 Agent Plugin resources cannot be materialized while creating Substrate golden Actors #2604.
• No Substrate change is required for this. Worth knowing early: ImageVolumeSource pulls anonymously for every registry except gcr.io and pkg.dev, and accepts only runnable image manifests, so a first version targets a bundle registry that allows anonymous pull. An in-cluster registry reachable only by nodes satisfies that and keeps the content private. The same limit applies to Harness.spec.workload.image, because a single image cache with a single GCP-only authenticator serves both container images and image volumes (cmd/atelet/main.go:206 and cmd/atelet/oci.go:113 in agent-substrate/substrate), so this is an environment constraint rather than a property of the proposal. It goes away when upstream Add OpenTelemetry Tracing Support for BYO LangGraph Agents #917, [BUG] Streaming chat shows "no visible reply" for a long time; later cancels and backend logs cleanup warnings #869 or feat: use controller name env var: #1078 lands.

I have a fuller design worked out, including how the content is packaged, how the revision digest stays free of credential material, and how rotation behaves. I left it out here to keep the discussion on the requirement first. Happy to write it up if the direction is agreeable.

🔄 Alternatives Considered

• Restore the v1alpha2 behaviour by reviving SetupGitAuth and mounting the credential into the runtime. Smallest change, but the credential then sits inside a sandbox that runs model-generated code.
• Substrate egress credential injection. It cannot sign AWS SigV4, so S3 stays out of reach, and the hostname rules cannot express the OCI token exchange.
• A short-lived credential fetched by the runtime. The sandboxed process cannot authenticate today, since MintJWT requires authenticating as the pod that runs the actor and there is no per-actor service account.
• Bake skills into the harness image. Works today, but it couples skill selection to the image lifecycle.

🎯 Affected Service(s)

Multiple services / System-wide

📚 Additional Context

Related: #2604, a network-backed source blocks readiness. #2608 and #2646 report bugs in the skillsinit paths that no longer have a caller on main, which is the same regression seen from the released side.

🙋 Are you willing to contribute?

• I am willing to submit a PR for this feature