{"id":16952,"library":"auto","title":"Auto Release Automation CLI","description":"auto is a comprehensive command-line interface (CLI) tool meticulously engineered to automate release workflows by leveraging semantic versioning conventions, primarily driven by GitHub Pull Request labels. As of its current stable version 11.3.6, the project maintains an active release cadence, frequently delivering bug fixes and incremental enhancements, as evidenced by its consistent patch and minor updates. A significant differentiator of `auto` lies in its label-driven methodology, which streamlines the release process without necessitating alterations to your codebase or drastic overhauls of existing development workflows. It integrates seamlessly into continuous integration/continuous delivery (CI/CD) pipelines while also supporting local execution. The tool features a modular architecture, extensible through a rich ecosystem of plugins (e.g., `@auto-it/npm`, `@auto-it/slack`), enabling users to adapt its functionality for diverse package managers and platforms. Furthermore, `auto` ships with robust TypeScript types, facilitating more reliable integration and development processes.","status":"active","version":"11.3.6","language":"javascript","source_language":"en","source_url":"https://github.com/intuit/auto","tags":["javascript","automation","semantic","release","github","labels","automated","continuos integration","changelog","typescript"],"install":[{"cmd":"npm install auto","lang":"bash","label":"npm"},{"cmd":"yarn add auto","lang":"bash","label":"yarn"},{"cmd":"pnpm add auto","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `auto` package is primarily a CLI tool executed via `npx auto` or a global installation. Direct programmatic import of the top-level `auto` package for general application use is uncommon. Programmatic interaction is typically handled through its core utility package.","wrong":"import { auto } from 'auto'","symbol":"auto","correct":"npx auto [command]"},{"note":"For developing custom plugins or interacting with `auto`'s core logic programmatically, symbols like `Auto` and `IPlugin` are imported from the `@auto-it/core` package, not the main `auto` package.","wrong":"import { Auto, IPlugin } from 'auto'","symbol":"Auto, IPlugin","correct":"import { Auto, IPlugin } from '@auto-it/core'"},{"note":"Specific plugins are imported from their respective scoped packages (e.g., `@auto-it/npm`). They are then configured in the `.autorc` file's `plugins` array.","wrong":"import { NpmPlugin } from 'auto/npm'","symbol":"NpmPlugin","correct":"import { NpmPlugin } from '@auto-it/npm'"}],"quickstart":{"code":"import { Auto, IPlugin } from '@auto-it/core';\nimport { NpmPlugin } from '@auto-it/npm';\nimport { GithubPlugin } from '@auto-it/github';\nimport { execSync } from 'child_process';\n\nasync function runAutoProgrammatically() {\n  // Set up required environment variables (replace with your actual tokens)\n  process.env.GH_TOKEN = process.env.GH_TOKEN ?? ''; // GitHub Personal Access Token\n  process.env.NPM_TOKEN = process.env.NPM_TOKEN ?? ''; // NPM Publish Token (if using NpmPlugin)\n\n  // Basic configuration for demonstration\n  const autoOptions = {\n    owner: 'your-org', // Replace with your GitHub organization/user\n    repo: 'your-repo', // Replace with your repository name\n    baseBranch: 'main', // Or your default branch\n    plugins: [\n      new NpmPlugin(),\n      new GithubPlugin(),\n      // Add other plugins as needed\n    ],\n  };\n\n  try {\n    // Initialize auto (this usually happens via the CLI `auto init` for .autorc setup)\n    // For programmatic use, we instantiate `Auto` directly.\n    const auto = new Auto(autoOptions);\n    await auto.loadConfig(); // Load default config and apply plugin configs\n\n    // Example: Check if a release can be made\n    console.log('Checking for new releases...');\n    const newVersion = await auto.getVersion();\n    console.log(`Calculated next version: ${newVersion}`);\n\n    if (newVersion) {\n      console.log(`\nTo simulate a release process, run the following commands manually after setting up GitHub labels (major, minor, patch) on a PR:\n1. Create a PR with a semantic label (e.g., 'minor')\n2. Merge the PR\n3. Set GH_TOKEN and NPM_TOKEN (if publishing to npm)\n4. Execute 'npx auto shipit' or 'npx auto version' in your CI/local environment.\n`);\n      // Programmatic execution of a 'version' command (simplified)\n      // In a real CI, this would involve more setup and error handling.\n      // For demonstration, we'll just show the concept.\n      // await auto.run('version'); // This would trigger versioning, changelog, etc.\n    } else {\n      console.log('No new version detected based on PR labels.');\n    }\n  } catch (error) {\n    console.error('An error occurred:', error instanceof Error ? error.message : error);\n    process.exit(1);\n  }\n}\n\n// To run the programmatic example:\n// 1. npm install auto @auto-it/core @auto-it/npm @auto-it/github\n// 2. Set GH_TOKEN and NPM_TOKEN environment variables.\n// 3. Replace 'your-org' and 'your-repo'.\n// 4. node your_script.js\nrunAutoProgrammatically();","lang":"typescript","description":"This quickstart demonstrates how to set up `auto` programmatically and check the next semantic version based on GitHub labels, providing a foundation for custom automation logic or testing. It highlights the use of core and plugin imports."},"warnings":[{"fix":"Upgrade your Node.js environment to version 10.x or newer.","message":"The `auto` CLI requires Node.js version 10 or higher. Older Node.js environments will result in execution failures or unexpected behavior.","severity":"breaking","affected_versions":"<10.0.0"},{"fix":"Ensure `GH_TOKEN` and `NPM_TOKEN` (if using the npm plugin) are correctly set as environment variables in your CI/local environment. Consider using a `.env` file at your project root, but remember to `.gitignore` it for security.","message":"For `auto` to interact with GitHub (e.g., creating releases, commenting on PRs) and npm (for publishing), `GH_TOKEN` and `NPM_TOKEN` environment variables (respectively) are mandatory. Failure to set them will lead to authentication errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware of the configuration precedence. For consistent behavior, use `.autorc` for baseline settings and CLI flags sparingly for temporary overrides or CI-specific adjustments.","message":"Configuration options can be set via `.autorc` (camelCase) or CLI flags (snake-case). CLI flags always override `.autorc` settings for overlapping options. This can lead to unexpected behavior if not understood.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update `auto` to version 11.3.3 or newer to ensure compatibility with the latest GitHub API. `npm install auto@latest`","message":"Versions of `auto` prior to v11.3.3 might encounter failures due to changes or deprecations in the GitHub API, as a bug fix to handle these deprecations was introduced in v11.3.3.","severity":"breaking","affected_versions":"<11.3.3"},{"fix":"Verify that your GitHub repository has a release tagged and marked as 'Latest Release'. If not, manually tag your last version and create a GitHub release for it.","message":"For `auto` to correctly determine the next version and generate changelogs, your last release on GitHub must be tagged and explicitly marked as the 'Latest Release'. Without this, `auto` may not find a baseline to calculate diffs.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Set the `GH_TOKEN` environment variable with a valid GitHub Personal Access Token (PAT) that has appropriate permissions (repo scope).","cause":"The `GH_TOKEN` environment variable is not set or is empty, preventing `auto` from authenticating with GitHub.","error":"Error: No GitHub token found. Please set the GH_TOKEN environment variable."},{"fix":"Add a semantic versioning label to the Pull Request. Refer to your `.autorc` configuration or `auto init` defaults for valid labels.","cause":"The Pull Request `auto` is inspecting does not have any semantic versioning labels (e.g., `major`, `minor`, `patch`, `release`, `prerelease`, etc.) configured for your project.","error":"Error: Could not find any valid labels on PR #XYZ to determine version bump."},{"fix":"Ensure the `GH_TOKEN` has write access to the repository and that git is correctly configured with these credentials, especially in CI environments.","cause":"The git push operation failed, likely due to insufficient permissions or incorrect git credentials configured in the environment where `auto` is running.","error":"Error: Could not push to remote. Check your git credentials."},{"fix":"Set the `NPM_TOKEN` environment variable with a valid npm publish token. If using a private registry, ensure your `.npmrc` is correctly configured or pass `legacyAuth` option to the npm plugin.","cause":"The `NPM_TOKEN` environment variable is missing or invalid, or the npm plugin is misconfigured, preventing package publication.","error":"Error: Could not publish to npm. Check your NPM_TOKEN environment variable."}],"ecosystem":"npm","meta_description":null}