new install gives "validation error for OrgRepositoryRef.Organization: field is required"

[seanw2020]

Describe the bug

new install gives "validation error for OrgRepositoryRef.Organization: field is required"

To Reproduce

Steps to reproduce the behaviour:

1. Open public GitHub free account
2. Follow instructions here: https://fluxcd.io/docs/get-started/
3. Issue this command:

  source ~/.gitcreds  # contains export GITHUB_USER=... and export GITHUB_TOKEN=...
  flux bootstrap github \
  ‐‐owner=${GITHUB_USER} \
  ‐‐repository=fleet-infra \
  ‐‐branch=main \
  ‐‐path=./clusters/my‐cluster

4. Get this error

   ► connecting to github.com
   ✗ failed to get Git repository "https://github.com//": multiple errors occurred: 
   - validation error for OrgRepositoryRef.Organization: field is required
   - validation error for OrgRepositoryRef.RepositoryName: field is required

Expected behavior

The output in the URL above

Logs

Additional context

► checking prerequisites
✔ kubectl 1.21.2 >=1.18.0-0
✔ Kubernetes 1.20.7-eks-8be107 >=1.16.0-0
► checking controllers
✔ all checks passed

flux --version
flux version 0.16.1

[kingdonb]

Thank you for the report!

I think from a UX perspective it's certainly true that the error message could be clearer about what has gone wrong here, perhaps a hint that passing --personal is not the default mode of bootstrapping will have got you to the answer quicker.

I will highlight in the Getting Started guide, the use of --personal is demonstrated in the first example, for use with repositories that do not belong to a team or github organization. Users who bootstrap with such a repo should pass this flag, otherwise the flux cli assumes you are trying to bootstrap an Org repo by default. The flux bootstrap github docs page also shows several combinations of params which produce a valid bootstrap sequence.

We generally do expect Flux users to read the guides before using Flux, (first "Getting Started," but also flux2-kustomize-helm-example and flux2-multi-tenancy linked at the end of the first guide) as there are many other important features covered in these guides that are hard for users to discover in the course of simply picking up Flux and using it.

We also recognize the desire for a tool that may address this concern more broadly ("flux is quite difficult to simply pick up and use"). To make gitops more accessible to everyone, I'd like to mention that we have released Weave GitOps, a developer-focused tool that is based heavily on Flux v2, with docs here and source/issues here. If you are new to Flux and struggling with adoption, maybe this will help!

[kingdonb]

(Transferring to the fluxcd/flux2 repo, as this is not a report about Flux v1.)

Whoops, I do not actually have permission to transfer issues to fluxcd/flux2. I don't think it needs to be transferred though, as there is not a bug except for possibly UX.

[seanw2020]

Hmm, after trying the examples you cited at flux bootstrap github docs page, specifically if I add --personal I get the same error. Ditto with --private=true:

  source ~/.gitcreds
  flux bootstrap github \
  ‐‐owner=${GITHUB_USER} \
  ‐‐repository=fleet-infra \
  ‐‐branch=main \
  ‐‐path=./clusters/my‐cluster \
  --personal

► connecting to github.com
✗ failed to get Git repository "https://github.com//": multiple errors occurred: 
- validation error for UserRepositoryRef.UserLogin: field is required
- validation error for UserRepositoryRef.RepositoryName: field is required

  source ~/.gitcreds
  flux bootstrap github \
  ‐‐owner=${GITHUB_USER} \
  ‐‐repository=fleet-infra \
  ‐‐branch=main \
  ‐‐path=./clusters/my‐cluster \
  --personal=true \
  --private=false

► connecting to github.com
✗ failed to get Git repository "https://github.com//": multiple errors occurred: 
- validation error for UserRepositoryRef.UserLogin: field is required
- validation error for UserRepositoryRef.RepositoryName: field is required

[seanw2020]

I found the problem. The path was incorrect, since, as you mentioned, I hadn't cloned the repository. Given that, I see this as a documentation bug and arguably a code bug (if the path is incorrect, catch that exception). For the documentation, I'd suggest something like this:

After "Run the bootstrap command", add this:

    git clone git@github.com:fluxcd/flux2-kustomize-helm-example.git
    cd flux2-kustomize-helm-example

For personal GitHub personal account (i.e., not a GitHub organization), do this:

    flux bootstrap github \
      --owner=${GITHUB_USER} \
      --repository=fleet-infra \
      --branch=main \
      --personal \
      --path=clusters/staging

For GitHub organization account (i.e., not GitHub personal account), do this:

flux bootstrap github \
  --owner=${GITHUB_USER} \
  --repository=fleet-infra \
  --branch=<organization default branch> \
  --team=<team1-slug> \
  --team=<team2-slug> \
  --path=clusters/my-cluster

[kingdonb]

I don't know if you saw this, but in both of the commands you pasted which you said error out for you, there appear to be several different types of (some are in unicode) dashes:

source ~/.gitcreds
  flux bootstrap github \
  ‐‐owner=${GITHUB_USER} \
  ‐‐repository=fleet-infra \
  ‐‐branch=main \
  ‐‐path=./clusters/my‐cluster \
  --personal

I find via this website https://www.babelstone.co.uk/Unicode/whatisit.html:

U+2010 : HYPHEN
U+002D : HYPHEN-MINUS {hyphen or minus sign}

Did you perhaps copy this command from a source that converts ASCII dashes into unicode hyphens? To Flux, this looks like the owner and repository parameters are missing.

I don't think you need to have cloned anything. If you try typing the bootstrap commands into a terminal by hand, with the keyboard (ascii) hyphen, do you get better results?

[kingdonb]

I'm not sure how we should address that, if it turns out to have been the whole cause of your error.

If you copied it from a flux doc, we will definitely adjust it to make sure the correct (ascii) dashes are present, and no unicode hyphens or n-dashes. If it was some other source, arguably Flux should still complain about receiving options which it does not recognize.

[seanw2020]

Whoa, good catch! I re-ran the initial command in this post, after typing the characters manually, and I saw the message you'd initially suspected I'd see:

► connecting to github.com
✗ failed to create new Git repository "https://github.com/REDACTED/fleet-infra": multiple errors occurred: 
- POST https://api.github.com/orgs/REDACTED/repos: 404 Not Found []
- the requested resource was not found

That lead me, as you suspected, to add --personal which then worked.

I'll close this issue. Hopefully, it helps somebody else in a similarly strange setup.

Thanks so much.

UPDATE: I figured out what happened. I had printed the docs page to PDF using PDF mage, a Chrome plugin, so that I can take notes, add screenshots, and make comments for myself. Then I copied and pasted the code from the PDF version, which has always worked in the past, but today that step added the non-ASCII version of the hyphen. I just contacted the author of the extension about this.

Sorry for the false alarm.