Generate helpful error on failed git write check

While starting up, the daemon continually checks whether it can clone
the upstream repo, and if so, whether it can write to it. If this
results in an error, it stores this away and keeps trying. Until it
succeeds, when asked to do anything related to the git repo (i.e.,
almost anything), it responds with the stored error.

In that interim, it's possible that a user will ask for something that
needs a cloned repo; and if so, a helpful error is .. helpful.

git/errors.go

@@ -2,6 +2,7 @@ package git
 
 import (
 	"errors"
+	"strings"
 
 	fluxerr "github.com/weaveworks/flux/errors"
 )
@@ -24,7 +25,7 @@ func CloningError(url string, actual error) error {
 	return &fluxerr.Error{
 		Type: fluxerr.User,
 		Err:  actual,
-		Help: `Problem cloning your git repository
+		Help: `Could not clone the upstream git repository
 
 There was a problem cloning your git repository,
 
@@ -44,6 +45,47 @@ cross-check with the fingerprint given by
 	}
 }
 
+func ErrUpstreamNotWritable(url string, actual error) error {
+	help := `Could not write to upstream repository
+
+To keep track of synchronisation, the flux daemon must be able to
+write to the upstream git repository.
+`
+	if strings.HasPrefix(url, "http://") ||
+		strings.HasPrefix(url, "https://") {
+		help = help + `
+Usually, git URLs starting with "http://" or "https://" will not work
+well with flux, because they require the user to supply credentials
+interactively. If possible, use an SSH URL (starting with "ssh://", or
+of the form "user@host:path/to/repo").
+`
+	} else {
+		help = help + `
+This failure may be due to the SSH (deploy) key used by the daemon not
+having write permission. You can see the key used, with
+
+    fluxctl identity
+
+In GitHub, please check via the repository settings that the deploy
+key is "Read/write". You can cross-check the fingerprint with that
+given by
+
+    fluxctl identity --fingerprint
+
+If the key is present but read-only, you will need to delete it and
+create a new deploy key. To create a new one, use
+
+    fluxctl identity --regenerate
+`
+	}
+
+	return &fluxerr.Error{
+		Type: fluxerr.User,
+		Err:  actual,
+		Help: help,
+	}
+}
+
 func PushError(url string, actual error) error {
 	return &fluxerr.Error{
 		Type: fluxerr.User,
@@ -57,7 +99,8 @@ If this has worked before, it most likely means a fast-forward push
 was not possible. It is safe to try again.
 
 If it has not worked before, this probably means that the repository
-exists but the deploy key provided doesn't have write permission.
+exists but the SSH (deploy) key provided doesn't have write
+permission.
 
 In GitHub, please check via the repository settings that the deploy
 key is "Read/write". You can cross-check the fingerprint with that

git/repo.go

@@ -148,7 +148,10 @@ func (c *Checkout) ManifestDir() string {
 func (c *Checkout) CheckOriginWritable(ctx context.Context) error {
 	c.Lock()
 	defer c.Unlock()
-	return checkPush(ctx, c.repo.KeyRing, c.Dir, c.repo.URL)
+	if err := checkPush(ctx, c.repo.KeyRing, c.Dir, c.repo.URL); err != nil {
+		return ErrUpstreamNotWritable(c.repo.URL, err)
+	}
+	return nil
 }
 
 // CommitAndPush commits changes made in this checkout, along with any