flux2
flux2 copied to clipboard
fluxcd
flux bootstrap github - Scopes
The documentation doesn't mention which scopes are needed for the Github PAT. Is it possible to add this information?
In the Getting Started guide, https://fluxcd.io/docs/get-started/#before-you-begin
A GitHub personal access token with repo permissions. See the GitHub documentation on creating a personal access token.
To be specific, even if you intend to use Flux in read-only mode, the repo permissions for the PAT should be for full read/write. This is because Flux writes to the repo, in order to set up SSH Deploy Keys. You can decide at bootstrap time whether the permissions for the Deploy Key should be read-only or read-write. (It is read-only by default.)
Hope this helps! Let us know if there's somewhere else you were expecting to find this information, then we can add it.
@don4of4 are you referring to the these docs? https://fluxcd.io/docs/installation/#github-and-github-enterprise
@stefanprodan It looks like I created this issue from this page: https://fluxcd.io/docs/cmd/flux_bootstrap_github/
Perhaps a reference could be added from here to the full doc page -- I do see this is documented fairly well on https://fluxcd.io/docs/installation/#github-and-github-enterprise
Thank you both.
The getting started guide does not mention anything about this.
https://fluxcd.io/docs/get-started
@drozzy Can you please elaborate? What's missing / what did you expect to see and where?
The note about the Access Token and that it requires repo-permission is at the top of the Getting Started guide.
You are right, I missed that. Thanks for pointing it out. I think perhaps "Objectives" should go first, and "Before you begin" should go second. Because the eye naturally scans the page and skips past objectives. So anything above that seems optional.
Thanks for the feedback. You're not the first person that missed this information, so it's helpful to hear! We can consider reordering the structure of the docs, that's a pretty reasonable suggestion and makes sense to me.
Perhaps it would make sense to just remove "before you begin" entirely and move the mention about repo tokens into the "Export your credentials" section. Then move kubernetes cluster into its own section. E.g.:
- Objectives
- Export your credentials (with mention that access token should have "repo" premissions")
- Install Kubernetes
- Install the Flux CLI
- Check your Kubernetes cluster
- Install Flux onto your cluster
- Etc.
Ehm, flux tries to create a deploy key which means that the token user must have Admin permissions.
@stefanprodan Is there a proper way to bootstrap with pre-existing deploy key? Without the dance of manual secret creation?
@pkit Yes there is a --private-key-file=<path/to/private.key> option, see https://fluxcd.io/flux/installation/#generic-git-server
@stefanprodan It's not clear that it applies to github too...
Because when I tried --token-auth=true it was still creating a deploy key...
It does apply to the generic bootstrap flux bootstrap git, git not github, not sure how to make the docs clear, the GitHub/GitLab sections are way below
For fine-grained (beta) tokens, I think the minimum I need for bootstrap to github is
Read access to metadata
Read and Write access to administration and code
Specifically
Administration
Repository creation, deletion, settings, teams, and collaborators.
Read and Write
Contents
Repository contents, commits, branches, downloads, releases, and merges.
Read and Write
Metadata mandatory
Search repositories, list collaborators, and access repository metadata.
Read-only
There needs to be more detail on GitHub token scopes in the getting started page with visual and/or use case examples. Three words in passing are not enough and assuming devs have used personal tokens with GitHub is a bad assumption. This is the difference between a quick start and one that takes an extra half hour for the extra research involved. Not to mention the potential mistakes for token creation if the incorrect settings are used. Put yourself in your new users' shoes, do them a favor, and expand the thinking around flux CD use and configuration requirements.
