Repository navigation
Description
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
agentjob; cross-job secret propagation is out of scope. - Existing
secrets.*,needs.*.outputs.*, and per-plugingithub-appbehavior 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-tokencontract 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-appsupport. - Automatically clearing environment variables after plugin checkout.
Related Work
- Issue: Support authenticated Agent Plugin installation from private repositories #55775
- Implementing PR: Support authenticated Agent Plugin installation from private repositories #56505
- Frontmatter validation:
pkg/workflow/plugins_frontmatter.go - Checkout generation:
pkg/workflow/plugin_installation.go - Ref pinning:
pkg/workflow/plugins_ref_resolution.go - Pre-step ordering:
pkg/workflow/compiler_yaml_checkout.go - Validation tests:
pkg/workflow/plugins_frontmatter_test.go - Compiler tests:
pkg/workflow/plugins_test.go
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-tokenstrings parsed from workflow frontmatter. -
Produces: A plugin-specific allowlist validator that accepts
secrets.*,needs.*.outputs.*,steps.*.outputs.*, andenv.*. -
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=1Expected: 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=1Expected: 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.GitHubTokenexpressions and top-levelpre-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_ENVcredential
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=1Expected: 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=1Expected: 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-finishExpected: 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 fmtExpected: PASS with no remaining formatting changes.
- Step 2: Run focused plugin tests
go test ./pkg/workflow -run 'Plugin|Plugins' -count=1Expected: PASS.
- Step 3: Run the repository completion gate
make agent-finishExpected: 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.*andsteps.*.outputs.*only to Agent Plugin token validation. -
Does not expose resolved credential values.
-
Preserves current
secrets.*,needs.*.outputs.*, andgithub-appforms. -
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-tokenaccepts${{ steps.<id>.outputs.<name> }}. -
plugins[].github-tokenaccepts${{ env.<name> }}. - Existing
secrets.*, secret fallback chains, andneeds.*.outputs.*remain accepted. - Unsupported expression contexts remain rejected.
- A credential retrieved by
pre-stepscan authenticate a private plugin checkout in the sameagentjob. - The generated checkout preserves the configured expression exactly.
- Plugin refs remain compile-time pinned to immutable SHAs.
-
persist-credentials: falseremains 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_ENVvalues within the job. -
make agent-finishpasses.
Activity