Custom Safe Outputs | GitHub Agentic Workflows
Skip to main content Custom Safe Outputs Custom safe outputs extend built-in GitHub operations to third-party services such as Slack, Discord, Notion, databases, or any external API that requires authentication. Use them for write operations that built-in safe outputs do not cover. Quick Start Section titled “Quick Start” Here’s a minimal custom safe output that sends a Slack message: .github/workflows/shared/slack-notify.md --- safe-outputs : jobs : slack-notify : description : " Send a message to Slack " runs-on : ubuntu-latest output : " Message sent to Slack!
" inputs : message : description : " The message to send " required : true type : string steps : - name : Send Slack message env : SLACK_WEBHOOK : " ${{ secrets.SLACK_WEBHOOK }} " run : | if [ -f "$GH_AW_AGENT_OUTPUT" ]; then MESSAGE=$(cat "$GH_AW_AGENT_OUTPUT" | jq -r '.items[] | select(.type == "slack_notify") | .message') # Use jq to safely escape JSON content PAYLOAD=$(jq -n --arg text "$MESSAGE" '{text: $text}') curl -X POST "$SLACK_WEBHOOK" \ -H 'Content-Type: application/json' \ -d "$PAYLOAD" else echo "No agent output found" exit 1 fi --- Use it in a workflow: .github/workflows/issue-notifier.md --- on : issues : types : [ opened ] permissions : contents : read imports : - shared/slack-notify.md --- # Issue Notifier A new issue was opened: "${{ steps.sanitized.outputs.text }}" Summarize the issue and use the slack-notify tool to send a notification.
The agent calls slack-notify , and the custom job runs with access to the SLACK_WEBHOOK secret. Architecture Section titled “Architecture” Agents use read-only Model Context Protocol (MCP) servers with allowed: tool lists. Custom jobs perform writes with secret access after the agent completes. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Agent (AI) │────│ MCP Server │────│ External API │ │ │ │ (read-only) │ │ (GET requests) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ calls safe-job tool ▼ ┌─────────────────┐ ┌─────────────────┐ │ Custom Job │────│ External API │ │ (with secrets) │ │ (POST/PUT) │ └─────────────────┘ └─────────────────┘ Creating a Custom Safe Output Section titled “Creating a Custom Safe Output” Recording execution outcomes Section titled “Recording execution outcomes” Optionally map status and url outputs from the job so Conclusion can record what happened: outputs : status : ${{ steps.publish.outputs.status }} url : ${{ steps.publish.outputs.url }} The step with id: publish sets them with $GITHUB_OUTPUT or core.setOutput . status is success , failure , cancelled , or skipped .
Use skipped for staged previews and intentional no-ops. Set url only to the absolute URI the service returns, never one the agent suggested. Conclusion records a safe_output.result event in usage/aw_session.jsonl . Without an explicit status, the Actions job result is used. Failed, cancelled, and skipped jobs never report a URL. A successful job without a URL proves execution, not creation of an identifiable resource.
Custom scripts instead return { success: true, url: canonicalResourceUri } after the service confirms the operation. Step 1: Define the Shared Configuration Section titled “Step 1: Define the Shared Configuration” In a shared file, define the read-only MCP server and the custom job together: --- mcp-servers : notion : container : " mcp/notion " env : NOTION_TOKEN : " ${{ secrets.NOTION_TOKEN }} " allowed : - " search_pages " - " get_page " - " get_database " - " query_database " safe-outputs : jobs : notion-add-comment : description : " Add a comment to a Notion page " runs-on : ubuntu-latest output : " Comment added to Notion successfully!
" permissions : contents : read inputs : page_id : description : " The Notion page ID to add a comment to " required : true type : string comment : description : " The comment text to add " required : true type : string steps : - name : Add comment to Notion page uses : actions/github-script@v8 env : NOTION_TOKEN : " ${{ secrets.NOTION_TOKEN }} " with : script : | const fs = require('fs'); const items = JSON.parse(fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, 'utf8')) .items.filter(item => item.type === 'notion_add_comment'); for (const item of items) { const response = await fetch('https://api.notion.com/v1/comments', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.NOTION_TOKEN}`, 'Notion-Version': '2022-06-28', 'Content-Type': 'application/json' }, body: JSON.stringify({ parent: { page_id: item.page_id }, rich_text: [{ type: 'text', text: { content: item.comment } }] }) }); if (!response.ok) { core.setFailed(`Notion API error (${response.status}): ${await response.text()}`); return; } } --- Use container: for Docker servers or command: / args: for npx.
List only read-only tools in allowed . Every job requires description and inputs ; output sets the success message. Step 2: Use in Workflow Section titled “Step 2: Use in Workflow” Import the configuration: --- on : issues : types : [ opened ] permissions : contents : read actions : read imports : - shared/mcp/notion.md --- # Issue Summary to Notion Analyze the issue: "${{ steps.sanitized.outputs.text }}" Search for the GitHub Issues page in Notion using the read-only Notion tools, then add a summary comment using the notion-add-comment safe-job.
The agent queries with read-only tools, and the safe job runs with write permissions after the agent completes. Safe Job Reference Section titled “Safe Job Reference” Attribution and Tracking Section titled “Attribution and Tracking” Custom jobs must add a generated-by footer linking to the workflow run and preserve workflow provenance annotations on published issues, discussions, and comments. Direct API calls bypass built-in handlers, so without attribution, audits cannot identify the items as workflow-generated.
Custom jobs receive the same GH_AW_WORKFLOW_* , engine, tracker, message, and detection metadata as built-in jobs. For GitHub issues, use the createIssue helper below instead of hand-maintained footer templates. Issue Creation API Section titled “Issue Creation API” actions/setup/js/index.cjs re-exports setupGlobals , createIssue , and logSpan . Run the setup action to install the runtime helpers, then load them from ${RUNNER_TEMP}/gh-aw/actions/index.cjs in actions/github-script : safe-outputs: jobs: publish-finding: description: "Publish one validated finding" runs-on: ubuntu-latest permissions: issues: write inputs: body: description: "Finding details" required: true type: string steps: - uses: github/gh-aw/actions/setup@main - uses: actions/github-script@v9.0.0 with: script: | const fs = require("node:fs"); const actionsDir = `${process.env.RUNNER_TEMP}/gh-aw/actions` ; const { setupGlobals, createIssue } = require( `${actionsDir}/index.cjs` ); setupGlobals(core, github, context, exec, io, getOctokit); const { sanitizeContent } = require( `${actionsDir}/sanitize_content.cjs` ); const output = JSON.parse(fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, "utf8")); const items = output.items.filter(item => item.type === "publish_finding"); if (items.length !== 1 || typeof items[ 0 ].body !== "string") { throw new Error("Exactly one finding with a string body is required"); } const result = await createIssue({ title: "Validated workflow finding", body: sanitizeContent(items[ 0 ].body), }); if (!result.staged) core.info(result.issue.html_url); Use a release that contains this API, and pin the setup action to a trusted commit in production.
API Contract setup
The rest of this page is on the live site.