Auto Release Automation CLI

Common errors

• Error: No GitHub token found. Please set the GH_TOKEN environment variable.

  cause The `GH_TOKEN` environment variable is not set or is empty, preventing `auto` from authenticating with GitHub.
  fix Set the `GH_TOKEN` environment variable with a valid GitHub Personal Access Token (PAT) that has appropriate permissions (repo scope).

• Error: Could not find any valid labels on PR #XYZ to determine version bump.

  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.
  fix Add a semantic versioning label to the Pull Request. Refer to your `.autorc` configuration or `auto init` defaults for valid labels.

• Error: Could not push to remote. Check your git credentials.

  cause The git push operation failed, likely due to insufficient permissions or incorrect git credentials configured in the environment where `auto` is running.
  fix Ensure the `GH_TOKEN` has write access to the repository and that git is correctly configured with these credentials, especially in CI environments.

• Error: Could not publish to npm. Check your NPM_TOKEN environment variable.

  cause The `NPM_TOKEN` environment variable is missing or invalid, or the npm plugin is misconfigured, preventing package publication.
  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.

Warnings

• breaking The `auto` CLI requires Node.js version 10 or higher. Older Node.js environments will result in execution failures or unexpected behavior.
  Fix: Upgrade your Node.js environment to version 10.x or newer.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  Fix: Update `auto` to version 11.3.3 or newer to ensure compatibility with the latest GitHub API. `npm install auto@latest`
• gotcha 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.
  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.

Install

• npm install auto npm
• yarn add auto yarn
• pnpm add auto pnpm

Imports

• auto
  wrong:

  import { auto } from 'auto'

  correct:

  npx auto [command]

  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.
• Auto, IPlugin
  wrong:

  import { Auto, IPlugin } from 'auto'

  correct:

  import { Auto, IPlugin } from '@auto-it/core'

  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.
• NpmPlugin
  wrong:

  import { NpmPlugin } from 'auto/npm'

  correct:

  import { NpmPlugin } from '@auto-it/npm'

  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.

Quickstart

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.

import { Auto, IPlugin } from '@auto-it/core';
import { NpmPlugin } from '@auto-it/npm';
import { GithubPlugin } from '@auto-it/github';
import { execSync } from 'child_process';

async function runAutoProgrammatically() {
  // Set up required environment variables (replace with your actual tokens)
  process.env.GH_TOKEN = process.env.GH_TOKEN ?? ''; // GitHub Personal Access Token
  process.env.NPM_TOKEN = process.env.NPM_TOKEN ?? ''; // NPM Publish Token (if using NpmPlugin)

  // Basic configuration for demonstration
  const autoOptions = {
    owner: 'your-org', // Replace with your GitHub organization/user
    repo: 'your-repo', // Replace with your repository name
    baseBranch: 'main', // Or your default branch
    plugins: [
      new NpmPlugin(),
      new GithubPlugin(),
      // Add other plugins as needed
    ],
  };

  try {
    // Initialize auto (this usually happens via the CLI `auto init` for .autorc setup)
    // For programmatic use, we instantiate `Auto` directly.
    const auto = new Auto(autoOptions);
    await auto.loadConfig(); // Load default config and apply plugin configs

    // Example: Check if a release can be made
    console.log('Checking for new releases...');
    const newVersion = await auto.getVersion();
    console.log(`Calculated next version: ${newVersion}`);

    if (newVersion) {
      console.log(`
To simulate a release process, run the following commands manually after setting up GitHub labels (major, minor, patch) on a PR:
1. Create a PR with a semantic label (e.g., 'minor')
2. Merge the PR
3. Set GH_TOKEN and NPM_TOKEN (if publishing to npm)
4. Execute 'npx auto shipit' or 'npx auto version' in your CI/local environment.
`);
      // Programmatic execution of a 'version' command (simplified)
      // In a real CI, this would involve more setup and error handling.
      // For demonstration, we'll just show the concept.
      // await auto.run('version'); // This would trigger versioning, changelog, etc.
    } else {
      console.log('No new version detected based on PR labels.');
    }
  } catch (error) {
    console.error('An error occurred:', error instanceof Error ? error.message : error);
    process.exit(1);
  }
}

// To run the programmatic example:
// 1. npm install auto @auto-it/core @auto-it/npm @auto-it/github
// 2. Set GH_TOKEN and NPM_TOKEN environment variables.
// 3. Replace 'your-org' and 'your-repo'.
// 4. node your_script.js
runAutoProgrammatically();