Skip to content

Allow Agent Plugin authentication with credentials retrieved at runtime #59476

Closed

Description

@ibalboteo

Runtime Agent Plugin Credentials Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Suggested issue title: Allow Agent Plugin authentication with credentials retrieved at runtime

Goal: Allow plugins[].github-token to consume GitHub credentials retrieved by pre-steps in the same agent job, without requiring repository-level or organization-level GitHub Actions secrets.

Architecture: Extend only the Agent Plugin token-expression validator to accept same-job steps.<id>.outputs.<name> and env.<name> references. Keep compile-time plugin ref resolution unchanged, preserve each expression verbatim in the generated actions/checkout step, and rely on the existing ordering in which pre-steps run before plugin checkout.

Tech Stack: Go, GitHub Actions expressions, gh-aw Markdown/YAML frontmatter, actions/checkout, Go unit and compiler tests.

Spec: This document is the self-contained specification and implementation plan intended for a github/gh-aw issue.

Global Constraints

  • The feature must be provider-neutral. Vault, cloud secret managers, internal token brokers, and custom credential actions are examples, not dependencies.
  • The retrieved GitHub credential may be a long-lived PAT, fine-grained PAT, GitHub App installation token, or another token type.
  • The compiler must never evaluate, resolve, log, serialize, or persist the credential value.
  • Runtime credentials must remain within the existing agent job; cross-job secret propagation is out of scope.
  • Existing secrets.*, needs.*.outputs.*, and per-plugin github-app behavior must remain backward compatible.
  • Plugin refs must continue to resolve to immutable 40-character lowercase commit SHAs at compile time.
  • Generated plugin checkouts must continue to set persist-credentials: false.
  • Do not broaden the skills[].github-token contract unless its separate lifecycle is proven to support the same contexts.

Problem

Organizations may be unable or unwilling to duplicate a GitHub credential as a repository or organization-level GitHub Actions secret. Instead, consumer workflows authenticate to a central secret-management service at runtime and retrieve the credential through a reusable action.

Such actions commonly expose credentials in one of two same-job forms:

steps.<id>.outputs.<name>

or:

env.<name>

where the environment variable was exported through $GITHUB_ENV.

gh-aw already documents pre-steps as the hook for retrieving or minting credentials before checkout. pre-steps and Agent Plugin checkout execute in the same generated agent job, so both forms are available without crossing a job boundary.

However, plugins[].github-token currently reuses skillsGitHubTokenExpressionRegexp, which accepts only:

${{ secrets.NAME }}
${{ secrets.NAME || secrets.FALLBACK }}
${{ needs.job.outputs.name }}

It rejects:

${{ steps.credentials.outputs.github_token }}
${{ env.GH_TOKEN }}

This leaves pre-steps unable to provide runtime-retrieved credentials to private Agent Plugin checkouts. The accepted needs.*.outputs.* alternative is unsuitable for many credentials because actions commonly mask them with ::add-mask::, and GitHub Actions may suppress masked values when they are promoted to outputs across job boundaries.

Expected Usage

Credential exposed as a same-job step output

pre-steps:
  - name: Retrieve centrally managed GitHub credential
    id: plugin_credentials
    uses: octo-org/central-credentials-action@0123456789abcdef0123456789abcdef01234567

plugins:
  - plugin: octo-org/private-agent-plugin@main
    github-token: ${{ steps.plugin_credentials.outputs.github_token }}

Credential exported through $GITHUB_ENV

pre-steps:
  - name: Retrieve centrally managed GitHub credential
    uses: octo-org/central-secrets-action@0123456789abcdef0123456789abcdef01234567
    # The action exports GH_TOKEN through GITHUB_ENV.

plugins:
  - plugin: octo-org/private-agent-plugin@main
    github-token: ${{ env.GH_TOKEN }}

The generated plugin checkout must preserve the selected expression:

- name: Checkout agent plugin octo-org/private-agent-plugin
  uses: actions/checkout@<pinned-action-sha>
  with:
    repository: octo-org/private-agent-plugin
    ref: <resolved-plugin-sha>
    path: .gh-aw-plugins/plugin-0
    persist-credentials: false
    token: ${{ env.GH_TOKEN }}

Security Model

  • Same-job references avoid transporting masked credentials through job outputs.
  • Step outputs are preferred when the credential action supports them because they avoid introducing a job-wide environment variable.
  • Environment references remain necessary for existing reusable actions that expose secrets only through $GITHUB_ENV.
  • Environment-exported credentials remain available to later steps in the same job. Documentation must call out that behavior and recommend clearing or narrowly scoping credentials when appropriate.
  • Credential-producing actions should use immutable SHA pins, mask sensitive values, and return least-privilege credentials.
  • Long-lived PATs should be centrally rotated and restricted to read access for the required plugin repositories.
  • Validation must remain allowlist-based. Do not accept arbitrary GitHub Actions expressions such as github.event.*, inputs.*, function calls, or compound expressions mixing unapproved contexts.

