{"id":16193,"library":"reg-notify-github-with-api-plugin","title":"GitHub API Notification Plugin for reg-suit","description":"This plugin for `reg-suit`, a visual regression testing CLI, sends notification results to GitHub repositories. It is specifically designed for GitHub Enterprise users, utilizing the GitHub API with a personal access token for authentication, differentiating it from `reg-notify-github-plugin` which relies on a GitHub App for `github.com`. The current stable version is 0.14.6, with minor releases occurring actively as indicated by recent changelog entries. Key features include configurable GitHub URL, repository owner and name, private access token, and options for customizing the PR comment style, such as a short summary table. It's an essential component for integrating `reg-suit` results into GitHub-centric CI/CD workflows, especially in enterprise environments where GitHub Apps might be restricted.","status":"active","version":"0.14.6","language":"javascript","source_language":"en","source_url":"https://github.com/reg-viz/reg-suit","tags":["javascript","reg","reg-suit-plugin","GitHub","typescript"],"install":[{"cmd":"npm install reg-notify-github-with-api-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add reg-notify-github-with-api-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add reg-notify-github-with-api-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for the visual regression testing CLI; this package is a plugin for it.","package":"reg-suit","optional":false}],"imports":[{"note":"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.","symbol":"RegNotifyGithubWithApiPlugin","correct":"import RegNotifyGithubWithApiPlugin from 'reg-notify-github-with-api-plugin';"},{"note":"Imports the TypeScript interface defining the configuration object for the plugin. Useful for type-checking when creating `reg.config.ts` or custom wrappers.","symbol":"RegNotifyGithubWithApiPluginOption","correct":"import type { RegNotifyGithubWithApiPluginOption } from 'reg-notify-github-with-api-plugin';"},{"note":"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.","wrong":"import { prepare } from 'reg-suit'; prepare('-p notify-github-with-api');","symbol":"prepare command","correct":"reg-suit prepare -p notify-github-with-api"}],"quickstart":{"code":"npm i reg-notify-github-with-api-plugin -D\nreg-suit prepare -p notify-github-with-api\n\n// Add this configuration to your reg.config.json or reg.config.ts\n// Ensure you replace placeholder values with your actual GitHub details and token.\n// For security, it's highly recommended to use environment variables for `privateToken`.\n\ninterface RegConfig {\n  plugins: [\n    'reg-keygen-git-hash-plugin',\n    'reg-publish-s3-plugin', // Or 'reg-publish-gcs-plugin' for Google Cloud Storage\n    ['reg-notify-github-with-api-plugin', {\n      githubUrl: process.env.GITHUB_API_URL ?? 'https://api.github.com/graphql',\n      owner: process.env.GITHUB_REPO_OWNER ?? 'your-org-or-username',\n      repository: process.env.GITHUB_REPO_NAME ?? 'your-repo',\n      privateToken: process.env.GITHUB_TOKEN ?? '', // Requires 'repo' scope for private repos\n      ref: process.env.GITHUB_PR_REF ?? undefined,\n      shortDescription: true,\n      markerComment: 'reg-visual-test-results' // Optional: Customize for multiple workflows\n    }]\n  ];\n}\n\n// Example reg.config.ts (if you use TypeScript for configuration)\nconst config: RegConfig = {\n  plugins: [\n    'reg-keygen-git-hash-plugin',\n    'reg-publish-s3-plugin',\n    ['reg-notify-github-with-api-plugin', {\n      githubUrl: process.env.GITHUB_API_URL || 'https://api.github.com/graphql',\n      owner: process.env.GITHUB_REPO_OWNER || 'your-org-or-username',\n      repository: process.env.GITHUB_REPO_NAME || 'your-repo',\n      privateToken: process.env.GITHUB_TOKEN || '',\n      ref: process.env.GITHUB_PR_REF,\n      shortDescription: true,\n      markerComment: 'reg-visual-test-results'\n    }]\n  ]\n};\n\nexport default config;","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":">=0.14.6"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that the `owner` and `repository` configuration values are correct and that the `privateToken` has access to that specific repository.","cause":"The configured `owner` or `repository` in `reg.config.json` does not match an existing GitHub repository accessible by the provided token.","error":"GitHub API responded with status 404 (Not Found) for repository 'owner/repository'"},{"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.","cause":"The `privateToken` provided in the `reg.config.json` is invalid, expired, or lacks the necessary permissions (e.g., 'repo' scope for private repositories).","error":"GitHub API responded with status 401 (Unauthorized) - Bad credentials"},{"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.","cause":"The plugin has not been correctly installed or `reg-suit` has not been prepared to recognize it.","error":"Error: Plugin 'notify-github-with-api' not found."}],"ecosystem":"npm"}