Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Jan 22, 2026

Upgrade Guide Documentation

Create a comprehensive guide for upgrading agentic-workflows covering:

Plan

  • Explore repository structure and existing documentation
  • Understand upgrade command functionality
  • Review documentation style guidelines and patterns
  • Create upgrade guide in /docs/src/content/docs/guides/upgrading.md
  • Include sections on:
    • Prerequisites for upgrading
    • Backing up workflows before upgrade
    • Running the upgrade command
    • Reviewing the changes made
    • Testing upgraded workflows
    • Pushing updates to repository
    • Troubleshooting common issues
  • Add GitHub alerts for important warnings
  • Include code examples following GitHub Docs style
  • Build and validate documentation
  • Fix any build errors or warnings
  • Merge main branch
  • Rebuild documentation after merge
  • Update documentation to reflect automatic compilation

Summary

Created /docs/src/content/docs/guides/upgrading.md with:

  • Overview of upgrade process (agent files + codemods + automatic compilation)
  • Prerequisites and setup verification
  • Step-by-step upgrade workflow (8 steps, including lock file review)
  • Comprehensive troubleshooting section
  • Advanced topics (CI/CD, custom directories, selective codemods)
  • Best practices and next steps

Merged main branch which included:

Updated documentation to reflect PR #11131 changes:

  • Documented that gh aw upgrade now automatically compiles workflows
  • Updated all command examples and references throughout the guide
  • Added Step 6: Review Generated Lock Files
  • Clarified that --no-fix flag skips both codemods and compilation
  • Removed redundant gh aw compile commands from CI/CD examples
  • Updated troubleshooting sections for automatic compilation scenarios

Validated:

  • Documentation builds successfully with make build-docs
  • All internal links validated
  • Follows GitHub Docs voice and Diátaxis framework

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

Original prompt

adf a guide for upgrading agentic-workflows. It covers upgrading the extensions, running the upgrade command, reviewing the changes, and pushing the updates to the repository.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot AI changed the title [WIP] Add guide for upgrading agentic-workflows Add upgrade guide for agentic workflows Jan 22, 2026
Copilot AI requested a review from pelikhan January 22, 2026 00:30
@pelikhan
Copy link
Contributor

@copilot mega main and update docs

Copy link
Contributor Author

Copilot AI commented Jan 22, 2026

@copilot mega main and update docs

Merged main branch and rebuilt documentation successfully. Commit: f8b2a21

The merge included:

Documentation builds with zero errors and all internal links validate.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • telemetry.astro.build
    • Triggering command: /opt/hostedtoolcache/node/24.12.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

@pelikhan
Copy link
Contributor

@copilot review the changes from the last merge, specifically that the upgrade command now also runs compile, and update the documentation accordingly.

- Document that upgrade command now compiles workflows automatically
- Update overview to mention 3 key areas (added compilation)
- Clarify that compilation step is now part of upgrade command
- Update all command examples to reflect compilation is included
- Add new Step 6 for reviewing generated lock files
- Renumber subsequent steps (Step 7: Test, Step 8: Commit)
- Remove redundant compile step from CI/CD example
- Add notes about --no-fix skipping both codemods and compilation
- Update troubleshooting sections to reflect automatic compilation

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Jan 22, 2026

@copilot review the changes from the last merge, specifically that the upgrade command now also runs compile, and update the documentation accordingly.

Updated the upgrade guide to reflect automatic workflow compilation. Commit: 0bb30d6

Key changes:

  • Documented that gh aw upgrade now performs 3 operations (added compilation)
  • Updated overview, examples, and all command references
  • Added Step 6: Review Generated Lock Files
  • Renumbered subsequent steps (Step 7: Test, Step 8: Commit)
  • Removed redundant gh aw compile from CI/CD example
  • Updated --no-fix flag description (skips both codemods and compilation)
  • Clarified troubleshooting sections for automatic compilation

The guide now accurately reflects that compilation happens automatically during upgrade.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • telemetry.astro.build
    • Triggering command: /opt/hostedtoolcache/node/24.12.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

@pelikhan pelikhan marked this pull request as ready for review January 22, 2026 01:16
@pelikhan pelikhan merged commit 98cea81 into main Jan 22, 2026
70 checks passed
@pelikhan pelikhan deleted the copilot/upgrade-agentic-workflows branch January 22, 2026 01:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants