Reusing Workflows

Adding Workflows

You can add any existing workflow you have access to from external repositories.

Use the gh aw add-wizard command to add a workflow with interactive guidance:

gh aw add-wizard <workflow-url>

For example, to add the daily-repo-status workflow from the githubnext/agentics repository:

# Full GitHub URL
gh aw add-wizard https://github.com/githubnext/agentics/blob/main/workflows/daily-repo-status.md

# Short form (for workflows in top-level workflows/ directory)
gh aw add-wizard githubnext/agentics/daily-repo-status

# Skip the API key prompt when a secret is already configured
gh aw add-wizard githubnext/agentics/daily-repo-status --skip-secret

This checks requirements, adds the workflow markdown file to your repository, and generates the corresponding YAML workflow. After adding, commit and push the changes to your repository.

The --skip-secret flag bypasses the interactive API key prompt. Use it when the required secret (e.g., COPILOT_GITHUB_TOKEN) is already configured at the organisation or repository level.

For non-interactive installation, use gh aw add with optional versioning. By default this looks in the workflows/ directory, but you can specify an explicit path if needed:

gh aw add githubnext/agentics/ci-doctor              # short form
gh aw add githubnext/agentics/ci-doctor@v1.0.0       # with version
gh aw add githubnext/agentics/workflows/ci-doctor.md # explicit path

Use --name, --pr, --force, --engine, or --verbose flags to customize installation. The source field is automatically added to workflow frontmatter for tracking origin and enabling updates.

When installing a workflow, gh aw add also automatically fetches:

• Workflows referenced in the workflow’s dispatch-workflow safe output.
• Files declared in the workflow’s resources: frontmatter field (companion workflows, custom actions).

Note

Check carefully that the workflow comes from a trusted source and is appropriate for your use in your repository. Review the workflow’s content and understand what it does before adding it to your repository.

Note

Workflows marked with private: true in their frontmatter cannot be added to other repositories. Attempting to do so will fail with an error. See Private Workflows for details.

Using an Agent to Import and Adapt a Workflow

You can use a coding agent to import a workflow from another repository and adapt it for your own. The agent reads the source workflow, customizes repository-specific configuration (labels, assignees, branch names, permissions), and sets up the repository — including initialization if needed.

Tip

Use this approach when you want to significantly customize a workflow before using it. For straightforward imports without modification, use gh aw add or gh aw add-wizard instead.

GitHub Web Interface

If you have access to GitHub Copilot, use one of these prompts in your repository to import and adapt a workflow from another repo. Each prompt also initializes the repository for GitHub Agentic Workflows if it has not been set up yet.

Daily Status Report

Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md

Then import and adapt the daily-repo-status workflow from githubnext/agentics. The source is at https://github.com/githubnext/agentics/blob/main/workflows/daily-repo-status.md. Adapt any labels, team references, and output format to suit this repository.

Issue Triage

Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md

Then import and adapt an issue triage workflow from github/gh-aw. Find a suitable issue triage workflow in that repository and adapt it: update the labels, assignee logic, and any repository-specific rules to match this project's conventions.

CI Doctor

Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md

Then import and adapt the CI Doctor workflow from githubnext/agentics. The source is at https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md. Adapt the workflow to match this repository's CI setup, branch naming, and issue labeling conventions.

Tip

On the first run in a new repository, the workflow may fail because secrets are not yet configured. The agentic workflow should detect missing tokens and open an issue with setup instructions.

Coding Agent

Follow these steps to import and adapt a workflow using VSCode, Claude, Codex, or Copilot in your terminal.

1. Start your coding agent in the context of your repository.

2. Enter the following prompt, replacing SOURCE_WORKFLOW, OWNER, and REPO with the workflow you want to import:

   Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md
   
   Then import and adapt the SOURCE_WORKFLOW workflow from OWNER/REPO. The source is at https://github.com/OWNER/REPO/blob/main/workflows/SOURCE_WORKFLOW.md.
   
   Adapt the workflow for this repository: update any labels, assignees, branch names, and permissions to match this project's structure. Keep the overall purpose and logic of the workflow intact.

   You can add as much extra context, constraints, or customization goals after the last line as you need.

