From 282a53c1c1ea3cac8798c38efdd6bae981a22895 Mon Sep 17 00:00:00 2001 From: John Reilly Date: Sat, 7 Dec 2024 09:11:57 +0000 Subject: [PATCH] feat: Cross platform usage docs and attempt to fix post release permissions (#19) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## PR Checklist - [ ] Addresses an existing open issue: fixes #000 - [ ] That issue was marked as [`status: accepting prs`](https://github.com/johnnyreilly/azdo-npm-auth/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [ ] Steps in [CONTRIBUTING.md](https://github.com/johnnyreilly/azdo-npm-auth/blob/main/.github/CONTRIBUTING.md) were taken ## Overview This PR documents how to use the tool in a cross platform way. It also applies the change suggested by @apexskier here to attempt to fix post-release permissions: https://github.com/apexskier/github-release-commenter/issues/545#issuecomment-2513388057 --- .github/workflows/post-release.yml | 5 +++++ README.md | 28 +++++++++++++++------------- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.github/workflows/post-release.yml b/.github/workflows/post-release.yml index 5643479..e95ea00 100644 --- a/.github/workflows/post-release.yml +++ b/.github/workflows/post-release.yml @@ -1,3 +1,8 @@ +# based on https://github.com/apexskier/github-release-commenter/issues/545#issuecomment-2513388057 +permissions: + issues: write + pull-requests: write + jobs: post_release: runs-on: ubuntu-latest diff --git a/README.md b/README.md index 65cfd3b..8398778 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,10 @@ Simply set up user authentication to Azure DevOps npm feeds, optionally using th To get `azdo-npm-auth` to create the necessary user `.npmrc` file, run the following command: ```shell -npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth +npx -y --registry https://registry.npmjs.org azdo-npm-auth ``` -You might be wondering what the `npm_config_registry=https://registry.npmjs.org` part is for. It is a way to ensure that the `npx` command uses the **public** npm registry to install `azdo-npm-auth`. Without this, you might encounter an error like below: +You might be wondering what the `--registry https://registry.npmjs.org` part is for. It is a way to ensure that the `npx` command uses the **public** npm registry to install `azdo-npm-auth`. Without this, you might encounter an error like below: ```shell npm error code E401 @@ -29,26 +29,28 @@ npm error To correct this please try logging in again with: npm error npm login ``` -If you're catering for Windows users that do not use Bash then you might need to introduce a `npx cross-env` prefix: +It is possible to use environment variables to control the `registry` setting as well; consider the following (non-Windows compatible) example: ```shell -npx cross-env npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth +npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth ``` -### "No parse"-mode / manually supplying `organization`, `project`, and `feed` +But the `--registry` flag is the recommended approach. -If you would like to manually supply the `organization`, `project`, and `feed` values, you can do so. In this mode of operation `azdo-npm-auth` will not attempt to parse the `.npmrc` file, and will use the supplied values to build a user `.npmrc` file. +### "No parse"-mode / manually supplying `organization`, `feed` and `project` -If your feed is project-scoped, you will need to supply the `project` value: +If you would like to manually supply the `organization`, `feed` and (optionally) `project` values, you can do so. In this mode of operation `azdo-npm-auth` will not attempt to parse the **project** `.npmrc` file, and will use the supplied values to build a **user** `.npmrc` file. + +If your feed is organization-scoped, you will **not** need to supply the `project` value: ```shell -npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth --organization johnnyreilly --project my-project --feed project-feed-name +npx -y --registry https://registry.npmjs.org azdo-npm-auth --organization johnnyreilly --feed organization-feed-name ``` -If your feed is organization-scoped, you will **not** need to supply the `project` value: +If your feed is project-scoped, you will need to supply the `project` value: ```shell -npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth --organization johnnyreilly --feed organization-feed-name +npx -y --registry https://registry.npmjs.org azdo-npm-auth --organization johnnyreilly --project my-project --feed project-feed-name ``` ## Integration with `package.json` @@ -59,7 +61,7 @@ We generally advise setting up a custom npm script like the one below: ```json "scripts": { - "auth": "npm_config_registry=https://registry.npmjs.org npx --yes azdo-npm-auth" + "auth": "npx -y --registry https://registry.npmjs.org azdo-npm-auth" }, ``` @@ -73,7 +75,7 @@ First the bad news. The below **won't** work: ```json "scripts": { - "preinstall": "npm_config_registry=https://registry.npmjs.org npx --yes azdo-npm-auth" + "preinstall": "npx -y --registry https://registry.npmjs.org azdo-npm-auth" }, ``` @@ -154,7 +156,7 @@ When you are attempting to install from private feeds, npm will commonly error o This section exists to list some classic errors you might encounter when you try to `npm i`. Regardless of the error, the remedy is generally: ```shell -npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth +npx -y --registry https://registry.npmjs.org azdo-npm-auth ``` ### User `.npmrc` not found