Skip to content

[docs] docs: Remove bloat from packaging-imports.md guide (56% reduction) #1851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Oct 17, 2025
Merged

[docs] docs: Remove bloat from packaging-imports.md guide (56% reduction) #1851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
60b0acc
docs: Remove bloat from packaging-imports.md guide
github-actions[bot] Oct 17, 2025
7f35efd
chore: Add changeset for documentation unbloat
github-actions[bot] Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/patch-unbloat-packaging-imports.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

168 changes: 22 additions & 146 deletions docs/src/content/docs/guides/packaging-imports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,72 +5,33 @@ sidebar:
order: 600
---

This guide covers adding, updating, and importing agentic workflows from external repositories using workflow specifications and import directives.

## Adding Workflows

Install workflows from external repositories:
Install workflows from external repositories with optional versioning:

```bash
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
```

**Options:**

| Flag | Description |
|------|-------------|
| `--name NAME` | Custom workflow name |
| `--pr` | Create pull request for review |
| `--force` | Overwrite existing files |
| `--number N` | Create N numbered copies |
| `--engine ENGINE` | Override AI engine |
| `--verbose` | Show detailed output |

The `source` field is automatically added to workflow frontmatter for tracking origin and enabling updates:

```yaml
source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0"
```
Use `--name`, `--pr`, `--force`, `--number`, `--engine`, or `--verbose` flags to customize installation. The `source` field is automatically added to workflow frontmatter for tracking origin and enabling updates.

## Updating Workflows

Keep workflows in sync with source repositories:
Keep workflows synchronized with their source repositories:

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

**Options:**

| Flag | Description |
|------|-------------|
| `--major` | Allow major version updates |
| `--force` | Update even if no changes detected |
| `--engine ENGINE` | Override AI engine for compilation |
| `--verbose` | Show detailed resolution steps |

**Update Behavior:**

- **Semantic versions** (e.g., `v1.2.3`): Updates to latest compatible release within same major version (use `--major` for major updates)
- **Branch references** (e.g., `main`): Updates to latest commit on that branch
- **No reference**: Updates to latest commit on default branch

**Conflict Resolution:**

Updates use 3-way merge via `git merge-file`. When conflicts occur:
Use `--major`, `--force`, `--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. Updates use 3-way merge; when conflicts occur, manually resolve conflict markers and run `gh aw compile`.

1. Review conflict markers in the workflow file
2. Manually edit to keep desired changes
3. Remove conflict markers (`<<<<<<<`, `|||||||`, `=======`, `>>>>>>>`)
4. Run `gh aw compile` to recompile
## Imports

## Imports Field

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

```yaml
---
Expand All @@ -83,41 +44,13 @@ imports:
---
```

File paths are relative to the workflow location. During `gh aw add`, imports are expanded to track source repository:

```yaml
# Before (source repo)
imports: [shared/common-tools.md]

# After (your repo)
imports: [githubnext/agentics/shared/common-tools.md@abc123def]
```

## Examples

### Version Management

```bash
# Add versioned workflow
gh aw add githubnext/agentics/ci-doctor@v1.0.0

# Update to latest v1.x
gh aw update ci-doctor
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`).

# Allow major version update
gh aw update ci-doctor --major
## Example: Modular Workflow with Imports

# Track development branch
gh aw add githubnext/agentics/experimental@develop
gh aw update experimental
```

### Modular Workflows with Imports

Create shared MCP server configuration:
Create a shared MCP server configuration in `.github/workflows/shared/mcp/tavily.md`:

```aw wrap
# .github/workflows/shared/mcp/tavily.md
```yaml
---
mcp-servers:
tavily:
Expand All @@ -126,10 +59,9 @@ mcp-servers:
---
```

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

```aw wrap
# .github/workflows/research-agent.md
```yaml
---
on:
issues:
Expand All @@ -145,75 +77,19 @@ tools:
Perform web research using Tavily and respond to issues.
```

The compiled workflow includes both Tavily MCP server and GitHub tools.

## Validation
## Specification Formats and Validation

**Common Errors:**
Workflow specifications require minimum 3 parts (owner/repo/workflow-name) for short form. 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).

| Error | Fix |
|-------|-----|
| `repository must be in format 'org/repo'` | Include owner and repo with slash |
| `workflow specification must be in format 'owner/repo/workflow-name[@version]'` | Include owner, repo, and workflow name |
| `workflow specification with path must end with '.md' extension` | Add `.md` extension for explicit paths |
| `'owner-/repo' does not look like a valid GitHub repository` | Don't start/end identifiers with hyphens |

**Specification Requirements:**

- Minimum 3 parts (owner/repo/workflow-name) for short form
- Explicit paths must end with `.md`
- Version optional (tag, branch, or commit SHA)
- Identifiers: alphanumeric 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]`
- 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

**Version Management:**
- Use semantic versioning for stable workflows (`@v1.0.0`)
- Use branches for development (`@develop`)
- Pin to commit SHAs for immutability (`@abc123def...`)

**Import Organization:**
- Create `shared/` directory for reusable components
- Use descriptive names (`github-tools.md`, `security-notice.md`)
- Keep imports focused on specific functionality

**Workflow Updates:**
- Review changes with `gh aw update --verbose` before applying
- Test updates on a branch before merging
- Resolve conflicts promptly to avoid compilation failures
- Keep local modifications minimal to reduce merge conflicts
- Preserve the `source` field to enable updates

## Reference

**Specification Formats:**

| Format | Example | Notes |
|--------|---------|-------|
| Repository | `owner/repo[@version]` | Version optional |
| Short workflow | `owner/repo/workflow[@version]` | Adds `workflows/` prefix and `.md` |
| Explicit workflow | `owner/repo/path/to/workflow.md[@version]` | Full path required |
| GitHub URL | `https://github.com/owner/repo/blob/main/workflows/ci-doctor.md` | Extracts ref from URL |
| Raw URL | `https://raw.githubusercontent.com/owner/repo/refs/heads/main/workflows/ci-doctor.md` | Direct file access |

**Version Types:**

- **Semantic versions**: `v1.0.0`, `v1.2.3`, `1.0.0`, `v2.0.0-beta`
- **Branch names**: `main`, `develop`, `feature/new-feature`
- **Commit SHAs**: `abc123def456789012345678901234567890abcdef` (40 chars)
- **No version**: Uses repository default branch

**Source Field:**

Automatically added to workflow frontmatter to track origin:

```yaml
source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0"
```

## Related Documentation
Use semantic versioning for stable workflows, branches for development, and commit SHAs for immutability. Organize reusable components in a `shared/` directory with descriptive names. Review updates with `--verbose` before applying, test on branches, and keep local modifications minimal to reduce merge conflicts.

- [CLI Commands](/gh-aw/tools/cli/) - Complete CLI reference
- [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory layout and organization
- [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options
- [Imports](/gh-aw/reference/imports/) - Include directive details
**Related:** [CLI Commands](/gh-aw/tools/cli/) | [Workflow Structure](/gh-aw/reference/workflow-structure/) | [Frontmatter](/gh-aw/reference/frontmatter/) | [Imports](/gh-aw/reference/imports/)
Loading