# Troubleshoot a package release approval

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/troubleshoot-a-package-release-approval/)

If your GitHub Actions workflow already waits for KeySigner approval before publishing to npm, use the request ID to see where the release stopped and what you can safely retry.

## Before you start

**KeySigner console and enrolled owner approval tools. KeySigner console and access to the npm test package**

- Use a disposable package and a GitHub Actions workflow already configured to wait for KeySigner. Have a separate requester, enough eligible owners and access to the workflow logs.
- Register the disposable package and its owner rule in KeySigner. Use the registry’s own publishing configuration and keep the approved digest and workflow run available for comparison.

## Data and access

- **Shared or checked**. The workflow request ID links the package digest and KeySigner approval to the GitHub Actions run. Compare the published archive’s digest with the approved package.
- **Check separately**. npm publishing trust and package permissions are separate. Review an already-published version before retrying.

## 1. Match the request to the workflow run

In the KeySigner console, open Accounts and find the package under Packages. Check the registered owners, required number of approvals and minimum key tier. Compare the release request from your workflow with the intended registry, package, version, archive digest and GitHub Actions run.

**Check.** The package and owner rule match the rehearsal, and the workflow identifies the request and the exact archive it will publish.

## 2. Check whether an owner still needs to act

Find the release in the history below Packages. If it says Waiting for owners, compare the approval count with the rule. Ask a registered owner who has yet to vote to review the existing request with their enrolled approval tool. The requester cannot approve their own release.

![KeySigner package history shows one release waiting with one of two approvals and another approved release flagged Published bytes differ.](https://keysigner.io/integrations/guides/troubleshoot-a-package-release-approval/package-history-status.png)

In this local test, version 1.0.2 still needed an owner. Version 1.0.1 was approved, then flagged after we submitted a different digest.

**Check.** A row such as 1 of 2 approvals still needs one eligible owner. Submitting the same pending release again with a new request key returns the ID of the existing request.

## 3. Use the request state to decide what to retry

Keep the request ID from the original workflow attempt. Check its current state before starting another approval or rerunning the publish job.

**Check.** A fresh approval attempt applies to the same waiting request. An owner denial ends that request, and the workflow should leave publication blocked.

### What did KeySigner report?

- **Already waiting for owners**. Use the request ID in the response. Ask the next eligible owner to review that request.
- **Approval attempt expired**. If the request still says Waiting for owners, start a new approval attempt for that request. Check that the existing approval count is still present.
- **Denied**. Ask the owner what needs to change. After you review the package, version and digest, submit a new request only if the release should proceed.
- **Approved**. Continue to the workflow and registry check. Approval covers the requested archive.

## 4. Verify what npm received

If the request is Approved, open the corresponding GitHub Actions run and check the publish step. Open the exact version on npm and compare the SHA-256 of its downloaded package archive with the approved digest. Check provenance against the run and source commit if it’s available.

**Check.** The publish job and registry show the expected version, and the downloaded archive matches the digest that owners approved.

## Check your result

Record the KeySigner request ID, GitHub Actions run, npm package version and digest together. Before you rely on the gate, rehearse a denied or still-waiting request and confirm the workflow skips the publish step.

### What we tested

**Tested on November 18, 2026.** We used a local KeySigner API and Chromium with a disposable package record. We verified duplicate handling, rejection of an approval attempt whose expiry we set in the test fixture, a fresh attempt on the same request, denial and a digest finding visible to an owner. The rehearsal used test digests and stopped at KeySigner. Verify the publish job and registry outcome in your own workflow.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### Package history says Published bytes differ

Pause publishing and ask the release owner and workflow maintainer to investigate. Compare the approved digest, the digest recorded in KeySigner and the SHA-256 of the archive downloaded from npm. The release requester or a KeySigner administrator can submit a digest for comparison. An authorized auditor can export the finding. If your team forwards audit events, verify delivery in the receiving system.

## Tools in this guide

- [GitHub Actions](https://keysigner.io/integrations/github-actions/)
  - [Review deployment environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#github-actions)
- [npm](https://keysigner.io/integrations/npm/)
  - [Review trusted publishers](https://docs.npmjs.com/trusted-publishers/)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#npm)

## Setup instructions

- [Review the GitHub Actions and npm publishing setup](https://keysigner.io/integrations/guides/github-actions-and-npm/)
- [Export release decisions and digest findings](https://keysigner.io/integrations/approval-history/#release)
- [Check audit delivery](https://keysigner.io/integrations/approval-history/#delivery)
- [Read GitHub Actions workflow logs](https://docs.github.com/en/actions/how-tos/monitor-workflows/use-workflow-run-logs)
- [Check npm package provenance](https://docs.npmjs.com/generating-provenance-statements/)
- [Check an approved package with Cosign](https://keysigner.io/integrations/guides/check-an-approved-package-with-cosign/)
- [Use the integration rollout checklist](https://keysigner.io/integrations/rollout-checklist/)

[More guides for this task](https://keysigner.io/integrations/tasks/review-code-and-releases/)
