docs: add concrete steps/mcp-servers/jobs import examples to imports reference

[Copilot]

The imports: field already supports AzDo-style step templating, but the reference docs only described merge semantics in a table without showing how to actually use it. Adds concrete examples to the Frontmatter Merging section of imports.md.

Added examples

• Importing Steps — shared rotate-token.md with a GitHub App token step; imported steps are prepended before the main workflow's own steps in declaration order
• Importing MCP Servers — shared shared/mcp/tavily.md imported into any workflow needing web search
• Importing Top-level jobs: — shows a shared/build.md with a jobs: entry that uses needs to declare its position; shared jobs are merged into the importing workflow's compiled lock file and ordered by needs declarations (the job can run before or after the agent job)
• Importing Jobs via safe-outputs.jobs — shows the callable MCP tool alternative that exposes jobs the AI agent can invoke on demand

Steps import example

---
description: Shared token rotation setup
steps:
  - name: Rotate GitHub App token
    id: get-token
    uses: actions/create-github-app-token@v1
    with:
      app-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}
---

---
on: issues
engine: copilot
imports:
  - shared/rotate-token.md
permissions:
  contents: read
  issues: write
---

[github-actions]

Hey @Copilot 👋 — thanks for picking up this issue and getting the PR started! Adding concrete import examples to docs/src/content/docs/reference/imports.md is exactly the right approach for helping users share reusable steps.

A few things to address before this is ready for review:

• No code changes yet — the only commit is Initial plan with 0 files changed. The three examples listed in the checklist (steps import, MCP servers import, safe-outputs.jobs import) still need to be written.
• Missing PR description — the body is a task checklist, not a summary of what this PR does and why. A short paragraph explaining the problem being solved and what was added would help reviewers and future readers.
• Validate the docs build — once the examples are added, run make agent-finish to confirm build, lint, and recompile all pass.

Here's a ready-to-use prompt to complete this:

Complete the WIP PR #23835 in github/gh-aw.

The goal is to add three concrete import examples to `docs/src/content/docs/reference/imports.md`.
The motivation: users currently copy-paste boilerplate steps (e.g. token-rotation logic) across multiple workflows — reusable step imports solve this.

Steps:
1. Open `docs/src/content/docs/reference/imports.md` and study the existing examples and structure.
2. Add a new section with three clearly labelled code examples:
   a. **Steps import** — shared workflow defining reusable steps; caller imports via `imports:` frontmatter field.
   b. **MCP servers import** — shared file exposing an `mcp-servers:` block; caller pulls it in.
   c. **`safe-outputs.jobs` import** — shared file defining a `safe-outputs.jobs` block; caller imports it.
