From 6ae9cc91d384be00432a77673ee1bd8fd24fc7a3 Mon Sep 17 00:00:00 2001 From: "Alejandro R. Mosteo" Date: Mon, 15 Jan 2024 23:47:05 +0100 Subject: [PATCH] Document PAT creation and hint in `alr publish` help --- doc/publishing.md | 24 ++++++++++++++++++++++++ src/alr/alr-commands-publish.ads | 6 +++++- 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/doc/publishing.md b/doc/publishing.md index da82f11f3..0e68f6871 100644 --- a/doc/publishing.md +++ b/doc/publishing.md @@ -22,6 +22,30 @@ index on GitHub on your behalf. Read on for the details underlying these automated steps, or in case you need to perform further tweaking. +## Creating a Github Personal Access Token + +A Personal Access Token (PAT) allows Alire to act on your behalf to fork the +community index, push the new release manifest to a new branch in your own fork, +and finally open a pull-request against the community repository. + +The PAT, once created, is a plain string. You can either export the environment +variable `GH_TOKEN` set to this string, or provide it when Alire asks for it. + +There are two kinds of PATs on Github: classic and fine-grained. The latter are +in beta and not documented here yet. Follow these steps to create a classic PAT: + +1. On the main https://github.com page, after having logged in, click on your + profile photo on the top-right corner. +1. Click on "Settings" in the list of options in the profile menu. +1. Click on "Developer settings" entry at the bottom in your Settings page. +1. Click on "Personal access tokens" and then "Tokens (classic)". +1. Click on "Generate new token" and the select the classic variant. +1. In the "Select scopes" section, under "repo", check "public_repo". This is + the only permission needed for this PAT. +1. Click on "Generate token" at the bottom. + +You will get the PAT string after completing the generation. + ## General concepts The community index is a collection of diff --git a/src/alr/alr-commands-publish.ads b/src/alr/alr-commands-publish.ads index b56500ee3..3ca816a4b 100644 --- a/src/alr/alr-commands-publish.ads +++ b/src/alr/alr-commands-publish.ads @@ -20,7 +20,7 @@ package Alr.Commands.Publish is function Long_Description (Cmd : Command) return AAA.Strings.Vector is (AAA.Strings.Empty_Vector - .Append ("Checks a release and generates an index manifest") + .Append ("Checks a release and generates an index manifest.") .New_Line .Append ("See full details at") .New_Line @@ -34,6 +34,10 @@ package Alr.Commands.Publish is & " issue `alr publish` after committing and pushing" & " the new release version.") .New_Line + .Append ("See the above link for instructions on how to create a " + & "Github Personal Access Token (PAT), needed to allow `alr` to " + & "interact with Github (forking, PR creation) on your behalf.") + .New_Line .Append ("Use --tar to create a source archive ready to be uploaded.") .New_Line .Append ("Use --manifest to use metadata in a non-default file.")