Workflows

This page provides a comprehensive guide to workflows in the Goose project, including orchestration, design decisions, and step-by-step tutorials. Workflows automate processes like publishing packages, managing versions, and troubleshooting issues, ensuring reliability and efficiency. For foundational setup, review the Installation page.

Design Decisions in Workflow Orchestration

Goose prioritizes reliability and efficiency in workflow orchestration, incorporating performance optimizations and modular designs to minimize failures and resource waste:

• Error Handling: Workflows include checks to handle failures, such as skipping steps on errors or using dry-run modes for testing.
• Platform-Specific Optimizations: To address performance issues, Goose temporarily disables certain builds (e.g., Windows) until optimizations are in place, such as implementing caching strategies to reduce delays on cache misses.
• Versioning Integration: Users manage versions manually or via CLI, as automated tools like Changesets have been replaced for better reliability. This approach prevents errors that could trigger unnecessary rebuilds and waste resources.
• Modular Workflows: Goose uses modular designs for extensibility, but this introduces potential points of failure, such as incorrect paths or dependency mismatches. To mitigate, review workflow files and test changes incrementally.

Workflows can be triggered via GitHub CLI or API calls, with Goose monitoring and reporting on execution. The deployment process integrates with automation to handle versioning and release management securely, such as running only on the main branch to prevent accidental releases. Additionally, removing redundant steps, like unnecessary directory checks, simplifies processes and avoids errors that could halt workflows.

Tutorial: Publishing Packages to npm

This tutorial guides you through publishing Goose packages to npm using workflows. It automates builds, versioning, and publishing in a multi-package setup, reducing manual errors. The process navigates to the relevant directory and executes a recursive publish command to handle all packages in one step.

Prerequisites

• Ensure Goose is installed as described in Installation.
• Work in a repository with the ui directory, containing packages like @aaif/goose-acp and @aaif/goose.
• Have GitHub CLI (gh) installed.

Step-by-Step Guide

1. Prepare Your Environment: Navigate to your Goose project directory and run pnpm install to resolve dependencies.

1. Test the Workflow in Dry-Run Mode: Run the workflow to verify builds without publishing.

• Command:

gh workflow run publish-npm.yml --ref <branch> -f dry-run=true

This generates schemas, builds binaries (excluding Windows for performance), and lists packages for verification.

1. Manage Versions Manually: Bump versions using CLI commands.

• For a patch update:

cd ui/acp
pnpm version patch
git commit -am "chore: bump version for acp"
git push

Repeat for other packages as needed.

1. Run the Actual Publish: After testing, merge changes to the main branch and execute the workflow.

• Command:

gh workflow run publish-npm.yml --ref main -f dry-run=false

This builds and publishes packages using pnpm publish -r --access public --no-git-checks from the ui directory.

Workflow Changes and Simplifications

Recent updates simplified the publishing workflow by replacing unreliable components, such as the Changesets action, with direct pnpm commands for better reliability. This change eliminates unnecessary steps and enhances efficiency.

Tutorial: Managing Versions in Goose

Version management is crucial for tracking changes in Goose's multi-package structure. Without automated tools, versions are handled manually or via CLI, promoting efficiency by avoiding resource-intensive rebuilds.

Step-by-Step Guide

1. Choose a Versioning Strategy:

• Manual Bumps: For simple scenarios:

cd ui/goose
pnpm version minor

• Use Changesets CLI: For structured changes:

cd ui
pnpm changeset add
pnpm changeset version
git commit -am "chore: version packages"

1. Integrate with Workflows: After bumping versions, commit, push, and follow the publishing tutorial to test and deploy.

Key Concepts

• Follow semantic versioning (e.g., major.minor.patch).
• Verify versions in package.json files before publishing to prevent errors.

Tutorial: Troubleshooting Common Workflow Issues

Goose workflows may encounter issues like publishing errors, build problems, or misconfigurations. This section covers debugging techniques, including log inspection and performance-related fixes, to resolve them effectively.

Step-by-Step Guide

1. Handle "Package Already Exists" Errors: Bump the version and re-run the workflow.

• Example:

cd ui/acp
pnpm version patch
git commit -am "chore: bump version"
git push

1. Address Cache or Build Problems: Skip cache for rebuilds or audit for redundant steps.

• Command:

gh workflow run publish-npm.yml -f skip-cache=true

Inspect logs for timestamps, error codes, and stack traces to trace issues to specific components, such as incorrect paths or dependency mismatches.

1. Test Iteratively: Always use dry-run mode for initial tests to identify issues. Start by checking configuration files for errors, and review workflow files like publish-npm.yml for potential misconfigurations.

Best Practices

Regularly review workflows to align with Goose's design, such as re-enabling Windows builds after optimizations. For advanced error resolution, see Contributing.