docs(troubleshoot): document GitHub Package Registry auth for @midnight-ntwrk/* (closes #787) by HarleysCodes · Pull Request #1073 · midnightntwrk/midnight-docs

HarleysCodes · 2026-06-19T21:48:35Z

Summary

Resolves #787 by adding a new 'Solution 4' to docs/troubleshoot/fix-package-repository-access-failures.mdx covering the GitHub Package Registry authentication requirement that breaks yarn install for @midnight-ntwrk/* packages with 'Invalid authentication (as an unknown user)'.

Background

midnightntwrk/midnight-js's own .yarnrc.yml configures the midnight-ntwrk scope to fetch from https://npm.pkg.github.com/. The existing troubleshoot page covers 403s from the public npm registry but never mentions GitHub Packages, so users following its solutions still hit the auth failure.

The canonical fix is already documented in midnightntwrk/midnight-js#173 (adamreynolds-io): add npmAuthToken: "${GITHUB_TOKEN}" under the midnight-ntwrk scope and set the GITHUB_TOKEN env var before installing.

Change

Adds Solution 4 between Solution 3 and the existing 'Platform-specific fixes' section.
Explains why GitHub Packages requires auth even for public packages.
Documents PAT generation (read:packages scope, fine-grained or classic).
Provides a copy-pasteable .yarnrc.yml snippet mirroring the user's working config from the issue.
Notes that yarn interpolates ${GITHUB_TOKEN} at install time, so the token never lives in the config file.
Adds an optional 'inline env var' alternative for users who don't want export.

Verification

Doc-only change. Build and runtime are unaffected.
Verified against midnightntwrk/midnight-js's actual .yarnrc.yml on main: the scope block matches what this PR recommends users add npmAuthToken to.
Cross-referenced the fix against the Yarn 4 .yarnrc.yml docs (npmAuthToken, npmAlwaysAuth, npmRegistryServer fields all behave as documented).
No other doc files reference npmAuthToken or GITHUB_TOKEN; the change is scoped to the troubleshoot page.

Out of scope (not changed)

The install/quickstart guides do not currently mention @midnight-ntwrk/* requiring GitHub Packages auth at all. Happy to follow up with a parallel update to those surfaces if the docs team prefers the guidance live there instead of (or in addition to) the troubleshoot page.

vercel · 2026-06-19T21:48:39Z

@HarleysCodes is attempting to deploy a commit to the Midnight Foundation Team on Vercel.

A member of the Team first needs to authorize it.

CLAassistant · 2026-06-22T15:23:40Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ oduameh
✅ HarleysCodes
❌ harleycodes
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

…loses midnightntwrk#787) The existing 'Fix package repository access failures' page covers 403s from the public npm registry but never addresses the 'Invalid authentication (as an unknown user)' error that occurs when installing @midnight-ntwrk/* packages from https://npm.pkg.github.com/ without an npmAuthToken. Adds a new 'Solution 4: Authenticate to GitHub Package Registry' section covering: - Why GitHub Packages requires auth even for public @midnight-ntwrk/* packages (verified against midnightntwrk/midnight-js's own .yarnrc.yml). - A copy-pasteable .yarnrc.yml snippet with the npmAuthToken field under the midnight-ntwrk scope, matching the working config cited in midnightntwrk/midnight-js#173 (adamreynolds-io's answer). - Steps to generate a GitHub PAT with read:packages scope and export it as GITHUB_TOKEN before yarn install. Closes midnightntwrk#787

…h doc The autolink `<https://github.com/settings/personal-access-tokens/new>` was being parsed by MDX as a JSX tag start; the `/` after `https:` broke tag-name parsing and crashed both `build` and `vale`. Replaced with backticked URL — same rendered output, valid MDX.

oduameh

Really well-written addition -- the structure matches the existing solutions cleanly and the technical content is accurate. Just a few suggestions to tighten the prose and align with patterns used in Solutions 1-3.

One item I could not leave inline because it is outside the diff: the page description on line 3 currently says "three proven solutions" but with this PR there are now four. It would be worth updating that to "four proven solutions" (or rewording to avoid a specific count).

oduameh · 2026-06-22T21:59:06Z


+## Solution 4: Authenticate to GitHub Package Registry
+
+If the previous solutions do not resolve the issue, the failure may be related to GitHub Package Registry authentication rather than your npm registry configuration. Midnight publishes `@midnight-ntwrk/*` packages to `https://npm.pkg.github.com/`, which requires authentication even for public packages.


Suggested change

If the previous solutions do not resolve the issue, the failure may be related to GitHub Package Registry authentication rather than your npm registry configuration. Midnight publishes `@midnight-ntwrk/*` packages to `https://npm.pkg.github.com/`, which requires authentication even for public packages.

If the previous solutions do not resolve the issue, the cause may be GitHub Package Registry authentication rather than an npm registry misconfiguration. Midnight publishes `@midnight-ntwrk/*` packages to `https://npm.pkg.github.com/`, which requires authentication even for public packages.

oduameh · 2026-06-22T21:59:06Z

+@midnight-ntwrk/ledger@npm:4.0.0::__archiveUrl=...: Invalid authentication (as an unknown user)
+```
+
+To resolve this, configure `npmAuthToken` in your `.yarnrc.yml` and provide a GitHub personal access token with the `read:packages` scope through the `GITHUB_TOKEN` environment variable.


Suggested change

To resolve this, configure `npmAuthToken` in your `.yarnrc.yml` and provide a GitHub personal access token with the `read:packages` scope through the `GITHUB_TOKEN` environment variable.

To resolve this, configure `npmAuthToken` in your `.yarnrc.yml`. You also need a GitHub personal access token with the `read:packages` scope, provided through the `GITHUB_TOKEN` environment variable.

oduameh · 2026-06-22T21:59:06Z

+
+### Generate a GitHub personal access token
+
+Create a fine-grained personal access token at `https://github.com/settings/personal-access-tokens/new` with the `read:packages` scope. A classic PAT with the same scope also works.


Suggested change

Create a fine-grained personal access token at `https://github.com/settings/personal-access-tokens/new` with the `read:packages` scope. A classic PAT with the same scope also works.

Create a fine-grained personal access token (PAT) at `https://github.com/settings/personal-access-tokens/new` with the `read:packages` scope. A classic PAT with the same scope also works.

oduameh · 2026-06-22T21:59:06Z

+
+Create a fine-grained personal access token at `https://github.com/settings/personal-access-tokens/new` with the `read:packages` scope. A classic PAT with the same scope also works.
+
+For organization-owned packages, your token must also have access to the `midnightntwrk` organization.


Suggested change

For organization-owned packages, your token must also have access to the `midnightntwrk` organization.

:::info[Organization access]

For organization-owned packages, your token must also have access to the `midnightntwrk` organization.

:::

oduameh · 2026-06-22T21:59:06Z

+    npmAuthToken: "${GITHUB_TOKEN}"
+```
+
+Yarn interpolates `${GITHUB_TOKEN}` from the environment at install time, so the token never has to live in `.yarnrc.yml`.


Suggested change

Yarn interpolates `${GITHUB_TOKEN}` from the environment at install time, so the token never has to live in `.yarnrc.yml`.

:::tip[Token security]

Yarn interpolates `${GITHUB_TOKEN}` from the environment at install time, so the token never lives in `.yarnrc.yml`.

:::

oduameh · 2026-06-22T21:59:06Z

+yarn install
+```
+
+**Verification**: Installation completes without `Invalid authentication` errors and `@midnight-ntwrk/*` packages resolve from `npm.pkg.github.com`.


Suggested change

**Verification**: Installation completes without `Invalid authentication` errors and `@midnight-ntwrk/*` packages resolve from `npm.pkg.github.com`.

**Verification**: Installation completes without `Invalid authentication` errors and `@midnight-ntwrk/*` packages resolve from `npm.pkg.github.com`.

oduameh · 2026-06-22T21:59:06Z

+
+Without a configured token, every install attempt fails with:
+
+```


For consistency with the error block earlier in the page (which uses ```bash), consider adding a language tag here. Even for output-only blocks, a tag like ```text or ```bash helps screen readers and syntax highlighters.

oduameh · 2026-06-22T21:59:06Z

+
+<Step>
+
+### Export the token and reinstall


In Solutions 1-3, the step before "Test installation" only configures things, and "Test installation" is the first time install actually runs. Here, step 3 both exports the token and runs yarn install, so step 4 re-runs the same command.

To match the existing pattern, you could separate the concerns:

Step 3 ("Export the token"): just the export command plus the inline-env-var alternative

Step 4 ("Test installation"): runs yarn install as the actual verification

That way each step does one thing, and the test step is meaningful on its own.

Addresses oduameh's review comments: - line 3: update description from 'three proven solutions' to 'four proven solutions' to match the new Solution 4. - Solution 4 intro: tighten phrasing, mirror the parallelism oduameh flagged ('authentication rather than misconfiguration'). - error output block: tag as 'text' instead of leaving it untagged, so screen readers and syntax highlighters handle it consistently with the other code blocks on the page. - '.yarnrc.yml' intro: split the long sentence oduameh flagged into two for readability. - PAT step: add '(PAT)' parenthetical on first mention; move the 'midnightntwrk organization' note into a :::info admonition to match Solution 2's pattern. - token interpolation: move into a :::tip admonition with 'Token security' label, matching Solution 2's admonition cadence. - step 4 ('Test installation'): fold into step 3 since step 3 already runs 'yarn install' — re-running the same command in a separate step added noise without adding signal. Verification prose moved to the tail of step 3 to match the Solutions 1-3 'Verification:' pattern. Refs midnightntwrk#1073.

HarleysCodes · 2026-07-01T03:18:48Z

addressed all 8 inline comments + the line-3 description fix. opted for ```text on the line 205 error block (output-only, not a command) and folded step 4 into step 3 (since step 3 already runs install — re-running the same command in a separate step added noise). happy to revisit either if you wanted the other shape.

HarleysCodes requested review from a team as code owners June 19, 2026 21:48

HarleysCodes and others added 2 commits June 22, 2026 12:19

HarleysCodes force-pushed the docs/fix-package-repo-auth-787 branch from 96d6d32 to e69ba02 Compare June 22, 2026 17:19

Merge branch 'main' into docs/fix-package-repo-auth-787

8e70c7c

oduameh reviewed Jun 22, 2026

View reviewed changes

oduameh and others added 2 commits June 23, 2026 09:21

Merge branch 'main' into docs/fix-package-repo-auth-787

6d34c0b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(troubleshoot): document GitHub Package Registry auth for @midnight-ntwrk/* (closes #787)#1073

docs(troubleshoot): document GitHub Package Registry auth for @midnight-ntwrk/* (closes #787)#1073
HarleysCodes wants to merge 5 commits into
midnightntwrk:mainfrom
HarleysCodes:docs/fix-package-repo-auth-787

HarleysCodes commented Jun 19, 2026

Uh oh!

vercel Bot commented Jun 19, 2026

Uh oh!

CLAassistant commented Jun 22, 2026 •

edited

Loading

Uh oh!

oduameh left a comment

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

oduameh Jun 22, 2026

Uh oh!

HarleysCodes commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		## Solution 4: Authenticate to GitHub Package Registry

		If the previous solutions do not resolve the issue, the failure may be related to GitHub Package Registry authentication rather than your npm registry configuration. Midnight publishes `@midnight-ntwrk/*` packages to `https://npm.pkg.github.com/`, which requires authentication even for public packages.

	To resolve this, configure `npmAuthToken` in your `.yarnrc.yml` and provide a GitHub personal access token with the `read:packages` scope through the `GITHUB_TOKEN` environment variable.
	To resolve this, configure `npmAuthToken` in your `.yarnrc.yml`. You also need a GitHub personal access token with the `read:packages` scope, provided through the `GITHUB_TOKEN` environment variable.


		### Generate a GitHub personal access token

		Create a fine-grained personal access token at `https://github.com/settings/personal-access-tokens/new` with the `read:packages` scope. A classic PAT with the same scope also works.


		Create a fine-grained personal access token at `https://github.com/settings/personal-access-tokens/new` with the `read:packages` scope. A classic PAT with the same scope also works.

		For organization-owned packages, your token must also have access to the `midnightntwrk` organization.

-Yarn interpolates `${GITHUB_TOKEN}` from the environment at install time, so the token never has to live in `.yarnrc.yml`.
+:::tip[Token security]
+Yarn interpolates `${GITHUB_TOKEN}` from the environment at install time, so the token never lives in `.yarnrc.yml`.
+:::

	Verification: Installation completes without `Invalid authentication` errors and `@midnight-ntwrk/*` packages resolve from `npm.pkg.github.com`.
	Verification: Installation completes without `Invalid authentication` errors and `@midnight-ntwrk/*` packages resolve from `npm.pkg.github.com`.


		Without a configured token, every install attempt fails with:

		```

Uh oh!

Conversation

HarleysCodes commented Jun 19, 2026

Summary

Background

Change

Verification

Out of scope (not changed)

Uh oh!

vercel Bot commented Jun 19, 2026

Uh oh!

CLAassistant commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oduameh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HarleysCodes commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Jun 22, 2026 •

edited

Loading