From c720ead88c6d6662f322c88d7b0fab91e757b9af Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 05:29:54 +0000 Subject: [PATCH 1/4] Initial plan From a0f5ee0763b6ae27d8c0cbad5b65fe9e6788517d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 05:39:19 +0000 Subject: [PATCH 2/4] docs: add steps/mcp-servers/safe-outputs.jobs import examples to imports reference Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f0bf22fb-e4e8-4bf2-9423-5093df45fb97 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/imports.md | 121 +++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 50a537dca61..986580c7496 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -271,6 +271,127 @@ Example — `tools.bash.allowed` merging: # result: [read, list, write] ``` +### Importing Steps + +Share reusable pre-execution steps — such as token rotation, environment setup, or gate checks — across multiple workflows by defining them in a shared file: + +```aw title="shared/rotate-token.md" wrap +--- +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 }} +--- +``` + +Any workflow that imports this file gets the rotation step prepended before its own steps: + +```aw title="my-workflow.md" wrap +--- +on: issues +engine: copilot +imports: + - shared/rotate-token.md +permissions: + contents: read + issues: write +steps: + - name: Prepare context + run: echo "context ready" +--- + +# My Workflow + +Process the issue using the rotated token from the imported step. +``` + +Steps from imports run **before** steps defined in the main workflow, in import declaration order. + +### Importing MCP Servers + +Define an MCP server configuration once and import it wherever needed: + +```aw title="shared/mcp/tavily.md" wrap +--- +description: Tavily web search MCP server +mcp-servers: + tavily: + url: "https://mcp.tavily.com/mcp/?tavilyApiKey=${{ secrets.TAVILY_API_KEY }}" + allowed: ["*"] +network: + allowed: + - mcp.tavily.com +--- +``` + +Import it into any workflow that needs web search: + +```aw title="research.md" wrap +--- +on: issues +engine: copilot +imports: + - shared/mcp/tavily.md +permissions: + contents: read + issues: write +--- + +# Research Workflow + +Search the web for relevant information and summarize findings in the issue. +``` + +### Importing Jobs via `safe-outputs.jobs` + +Unlike top-level `jobs:` (which cannot be imported), 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 }}\"}" +--- +``` + +Import and use it in multiple workflows: + +```aw title="my-workflow.md" wrap +--- +on: issues +engine: copilot +imports: + - shared/notify.md +permissions: + contents: read + issues: write +--- + +# My Workflow + +Process the issue. When done, use notify-slack to send a summary notification. +``` + ### Error Handling - **Circular imports**: Detected at compile time. From e20ab5c64325710eee766cfc8a3fd4f7e778f847 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:24:28 +0000 Subject: [PATCH 3/4] docs: add top-level jobs example alongside safe-outputs.jobs in imports reference Agent-Logs-Url: https://github.com/github/gh-aw/sessions/93f24123-41f3-46ac-89c2-0f10516e690c Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/imports.md | 35 +++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 986580c7496..33628196c7e 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -346,9 +346,42 @@ permissions: Search the web for relevant information and summarize findings in the issue. ``` +### Top-level `jobs:` + +Top-level `jobs:` define pre-execution jobs that run **before** the agentic step in the same workflow. They are useful for building indexes, running linters, or computing outputs the agent reads via `${{ needs.job-name.outputs.* }}`: + +```aw title="my-workflow.md" wrap +--- +on: issues +engine: copilot +imports: + - shared/mcp/tavily.md +permissions: + contents: read + issues: write +jobs: + super_linter: + runs-on: ubuntu-latest + permissions: + contents: read + statuses: write + steps: + - uses: actions/checkout@v6 + - uses: super-linter/super-linter@v7 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +--- + +# Code Quality Workflow + +Review linting results and suggest fixes for any violations found. +``` + +Top-level `jobs:` are defined per-workflow and cannot be moved into shared import files. + ### Importing Jobs via `safe-outputs.jobs` -Unlike top-level `jobs:` (which cannot be imported), jobs defined under `safe-outputs:` can be shared across workflows. These jobs become callable MCP tools that the AI agent can invoke during execution: +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 --- From af9e6c04fd2be6c36ded88baec93fd501c4f0afd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 11:35:19 +0000 Subject: [PATCH 4/4] docs: update top-level jobs example to show shared workflow import with needs ordering Agent-Logs-Url: https://github.com/github/gh-aw/sessions/7facfa39-83b7-46db-9e95-ce77a8bd17d4 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/imports.md | 59 +++++++++++++++------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index 33628196c7e..9e2ca755422 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -346,38 +346,59 @@ permissions: Search the web for relevant information and summarize findings in the issue. ``` -### Top-level `jobs:` +### Importing Top-level `jobs:` -Top-level `jobs:` define pre-execution jobs that run **before** the agentic step in the same workflow. They are useful for building indexes, running linters, or computing outputs the agent reads via `${{ needs.job-name.outputs.* }}`: +Top-level `jobs:` defined in a shared workflow are merged into the importing workflow's compiled lock file. The job execution order is determined by `needs` entries — a shared job can run before or after other jobs in the final workflow: + +```aw title="shared/build.md" wrap +--- +description: Shared build job that compiles artifacts for the agent to inspect + +jobs: + build: + runs-on: ubuntu-latest + needs: [activation] + outputs: + artifact_name: ${{ steps.build.outputs.artifact_name }} + steps: + - uses: actions/checkout@v6 + - name: Build + id: build + run: | + npm ci && npm run build + echo "artifact_name=build-output" >> "$GITHUB_OUTPUT" + - uses: actions/upload-artifact@v4 + with: + name: build-output + path: dist/ + +steps: + - uses: actions/download-artifact@v4 + with: + name: ${{ needs.build.outputs.artifact_name }} + path: /tmp/build-output +--- +``` + +Import it so the `build` job runs before the agent and its artifacts are available as pre-steps: ```aw title="my-workflow.md" wrap --- -on: issues +on: pull_request engine: copilot imports: - - shared/mcp/tavily.md + - shared/build.md permissions: contents: read - issues: write -jobs: - super_linter: - runs-on: ubuntu-latest - permissions: - contents: read - statuses: write - steps: - - uses: actions/checkout@v6 - - uses: super-linter/super-linter@v7 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + pull-requests: write --- -# Code Quality Workflow +# Code Review Workflow -Review linting results and suggest fixes for any violations found. +Review the build output in /tmp/build-output and suggest improvements. ``` -Top-level `jobs:` are defined per-workflow and cannot be moved into shared import files. +In the compiled lock file the `build` job appears alongside `activation` and `agent` jobs, ordered according to each job's `needs` declarations. ### Importing Jobs via `safe-outputs.jobs`