Out of Scope

  • Integrating gh-aw with a specific secret-management vendor.
  • Requiring credentials to be dynamically minted or short-lived.
  • Propagating masked credentials between jobs.
  • Resolving credentials during gh aw compile.
  • Changing the Agent Plugin manifest format.
  • Replacing or redesigning existing per-plugin github-app support.
  • Automatically clearing environment variables after plugin checkout.

Related Work


Task 1: Add a plugin-specific token-expression contract

Files:

  • Modify: pkg/workflow/plugins_frontmatter.go
  • Test: pkg/workflow/plugins_frontmatter_test.go

Interfaces:

  • Consumes: Raw plugins[].github-token strings parsed from workflow frontmatter.

  • Produces: A plugin-specific allowlist validator that accepts secrets.*, needs.*.outputs.*, steps.*.outputs.*, and env.*.

  • Step 1: Add failing validation tests for same-job credentials

Add cases to TestValidateFrontmatterPlugins:

t.Run("accepts object form with same-job step output github-token", func(t *testing.T) {
	err := validateFrontmatterPlugins(map[string]any{
		"plugins": []any{
			map[string]any{
				"plugin":       "octo-org/private-plugin@main",
				"github-token": "${{ steps.plugin_credentials.outputs.github_token }}",
			},
		},
	})
	require.NoError(t, err)
})

t.Run("accepts object form with environment github-token", func(t *testing.T) {
	err := validateFrontmatterPlugins(map[string]any{
		"plugins": []any{
			map[string]any{
				"plugin":       "octo-org/private-plugin@main",
				"github-token": "${{ env.GH_TOKEN }}",
			},
		},
	})
	require.NoError(t, err)
})

Replace the existing test that expects a steps.*.outputs.* expression to be rejected.

  • Step 2: Add failing rejection tests for unsupported runtime expressions

Add table-driven coverage:

for _, token := range []string{
	"${{ github.token }}",
	"${{ github.event.issue.body }}",
	"${{ inputs.plugin_token }}",
	"${{ vars.PLUGIN_TOKEN }}",
	"${{ env.GH_TOKEN || secrets.GITHUB_TOKEN }}",
	"${{ steps.credentials.token }}",
	"${{ steps.credentials.outputs }}",
	"${{ env. }}",
} {
	t.Run(token, func(t *testing.T) {
		err := validateFrontmatterPlugins(map[string]any{
			"plugins": []any{
				map[string]any{
					"plugin":       "octo-org/private-plugin@main",
					"github-token": token,
				},
			},
		})
		require.ErrorContains(t, err, "plugins[0].github-token must be a valid GitHub token expression")
	})
}
  • Step 3: Run the focused test and confirm the new acceptance cases fail

Run:

go test ./pkg/workflow -run '^TestValidateFrontmatterPlugins$' -count=1

Expected: the steps.*.outputs.* and env.* acceptance cases fail under the current validator.

  • Step 4: Introduce a plugin-specific validator

Keep skillsGitHubTokenExpressionRegexp unchanged. Add a separate plugin validator with explicit alternatives:

var pluginGitHubTokenExpressionRegexp = regexp.MustCompile(
	`^\$\{\{\s*(` +
		`secrets\.[A-Za-z_][A-Za-z0-9_]*(\s*\|\|\s*secrets\.[A-Za-z_][A-Za-z0-9_]*)*` +
		`|needs\.[A-Za-z_][A-Za-z0-9_]*\.outputs\.[A-Za-z_][A-Za-z0-9_]*` +
		`|steps\.[A-Za-z_][A-Za-z0-9_]*\.outputs\.[A-Za-z_][A-Za-z0-9_]*` +
		`|env\.[A-Za-z_][A-Za-z0-9_]*` +
		`)\s*\}\}$`,
)

Use pluginGitHubTokenExpressionRegexp only in validateFrontmatterPlugins.

Update the validation error to show supported same-job forms:

return fmt.Errorf(
	"plugins[%d].github-token must be a valid GitHub token expression. Example: plugins[%d].github-token: \"${{ secrets.NAME }}\", \"${{ needs.auth.outputs.token }}\", \"${{ steps.auth.outputs.token }}\", or \"${{ env.GH_TOKEN }}\"",
	i,
	i,
)
  • Step 5: Run the focused tests

Run:

go test ./pkg/workflow -run '^TestValidateFrontmatterPlugins$' -count=1

Expected: PASS.

  • Step 6: Commit the validation contract
git add pkg/workflow/plugins_frontmatter.go pkg/workflow/plugins_frontmatter_test.go
git commit -m "Allow runtime credentials for agent plugins"

