GitHub API Notification Plugin for reg-suit

Common errors

• GitHub API responded with status 404 (Not Found) for repository 'owner/repository'

  cause The configured `owner` or `repository` in `reg.config.json` does not match an existing GitHub repository accessible by the provided token.
  fix Verify that the `owner` and `repository` configuration values are correct and that the `privateToken` has access to that specific repository.

• GitHub API responded with status 401 (Unauthorized) - Bad credentials

  cause The `privateToken` provided in the `reg.config.json` is invalid, expired, or lacks the necessary permissions (e.g., 'repo' scope for private repositories).
  fix Generate a new GitHub Personal Access Token with the required `repo` scope and update your `reg.config.json` or environment variable. Ensure there are no typos.

• Error: Plugin 'notify-github-with-api' not found.

  cause The plugin has not been correctly installed or `reg-suit` has not been prepared to recognize it.
  fix Ensure you have run `npm install reg-notify-github-with-api-plugin -D` and then `reg-suit prepare -p notify-github-with-api` to register the plugin with your `reg-suit` configuration.

Warnings

• gotcha This plugin (`reg-notify-github-with-api-plugin`) is specifically for GitHub Enterprise or scenarios requiring personal access token authentication. If you are using `github.com` and prefer GitHub App integration, the `reg-notify-github-plugin` is generally recommended. Do not confuse the two as their authentication methods differ significantly.
  Fix: Determine your GitHub environment and preferred authentication. For `github.com` with a GitHub App, use `reg-notify-github-plugin`. For GitHub Enterprise or PATs, use `reg-notify-github-with-api-plugin`.
• breaking The `privateToken` configuration option requires a GitHub Personal Access Token with the `repo` scope if the target repository is private. Insufficient scopes will lead to authentication failures when attempting to comment or update PR status.
  Fix: Ensure your Personal Access Token has the necessary `repo` scope for private repositories, or appropriate read/write access for public ones. Test the token's permissions using the GitHub API directly.
• gotcha Multiple `reg-suit` runs on the same pull request might overwrite each other's comments if they use the default `markerComment`. This can lead to lost history or confusion in visual regression reports.
  Fix: For `reg-notify-github-with-api-plugin` version 0.14.6 and higher, configure a unique `markerComment` string in your `reg.config.json` for each distinct workflow or instance of `reg-suit` running on the same PR. Example: `markerComment: 'reg-visual-tests-dark-theme'`.

Install

• npm install reg-notify-github-with-api-plugin npm
• yarn add reg-notify-github-with-api-plugin yarn
• pnpm add reg-notify-github-with-api-plugin pnpm

Imports

• RegNotifyGithubWithApiPlugin

  import RegNotifyGithubWithApiPlugin from 'reg-notify-github-with-api-plugin';

  While end-users primarily interact via `reg-suit` CLI configuration, this is the expected import for programmatic usage or testing the plugin directly. It's a default export of the plugin class.
• RegNotifyGithubWithApiPluginOption

  import type { RegNotifyGithubWithApiPluginOption } from 'reg-notify-github-with-api-plugin';

  Imports the TypeScript interface defining the configuration object for the plugin. Useful for type-checking when creating `reg.config.ts` or custom wrappers.
• prepare command
  wrong:

  import { prepare } from 'reg-suit'; prepare('-p notify-github-with-api');

  correct:

  reg-suit prepare -p notify-github-with-api

  This is how users typically 'import' and configure the plugin within the `reg-suit` ecosystem, not via JavaScript/TypeScript import statements in their application code.

Quickstart

Demonstrates how to install the plugin and configure it within `reg-suit` using a `reg.config.ts` file to enable GitHub API notifications for visual regression test results, emphasizing secure handling of sensitive credentials.

npm i reg-notify-github-with-api-plugin -D
reg-suit prepare -p notify-github-with-api

// Add this configuration to your reg.config.json or reg.config.ts
// Ensure you replace placeholder values with your actual GitHub details and token.
// For security, it's highly recommended to use environment variables for `privateToken`.

interface RegConfig {
  plugins: [
    'reg-keygen-git-hash-plugin',
    'reg-publish-s3-plugin', // Or 'reg-publish-gcs-plugin' for Google Cloud Storage
    ['reg-notify-github-with-api-plugin', {
      githubUrl: process.env.GITHUB_API_URL ?? 'https://api.github.com/graphql',
      owner: process.env.GITHUB_REPO_OWNER ?? 'your-org-or-username',
      repository: process.env.GITHUB_REPO_NAME ?? 'your-repo',
      privateToken: process.env.GITHUB_TOKEN ?? '', // Requires 'repo' scope for private repos
      ref: process.env.GITHUB_PR_REF ?? undefined,
      shortDescription: true,
      markerComment: 'reg-visual-test-results' // Optional: Customize for multiple workflows
    }]
  ];
}

// Example reg.config.ts (if you use TypeScript for configuration)
const config: RegConfig = {
  plugins: [
    'reg-keygen-git-hash-plugin',
    'reg-publish-s3-plugin',
    ['reg-notify-github-with-api-plugin', {
      githubUrl: process.env.GITHUB_API_URL || 'https://api.github.com/graphql',
      owner: process.env.GITHUB_REPO_OWNER || 'your-org-or-username',
      repository: process.env.GITHUB_REPO_NAME || 'your-repo',
      privateToken: process.env.GITHUB_TOKEN || '',
      ref: process.env.GITHUB_PR_REF,
      shortDescription: true,
      markerComment: 'reg-visual-test-results'
    }]
  ]
};

export default config;