Improve documentation for PAT usage

[spenserblack]

The PAT usage documentation is vague (what scopes are needed? Fine-grained, classic or either?).

[quazar-omega]

I got around to it only now, I had success just with the classic token, I set these permissions for mine (honestly I just put random stuff that I felt was somehow relevant):

• Classic
  • [x] repo
    • [x] repo:status
    • [x] repo_deployment
    • [x] public_repo
    • [x] repo:invite
    • [x] security_events
  • [x] workflow
  • [x] admin:repo_hook
    • [x] write:repo_hook
    • [x] read:repo_hook
  • [x] project
    • [x] read:project

• Fine-grained:

  Feature	Permissions
  Actions	rw
  Commit stauses	rw
  Contents	rw
  Deployments	rw
  Environments	rw
  Metadata	r
  Pull requests	rw
  Secrets	rw
  Variables	rw
  Webhooks	r
  Workflows	rw

This is the error I got with this configuration:

fatal: could not read Password for 'https://***@github.com': No such device or address
Error: Process completed with exit code 128.

After typing it out I do realize that it's very far fetched, but seeing as nothing worked I just had to try and go crazy with them

[spenserblack]

Thanks for doing this research! Apparently fine-grained tokens require a different format: https://stackoverflow.com/questions/74532852/github-clone-repo-with-fine-grained-personal-access-tokens-pat

So I could be lazy and say that if you want to use a fine-grained token you should do

with:
  token: 'oauth2:${{ secrets.WIKI_TOKEN }}'

:laughing:

Though I should probably add a true/false input for if it's a fine-grained token or not (perhaps that could be found out automatically with pattern-matching :thinking:)

I've narrowed the classic token down to just all of the repo tokens checked, but hopefully I can narrow it down further.

[spenserblack]

OK, it looks like only public_repo is needed for public repositories. Based on the scope descriptions, I suppose repo access must be granted if the wiki belongs to a private repo.

For now, I'll update the docs for classic tokens, and I'll consider fine-grained tokens to be a separate issue. Thanks for your help!

[spenserblack]

@all-contributors add @quazar-omega for usertesting

[allcontributors[bot]]

@spenserblack

I've put up a pull request to add @quazar-omega! :tada:

[quazar-omega]

Ohh wow, ok, I would have never figured that out ( ༎ຶ ‿ ༎ຶ)

I've narrowed the classic token down to just all of the repo tokens checked, but hopefully I can narrow it down further.

Yeah, that makes sense actually

Though I should probably add a true/false input for if it's a fine-grained token or not

Since Actions are versioned maybe at some point it wouldn't hurt to make a breaking change and use only fine grained tokens, maybe when they come out of beta, but in the meantime I agree, it could work. It seems like they follow a pattern like this:

• classic /^ghp_.*$/
• fine-grained /^github_pat_.*$/

[quazar-omega]

OK, it looks like only public_repo is needed for public repositories. Based on the scope descriptions, I suppose repo access must be granted if the wiki belongs to a private repo.

For now, I'll update the docs for classic tokens, and I'll consider fine-grained tokens to be a separate issue.

Sounds good!

Thanks for your help!

Don't mention it, you basically figured it out yourself haha 😅

[spenserblack]

Since Actions are versioned maybe at some point it wouldn't hurt to make a breaking change and use only fine grained tokens, maybe when they come out of beta, but in the meantime I agree, it could work.

Good idea :+1: I think it's worth a breaking change to enforce more secure tokens :laughing: Currently, not too many users would be affected by a breaking change, anyway :upside_down_face:

[quazar-omega]

@spenserblack

I've put up a pull request to add @quazar-omega! tada

Uhm, I'm confused, I am supposed to do something?

[quazar-omega]

Good idea 👍 I think it's worth a breaking change to enforce more secure tokens 😆

Yeah, exactly my thought process

Currently, not too many users would be affected by a breaking change, anyway 🙃

True, it's a good position to be in though, so we can start fresh and safe!

[spenserblack]

Uhm, I'm confused, I am supposed to do something?

I triggered all-contributors to add you as a a contributor for user testing. You don't need to do anything.

See https://github.com/spenserblack/actions-wiki/blob/a6ef4bbcb28cfa496c2bde603bc771c76702d73f/CREDITS.md

I use all-contributors when members of the GH community help out in ways that can't be represented with commit stats 🙂

[quazar-omega]

I understand now, didn't know what all-contributors was exactly about, thank you for that!

[jcbhmr]

Still having issues with this due to improper happy-path usage of a ${{ github.token }} token:

I'd like to note that currently

https://github.com/spenserblack/actions-wiki/blob/98f0591597022a21b68f6ea435b34b20e2157ca8/action.yml#L33

you use the https://TOKEN@github.com/user/repo format, when it should be https://USER:TOKEN@github.com/user/repo for constructing the auth URL so that the TOKEN part is in the password slot of the user:password auth thing. https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#using-a-personal-access-token-on-the-command-line

Once you have a token, you can enter it instead of your password when performing Git operations over HTTPS.

For example, on the command line you would enter the following:

$ git clone https://github.com/USERNAME/REPO.git
Username: YOUR_USERNAME
Password: YOUR_TOKEN

in this case, I think you can use $GITHUB_ACTOR to use the current trigger-er user as the username. That's what I think is best practice (I vaguely remember seeing that pattern used before) but I can't point to a specific "best practice because $X does it this way" on this. The alternative is GITHUB_REPOSITORY_OWNER which doesn't seem as semantically correct but idk.

the error makes sense that "cant find password" would mean that it literally cant find the password since its in the username slot misplaced...

— https://github.com/spenserblack/actions-wiki/issues/2#issuecomment-1466627982

---

case-in-point: this fixed it:

jobs:
  publish-wiki:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: spenserblack/actions-wiki@v0.1.1
        with:
          token: ${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}
          wiki-directory: wiki

don't know if this comment belongs here or in #2