3. Each example should use the ```aw fence, follow the parameterized `uses`/`with` pattern where inputs vary, and include brief prose.
4. Update the PR body to replace the checklist with a proper description.
5. Run `make agent-finish` before pushing.

Generated by Contribution Check · ◷

[pelikhan]

@copilot show top level jobs like in qmd.md

[Copilot]

Added a "Top-level jobs:" subsection (e20ab5c) showing the super-linter pre-execution job pattern before the safe-outputs.jobs section, with a note that top-level jobs are per-workflow and cannot be imported.

[pelikhan]

@copilot top level jobs in shared agentic workflows are imported in the final lock file and ordered according to the "needs" entries. Update sample to focus on shared agentic workflows .

The custom job can be before or after the jobs using needs

[Copilot]

Pull request overview

Adds concrete, copy/paste-ready examples to the imports: reference docs so readers can see how AzDo-style step templating works in practice (steps, MCP servers, and importable job-like behavior via safe-outputs.jobs).

Changes:

• Add a “Importing Steps” example showing imported steps are prepended in import declaration order
• Add an “Importing MCP Servers” example showing how to share and import an mcp-servers: + network: block
• Add guidance and examples around top-level jobs: (non-importable) and the importable alternative safe-outputs.jobs

Comments suppressed due to low confidence (1)

docs/src/content/docs/reference/imports.md:394

• The YAML example defines safe-outputs: notify-slack: directly. For importable custom jobs, this should be nested as safe-outputs: { jobs: { notify-slack: ... } } so it’s recognized as a custom safe-output job (and merged according to safe-outputs.jobs).

description: Shared notification job
safe-outputs:
  notify-slack:
    description: "Post a message to Slack"
    runs-on: ubuntu-latest
    output: "Notification sent"
    inputs:

---

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

[Copilot]

In this section the text says jobs are defined under safe-outputs:. Custom safe-output jobs are defined under safe-outputs.jobs: (see reference/custom-safe-outputs.md quick start); otherwise the workflow treats the key as a built-in safe-output type and compilation/behavior will be incorrect. Update the wording here to explicitly reference safe-outputs.jobs.

This issue also appears on line 388 of the same file.

Suggested change

	Jobs defined under `safe-outputs:` can be shared across workflows. These jobs become callable MCP tools that the AI agent can invoke during execution:
	```aw title="shared/notify.md" wrap
	---
	description: Shared notification job
	safe-outputs:
	notify-slack:
	description: "Post a message to Slack"
	runs-on: ubuntu-latest
	output: "Notification sent"
	inputs:
	message:
	description: "Message to post"
	required: true
	type: string
	steps:
	- name: Post to Slack
	env:
	SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }}
	run: |
	curl -s -X POST "$SLACK_WEBHOOK" \
	-H "Content-Type: application/json" \
	-d "{\"text\":\"${{ inputs.message }}\"}"
	Jobs defined under `safe-outputs.jobs:` can be shared across workflows. These jobs become callable MCP tools that the AI agent can invoke during execution:
	```aw title="shared/notify.md" wrap
	---
	description: Shared notification job
	safe-outputs:
	jobs:
	notify-slack:
	description: "Post a message to Slack"
	runs-on: ubuntu-latest
	output: "Notification sent"
	inputs:
	message:
	description: "Message to post"
	required: true
	type: string
	steps:
	- name: Post to Slack
	env:
	SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }}
	run: |
	curl -s -X POST "$SLACK_WEBHOOK" \
	-H "Content-Type: application/json" \
	-d "{\"text\":\"${{ inputs.message }}\"}"

[Copilot]

Inside a safe-outputs.jobs.<name> job, ${{ inputs.message }} is not a GitHub Actions input context. The job should read the tool call payload from $GH_AW_AGENT_OUTPUT (filtering by type with dashes normalized to underscores, e.g. notify_slack) and then construct the JSON payload with proper escaping (e.g. using jq) before calling curl.

Suggested change

	curl -s -X POST "$SLACK_WEBHOOK" \
	-H "Content-Type: application/json" \
	-d "{\"text\":\"${{ inputs.message }}\"}"
	message="$(
	echo "$GH_AW_AGENT_OUTPUT" | jq -r '
	.tools[]
	| select(.type == "notify_slack")
	| .payload.message
	'
	)"
	payload="$(jq -n --arg text "$message" '{text: $text}')"
	curl -s -X POST "$SLACK_WEBHOOK" \
	-H "Content-Type: application/json" \
	-d "$payload"

[Copilot]

@copilot top level jobs in shared agentic workflows are imported in the final lock file and ordered according to the "needs" entries. Update sample to focus on shared agentic workflows .

The custom j...

Updated in af9e6c0. The example now shows a shared/build.md with a top-level jobs: entry that uses needs: [activation] to declare its position in the job graph. The description explains that jobs from shared files are merged into the lock file and ordered by their needs entries — so a shared job can run before or after the agent job.

[pelikhan]

@copilot move jobs in separate shared workflow, remove taviky from this section example

[Copilot]

Already done in af9e6c0 — the section now shows jobs: defined inside a separate shared/build.md file (not inline in the consuming workflow), and the Tavily import was removed from this example.