Task 2: Verify generated checkout expressions and lifecycle ordering

Files:

  • Modify: pkg/workflow/plugins_test.go
  • Reference: pkg/workflow/plugin_installation.go
  • Reference: pkg/workflow/compiler_yaml_checkout.go
  • Reference: pkg/workflow/compiler_yaml_ai_execution.go

Interfaces:

  • Consumes: Validated PluginReference.GitHubToken expressions and top-level pre-steps.

  • Produces: Generated workflow YAML where the pre-step precedes plugin checkout and the checkout receives the expression unchanged.

  • Step 1: Add a compiler test for a $GITHUB_ENV credential

Create a test following the existing temporary-workflow compilation helpers:

func TestCompileWorkflowUsesPreStepEnvironmentForPluginCheckout(t *testing.T) {
	tmpDir := testutil.TempDir(t, "plugin-runtime-env-token")
	workflowPath := filepath.Join(tmpDir, "runtime-plugin-auth.md")
	require.NoError(t, os.WriteFile(workflowPath, []byte(`---
on: workflow_dispatch
engine: copilot
pre-steps:
  - name: Load centrally managed credential
    run: echo "GH_TOKEN=runtime-value" >> "$GITHUB_ENV"
plugins:
  - plugin: octo-org/private-plugin@`+testPluginSHA+`
    github-token: ${{ env.GH_TOKEN }}
---

Use the configured plugin.
`), 0o600))

	compiler := NewCompiler(WithVersion("dev"))
	require.NoError(t, compiler.CompileWorkflow(workflowPath))

	lockPath := strings.TrimSuffix(workflowPath, ".md") + ".lock.yml"
	lockContent, err := os.ReadFile(lockPath)
	require.NoError(t, err)

	generated := string(lockContent)
	preStepIndex := strings.Index(generated, "name: Load centrally managed credential")
	checkoutIndex := strings.Index(generated, "name: Checkout agent plugin octo-org/private-plugin")
	require.NotEqual(t, -1, preStepIndex)
	require.NotEqual(t, -1, checkoutIndex)
	assert.Less(t, preStepIndex, checkoutIndex)
	assert.Contains(t, generated, "token: ${{ env.GH_TOKEN }}")
	assert.Contains(t, generated, "persist-credentials: false")
}

Adapt the compiler invocation to the exact helper used by adjacent plugin compilation tests.

  • Step 2: Add a compiler test for a same-job step output

Add a parallel test whose pre-step writes an output:

pre-steps:
  - name: Load centrally managed credential
    id: plugin_credentials
    run: echo "github_token=runtime-value" >> "$GITHUB_OUTPUT"
plugins:
  - plugin: octo-org/private-plugin@<sha>
    github-token: ${{ steps.plugin_credentials.outputs.github_token }}

Assert:

assert.Contains(t, generated, "token: ${{ steps.plugin_credentials.outputs.github_token }}")

Also assert the pre-step appears before the plugin checkout.

  • Step 3: Run the focused compiler tests

Run:

go test ./pkg/workflow -run 'TestCompileWorkflowUsesPreStep(Environment|Output)ForPluginCheckout' -count=1

Expected: PASS without modifying plugin_installation.go, because newPluginCheckoutStep already preserves the configured expression.

  • Step 4: Run related plugin tests

Run:

go test ./pkg/workflow -run 'Plugin|Plugins' -count=1

Expected: PASS, including private plugin authentication, GitHub App authentication, imports, deduplication, semantic-version merging, conflict detection, and engine capability tests.

  • Step 5: Commit compiler coverage
git add pkg/workflow/plugins_test.go
git commit -m "Test runtime plugin checkout credentials"

Task 3: Document runtime-retrieved Agent Plugin credentials

Files:

  • Modify: docs/src/content/docs/reference/frontmatter.md
  • Modify: docs/src/content/docs/reference/steps-jobs.md
  • Modify: .github/aw/skills.md
  • Inspect and reconcile if still stale: docs/src/content/docs/reference/faq.md
  • Inspect and annotate if maintainers consider it current: docs/adr/54288-add-pinned-agent-plugins-support.md

Interfaces:

  • Consumes: The validated runtime credential forms introduced in Task 1.

  • Produces: Consistent public and agent-facing documentation for provider-neutral runtime credential retrieval.

  • Step 1: Update the Agent Plugins frontmatter reference

Document all accepted token forms:

plugins:
  - plugin: octo-org/private-plugin@0123456789abcdef0123456789abcdef01234567
    github-token: ${{ secrets.PRIVATE_PLUGIN_TOKEN }}

  - plugin: octo-org/private-plugin@0123456789abcdef0123456789abcdef01234567
    github-token: ${{ steps.plugin_credentials.outputs.github_token }}

  - plugin: octo-org/private-plugin@0123456789abcdef0123456789abcdef01234567
    github-token: ${{ env.GH_TOKEN }}

