Add note about tokens when working with maven registries

[serpro69]

Why:

From the issue in setup-java action ( actions/setup-java#620 (comment) ), I think this part of documentation could be improved.

It can be a bit confusing when the docs say "you can publish to other repos and no extra steps are needed" w/o re-iterating that GITHUB_TOKEN can't access private repositories and hence can't be used to publish to them.

This improves the documentation a bit by following the "format for scannability" principle for github docs.

Check off the following:

• I have reviewed my changes in staging, available via the View deployment link in this PR's timeline (this link will be available after opening the PR).

  • For content changes, you will also see an automatically generated comment with links directly to pages you've modified. The comment won't appear if your PR only edits files in the data directory.

• For content changes, I have completed the self-review checklist.

[welcome]

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[github-actions]

Automatically generated comment ℹ️

This comment is automatically generated and will be overwritten every time changes are committed to this branch.

The table contains an overview of files in the content directory that have been changed in this pull request. It's provided to make it easy to review your changes on the staging site. Please note that changes to the data directory will not show up in this table.

---

Content directory changes

You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request.

Source	Preview	Production	What Changed
packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry.md	fpt ghec ghes@ 3.12 3.11 3.10 3.9	fpt ghec ghes@ 3.12 3.11 3.10 3.9

---

fpt: Free, Pro, Team
ghec: GitHub Enterprise Cloud
ghes: GitHub Enterprise Server

[nguyenalex836]

@serpro69 Thanks so much for opening a PR! I'll get this triaged for review ✨

[vgrl]

Thanks for your contribution @serpro69 !

It can be a bit confusing when the docs say "you can publish to other repos and no extra steps are needed" w/o re-iterating that GITHUB_TOKEN can't access private repositories and hence can't be used to publish to them.

Can you expand on where our docs make the above statement? I'd like to consider whether making a change to that part of the docs would be beneficial, and also more valuable than adding a callout.

I'm hesitant to add more details about authentication into other sections (beyond "Authenticating to GitHub Packages") of the "Working with the Apache Maven registry" article, as the article is already quite long and we'd like to maintain consistency with our other "Working with..." package registry articles in the Packages docset.

We also do link to our main article "About permissions for GitHub Packages", where we mention using packages in GitHub Actions workflows.

• To install packages associated with other private repositories that GITHUB_TOKEN can't access, use a personal access token (classic)

Any additional info or context beyond the issue you already linked to support your proposed change is much appreciated! 🙏

[serpro69]

Hi @vgrl ,
Thanks for the comment. I can definitely see your point 🙂

Can you expand on where our docs make the above statement? I'd like to consider whether making a change to that part of the docs would be beneficial, and also more valuable than adding a callout.

In the publishing a package section:

If you would like to publish multiple packages to the same repository, you can include the URL of the repository in the element of the pom.xml file. GitHub will match the repository based on that field. Since the repository name is also part of the distributionManagement element, there are no additional steps to publish multiple packages to the same repository.

When I read this now, knowing that I need to use a PAT, I see the "no additional steps" is meant in the context of setting up the target repo.
But when I didn't know about the PAT, I read this slightly differently.

We also do link to our main article "About permissions for GitHub Packages", where we mention using packages in GitHub Actions workflows.

Yes, I know. But as github's best practices for docs: "Most readers don't consume articles in their entirety. Instead they either scan the page to locate specific information, or skim the page to get a general idea of the concepts." 🙂

In addition, the link you mention actually leads to a different section of that page, particularly the "About permissions for GitHub Packages." section.

For more information about packages-related scopes for a personal access token (classic), see "About permissions for GitHub Packages."

And that section, again, is not very clear on the need of PAT for private repos and only says:

To use or manage a package hosted by a package registry, you must use a personal access token (classic) with the appropriate scope, and your personal account must have appropriate permissions.
...
When you create a GitHub Actions workflow, you can use the GITHUB_TOKEN to publish, install, delete, and restore packages in GitHub Packages without needing to store and manage a personal access token.

And to actually get the info on the need of PAT, the person would need to go to the bottom of the page and get to
https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages#maintaining-access-to-packages-in-github-actions-workflows , where it does mention cases where PAT must be used.

So all in all, from my POV, I'd say that it's a bit confusing, because some places of the docs just say "use either PAT or GITHUB_TOKEN". And then there's only one sentence that says "To install packages associated with other private repositories that GITHUB_TOKEN can't access, use a personal access token (classic)", which I'd say is not enough to make this point clear and can be easily overlooked.

At the very least, this shouldn't be a bullet-point, but should be highlighted with a > [!NOTE] IMO.

So then maybe you could consider changing this part:

• To publish, install, delete, and restore packages associated with the workflow repository, use GITHUB_TOKEN.
• To install packages associated with other private repositories that GITHUB_TOKEN can't access, use a personal access token (classic)

Particularly, getting rid of the bullet-points and highlighting the need for PAT in certain scenarios would probably make it more readable and less prone to being overlooked?

I hope this rant made some sense, tied to explain this as clear as possible 🙂 But of course this is also quite subjective, and it could be just me who doesn't read the docs thoroughly and in their entirety 😁 But as you mention, the docs are quite long, and I think it would be beneficial to make them more easy to understand. I do think that this use-case is quite common, especially in orgs that use packages as their main artifact registry, and I'm sure I'm not the only one who scratched their head on why this doesn't work before figuring out the PAT part 😁

[nguyenalex836]

@serpro69 Howdy! 👋 Just wanted to pop in with a quick question -

Since the repository name is also part of the distributionManagement element, there are no additional steps to publish multiple packages to the same repository.

I think there's a possibility that “same repo” might have been misread as “other private repos” in that sentence 💛 Would you be able to confirm if that is / is not the case? Thank you so much! ✨

[serpro69]

I think there's a possibility that “same repo” might have been misread as “other private repos” in that sentence 💛 Would you be able to confirm if that is / is not the case? Thank you so much! ✨

Hi @nguyenalex836 ,

The way I understand "same repository" is - single repository that holds multiple different packages from other repositories. There's no mention of public vs private here.
But I hope you can see yourself the ambiguity of this sentence :) "Same repository" could really mean either "same public repository" or "same private repository". At the same time, from usage perspective, publishing to "same public repository" is not the same as publishing to "same private repository", and the latter has a dependency on the PAT.

Again, for my part, I don't benefit from this particular documentation update because now I've figured it out. But I thought to spare others the pain of trying to figure out how to publish to "same private repositories", because IMO the docs could really be improved a bit for this scenario. But the choice of course is yours :)

[nguyenalex836]

@serpro69 Thank you very much for the thorough response and clarification! ✨ We are continuing to review 💛

[nguyenalex836]

@serpro69 Thank you so much for flagging this! After consulting with the team, we will need to discuss this further and update the doc internally, given the number of moving pieces involved here 💛

I'll go ahead and close this PR, but if you're looking for another issue to pick up, take a look at our help wanted section to find open issues you can work on ✨ thanks again!