3. Set up required secrets if you haven’t done so already. See Engines for the secrets your chosen engine requires.

After the agent finishes, review the adapted workflow, merge the pull request, and trigger a run from the Actions tab or with gh aw run.

Updating Workflows

When you add a workflow, a tracking source: entry remembers where it came from. You can keep workflows synchronized with their source repositories:

gh aw update                           # update all workflows
gh aw update ci-doctor                 # update specific workflow
gh aw update ci-doctor issue-triage    # update multiple

Use --major, --force, --no-merge, --engine, or --verbose flags to control update behavior. Semantic versions (e.g., v1.2.3) update to latest compatible release within same major version. Branch references update to latest commit. SHA references update to the latest commit on the default branch. Updates use 3-way merge by default to preserve local changes; use --no-merge to replace with the upstream version. When merge conflicts occur, manually resolve conflict markers and run gh aw compile.

Imports

Import reusable components using the imports: field in frontmatter. File paths are relative to the workflow location:

---
on: issues
engine: copilot
imports:
  - shared/common-tools.md
  - shared/security-setup.md
  - shared/mcp/tavily.md
---

During gh aw add, imports are expanded to track source repository (e.g., shared/common-tools.md becomes githubnext/agentics/shared/common-tools.md@abc123def).

Remote imports are automatically cached in .github/aw/imports/ by commit SHA. This enables offline workflow compilation once imports have been downloaded. The cache is shared across different refs pointing to the same commit, reducing redundant downloads.

See Imports Reference for path formats, merge semantics, and field-specific behavior.

Importing Agent Files

Agent files provide specialized AI instructions and behavior. See Importing Copilot Copilot Agent Files for details on creating and importing agent files from external repositories.

Example: Modular Workflow with Imports

Create a shared Model Context Protocol (MCP) server configuration in .github/workflows/shared/mcp/tavily.md:

---
mcp-servers:
  tavily:
    url: "https://mcp.tavily.com/mcp/?tavilyApiKey=${{ secrets.TAVILY_API_KEY }}"
    allowed: ["*"]
network:
  allowed:
    - mcp.tavily.com
---

Reference it in your workflow to include the Tavily MCP server alongside other tools:

---
on:
  issues:
    types: [opened]
imports:
  - shared/mcp/tavily.md
tools:
  github:
    toolsets: [issues]
permissions:
  contents: read
---

# Research Agent
Perform web research using Tavily and respond to issues.

Result: The compiled workflow includes both the Tavily MCP server from the import and the GitHub tools from the main workflow, with network permissions automatically merged to allow access to both mcp.tavily.com and GitHub API endpoints.

Specification Formats and Validation

Workflow and import specifications require minimum 3 parts (owner/repo/path) for remote imports. Explicit paths must end with .md. Versions can be semantic tags (@v1.0.0), branches (@develop), or commit SHAs. Identifiers use alphanumeric characters with hyphens/underscores (cannot start/end with hyphen).

Examples:

• Repository: owner/repo[@version]
• Short workflow: owner/repo/workflow[@version] (adds workflows/ prefix and .md)
• Explicit workflow: owner/repo/path/to/workflow.md[@version]
• Shared import: owner/repo/shared/tools/config.md[@version]
• Copilot agent file import: owner/repo/.github/agents/agent-name.md[@version]
• GitHub URL: https://github.com/owner/repo/blob/main/workflows/ci-doctor.md
• Raw URL: https://raw.githubusercontent.com/owner/repo/refs/heads/main/workflows/ci-doctor.md

Best Practices

Use semantic versioning for stable workflows and agent files, branches for development, and commit SHAs for immutability.

Related: CLI Commands | Workflow Structure | Frontmatter | Imports | Copilot Agent Files