State explicitly:

Use a same-job step output or environment variable when a pre-step retrieves the credential from a centralized secret-management service at runtime. The service and credential lifetime are not prescribed by gh-aw.

  • Step 2: Update the custom steps lifecycle documentation

Add a complete provider-neutral example:

permissions:
  contents: read
  id-token: write

pre-steps:
  - name: Retrieve centrally managed GitHub credential
    id: plugin_credentials
    uses: octo-org/central-credentials-action@0123456789abcdef0123456789abcdef01234567

plugins:
  - plugin: octo-org/private-agent-plugin@0123456789abcdef0123456789abcdef01234567
    github-token: ${{ steps.plugin_credentials.outputs.github_token }}

Explain that pre-steps and plugin checkout run in the same agent job, while needs.*.outputs.* crosses a job boundary and may be unsuitable for masked credentials.

  • Step 3: Align agent-facing guidance

Update .github/aw/skills.md so it no longer states that Agent Plugin repositories must be public or that per-entry authentication is unavailable.

Tell workflow-authoring agents to:

  • Use declarative plugins: instead of manual checkout or installation.

  • Prefer same-job step outputs when supported.

  • Use env.* for actions that expose credentials through $GITHUB_ENV.

  • Avoid vendor-specific assumptions.

  • Step 4: Reconcile stale FAQ and ADR guidance

Remove or qualify statements claiming that plugins: no longer exists or supports only public repositories.

If the ADR is retained as a historical decision, add a note linking to the later private-plugin authentication work rather than rewriting historical context without explanation.

  • Step 5: Run documentation checks already provided by the repository

Run the narrowest documented markdown and link checks that cover the modified files. If the repository exposes only the aggregate validation command, run:

make agent-finish

Expected: documentation, generated workflow, formatting, lint, and tests pass.

  • Step 6: Commit documentation
git add \
  docs/src/content/docs/reference/frontmatter.md \
  docs/src/content/docs/reference/steps-jobs.md \
  docs/src/content/docs/reference/faq.md \
  docs/adr/54288-add-pinned-agent-plugins-support.md \
  .github/aw/skills.md
git commit -m "Document runtime agent plugin credentials"

Only stage FAQ or ADR files if they required changes.


Task 4: Complete regression validation

Files:

  • Verify: pkg/workflow/plugins_frontmatter.go
  • Verify: pkg/workflow/plugins_frontmatter_test.go
  • Verify: pkg/workflow/plugins_test.go
  • Verify: docs/src/content/docs/reference/frontmatter.md
  • Verify: docs/src/content/docs/reference/steps-jobs.md

Interfaces:

  • Consumes: All implementation and documentation changes from Tasks 1-3.

  • Produces: A release-ready change preserving existing plugin behavior.

  • Step 1: Run formatting

make fmt

Expected: PASS with no remaining formatting changes.

  • Step 2: Run focused plugin tests
go test ./pkg/workflow -run 'Plugin|Plugins' -count=1

Expected: PASS.

  • Step 3: Run the repository completion gate
make agent-finish

Expected: build, tests, workflow recompilation, formatting, linting, and error-message validation all pass.

  • Step 4: Inspect the final diff for contract completeness

Confirm that the diff:

  • Adds env.* and steps.*.outputs.* only to Agent Plugin token validation.

  • Does not expose resolved credential values.

  • Preserves current secrets.*, needs.*.outputs.*, and github-app forms.

  • Includes generated-YAML and ordering tests.

  • Uses provider-neutral terminology.

  • Does not promise that retrieved credentials are short-lived.

  • Step 5: Commit final fixes if validation changed files

git add -A
git commit -m "Finalize runtime agent plugin credential support"

Skip this commit when validation produces no changes.

Acceptance Criteria

  • plugins[].github-token accepts ${{ steps.<id>.outputs.<name> }}.
  • plugins[].github-token accepts ${{ env.<name> }}.
  • Existing secrets.*, secret fallback chains, and needs.*.outputs.* remain accepted.
  • Unsupported expression contexts remain rejected.
  • A credential retrieved by pre-steps can authenticate a private plugin checkout in the same agent job.
  • The generated checkout preserves the configured expression exactly.
  • Plugin refs remain compile-time pinned to immutable SHAs.
  • persist-credentials: false remains present.
  • The compiler never accesses the resolved credential value.
  • Tests prove lifecycle ordering and generated YAML for both new forms.
  • Documentation is provider-neutral and distinguishes persistent credentials from dynamically minted tokens.
  • Documentation warns about the wider lifetime of $GITHUB_ENV values within the job.
  • make agent-finish passes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions