feat!: add --head-sha to better control force pushes

To avoid potentially overwriting changes on the remote, allow callers to
specify `--head-sha` (defaulting to the current HEAD on the remote,
which is the previous behavior). This mitigates issues with potentially
overwriting remote changes on long running jobs or active branches,
particularly with jobs that rewrite file contents (such as lint fixes /
auto formatting).

- Replace --branch-from=<sha> with the pair of --head-sha=<sha> and
  --create-branch
- Skip fetching current remote HEAD if --head-sha is supplied

Author: avidal

README.md

@@ -31,18 +31,40 @@ token in one of the following environment variables:
 - GITHUB_TOKEN
 - GH_TOKEN
 
-Note that, by default, both of these commands expect the remote branch to already exist. If your
-workflow primarily works on *new* branches, you should additionally add the `--branch-from` flag and
-supply a commit hash to use as a branch point. With this flag, `commit-headless` will create the
-branch on GitHub from that commit hash if it doesn't already exist.
-
-Example: `commit-headless <command> [flags...] --branch-from=$(git rev-parse main HEAD) ...`
-
 In normal usage, `commit-headless` will print *only* the reference to the last commit created on the
 remote, allowing this to easily be captured in a script.
 
 More on the specifics for each command below. See also: `commit-headless <command> --help`
 
+### Specifying the expected head commit
+
+When creating remote commits via API, `commit-headless` must specify the "expected head sha" of the
+remote branch. By default, `commit-headless` will query the GitHub API to get the *current* HEAD
+commit of the remote branch and use that as the "expected head sha". This introduces some risk,
+especially for active branches or long running jobs, as a new commit introduced after the job starts
+will not be considered when pushing the new commits. The commit itself will not be replaced, but the
+changes it introduces may be lost.
+
+For example, consider an auto-formatting job. It runs `gofmt` over the entire codebase. If the job
+starts on commit A and formats a file `main.go`, and while the job is running the branch gains
+commit B, which adds *new* changes to `main.go`, when the lint job finishes the formatted version of
+`main.go` from commit A will be pushed to the remote, and overwrite the changes to `main.go`
+introduced in commit B.
+
+You can avoid this by specifying `--head-sha`. This will skip auto discovery of the remote branch
+HEAD and instead require that the remote branch HEAD matches the value of `--head-sha`. If the
+remote branch HEAD does not match `--head-sha`, the push will fail (which is likely what you want).
+
+### Creating a new branch
+
+Note that, by default, both of these commands expect the remote branch to already exist. If your
+workflow primarily works on *new* branches, you should additionally add the `--create-branch` flag
+and supply a commit hash to use as a branch point via `--head-sha`. With this flag,
+`commit-headless` will create the branch on GitHub from that commit hash if it doesn't already
+exist.
+
+Example: `commit-headless <command> [flags...] --head-sha=$(git rev-parse main HEAD) --create-branch ...`
+
 ### commit-headless push
 
 In addition to the required target and branch flags, the `push` command expects a list of commit
@@ -100,7 +122,8 @@ git commit --author='A U Thor <[email protected]>' --message="test bot commit"
 HEADLESS_TOKEN=$(ddtool auth github token) commit-headless push \
     --target=owner/repo \
     --branch=bot-branch \
-    --branch-from="$(git rev-parse HEAD^)" \ # use the previous commit as our branch point
+    --head-sha="$(git rev-parse HEAD^)" \ # use the previous commit as our branch point
+    --create-branch \
     "$(git rev-parse HEAD)" # push the commit we just created
 ```
 

action-template/README.md

@@ -46,7 +46,7 @@ If your workflow creates multiple commits and you want to push all of them, you
     commits: "${{ steps.create-commits.outputs.commits }}"
 ```
 
-If you primarily create commits on *new* branches, you'll want to use the `branch-from` option. This
+If you primarily create commits on *new* branches, you'll want to use the `create-branch` option. This
 example creates a commit with the current time in a file, and then pushes it to a branch named
 `build-timestamp`, creating it from the current commit hash if the branch doesn't exist.
 
@@ -67,7 +67,8 @@ example creates a commit with the current time in a file, and then pushes it to
   uses: DataDog/commit-headless@action/v%%VERSION%%
   with:
     branch: build-timestamp
-    branch-from: ${{ github.sha }}
+    head-sha: ${{ github.sha }}
+    create-branch: true
     command: push
     commits: "${{ steps.create-commits.outputs.commit }}"
 ```

action-template/action.js

@@ -46,11 +46,19 @@ function main() {
     "--branch", process.env.INPUT_BRANCH
   ];
 
-  const branchFrom = process.env["INPUT_BRANCH-FROM"] || "";
-  if (branchFrom !== "") {
-    args.push("--branch-from", branchFrom);
+  const headSha = process.env["INPUT_HEAD-SHA"] || "";
+  if (headSha !== "") {
+    args.push("--head-sha", headSha);
   }
 
+  const createBranch = process.env["INPUT_CREATE-BRANCH"] || "false"
+  if(!["true", "false"].includes(createBranch.toLowerCase())) {
+    console.error(`Invalid value for create-branch (${createBranch}). Must be one of true or false.`);
+    process.exit(1);
+  }
+
+  if(createBranch.toLowerCase() === "true") { args.push("--create-branch") }
+
   const dryrun = process.env["INPUT_DRY-RUN"] || "false"
   if(!["true", "false"].includes(dryrun.toLowerCase())) {
     console.error(`Invalid value for dry-run (${dryrun}). Must be one of true or false.`);

action-template/action.yml

@@ -21,8 +21,11 @@ inputs:
     required: true
   working-directory:
     description: 'Switch to this directory before running commit-headless. Useful if you need to commit changes to a secondary repository.'
-  branch-from:
-    description: 'If necessary, create the remote branch using this commit hash as the branch point.'
+  head-sha:
+    description: 'Expected commit sha of the remote branch, or the commit sha to branch from.'
+  create-branch:
+    description: 'Create the remote branch, using head-sha as the branch point.'
+    default: false
   command:
     description: 'Command to run. One of "commit" or "push"'
     required: true

cmd_commit.go

@@ -86,5 +86,5 @@ func (c *CommitCmd) Run() error {
 
 	owner, repository := c.Target.Owner(), c.Target.Repository()
 
-	return pushChanges(context.Background(), owner, repository, c.Branch, c.BranchFrom, c.DryRun, change)
+	return pushChanges(context.Background(), owner, repository, c.Branch, c.HeadSha, c.CreateBranch, c.DryRun, change)
 }

cmd_push.go

@@ -69,5 +69,5 @@ func (c *PushCmd) Run() error {
 
 	owner, repository := c.Target.Owner(), c.Target.Repository()
 
-	return pushChanges(context.Background(), owner, repository, c.Branch, c.BranchFrom, c.DryRun, changes...)
+	return pushChanges(context.Background(), owner, repository, c.Branch, c.HeadSha, c.CreateBranch, c.DryRun, changes...)
 }

github.go

@@ -12,6 +12,8 @@ import (
 	"golang.org/x/oauth2"
 )
 
+var ErrNoRemoteBranch = errors.New("branch does not exist on the remote")
+
 // Client provides methods for interacting with a remote repository on GitHub
 type Client struct {
 	httpC  *http.Client
@@ -61,8 +63,7 @@ func (c *Client) graphqlURL() string {
 }
 
 // GetHeadCommitHash returns the current head commit hash for the configured repository and branch
-// If the branch does not exist (404 return), we'll attempt to create it from commit branchFrom
-func (c *Client) GetHeadCommitHash(ctx context.Context, branchFrom string) (string, error) {
+func (c *Client) GetHeadCommitHash(ctx context.Context) (string, error) {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.branchURL(), nil)
 	if err != nil {
 		return "", fmt.Errorf("prepare http request: %w", err)
@@ -75,11 +76,7 @@ func (c *Client) GetHeadCommitHash(ctx context.Context, branchFrom string) (stri
 	defer resp.Body.Close()
 
 	if resp.StatusCode == http.StatusNotFound {
-		if branchFrom != "" {
-			return c.createBranch(ctx, branchFrom)
-		}
-
-		return "", fmt.Errorf("branch %q does not exist on the remote", c.branch)
+		return "", fmt.Errorf("get branch %q: %w", ErrNoRemoteBranch)
 	}
 
 	if resp.StatusCode != http.StatusOK {
@@ -99,15 +96,15 @@ func (c *Client) GetHeadCommitHash(ctx context.Context, branchFrom string) (stri
 	return payload.Commit.Sha, nil
 }
 
-// createBranch attempts to create c.branch using branchFrom as the branch point
-func (c *Client) createBranch(ctx context.Context, branchFrom string) (string, error) {
-	log("Creating branch from commit %s\n", branchFrom)
+// CreateBranch attempts to create c.branch using headSha as the branch point
+func (c *Client) CreateBranch(ctx context.Context, headSha string) (string, error) {
+	log("Creating branch from commit %s\n", headSha)
 
 	var input bytes.Buffer
 
 	err := json.NewEncoder(&input).Encode(map[string]string{
 		"ref": fmt.Sprintf("refs/heads/%s", c.branch),
-		"sha": branchFrom,
+		"sha": headSha,
 	})
 	if err != nil {
 		return "", err
@@ -256,7 +253,6 @@ func (c *Client) PushChange(ctx context.Context, headCommit string, change Chang
 			log("  - %s\n", e.Message)
 		}
 
-		log("\nInput data, for reference: %s", string(queryJSON))
 		return "", errors.New("graphql response")
 	}
 

main.go

@@ -42,10 +42,11 @@ func (f targetFlag) Repository() string {
 
 // flags that are shared among commands that interact with the remote
 type remoteFlags struct {
-	Target     targetFlag `name:"target" short:"T" required:"" help:"Target repository in owner/repo format."`
-	Branch     string     `required:"" help:"Name of the target branch on the remote."`
-	BranchFrom string     `help:"If necessary, create the remote branch using this commit sha."`
-	DryRun     bool       `name:"dry-run" help:"Perform everything except the final remote writes to GitHub."`
+	Target       targetFlag `name:"target" short:"T" required:"" help:"Target repository in owner/repo format."`
+	Branch       string     `required:"" help:"Name of the target branch on the remote."`
+	HeadSha      string     `name:"head-sha" help:"Expected commit sha of the remote branch, or the commit sha to branch from."`
+	CreateBranch bool       `name:"create-branch" help:"Create the remote branch, requires --head-sha to be set."`
+	DryRun       bool       `name:"dry-run" help:"Perform everything except the final remote writes to GitHub."`
 }
 
 type CLI struct {

pushchanges.go

@@ -10,7 +10,7 @@ import (
 
 // Takes a list of changes to push to the remote identified by target.
 // Prints the last commit pushed to standard output.
-func pushChanges(ctx context.Context, owner, repository, branch, branchFrom string, dryrun bool, changes ...Change) error {
+func pushChanges(ctx context.Context, owner, repository, branch, headSha string, createBranch, dryrun bool, changes ...Change) error {
 	hashes := []string{}
 	for i := 0; i < len(changes) && i < 10; i++ {
 		hashes = append(hashes, changes[i].hash)
@@ -25,8 +25,12 @@ func pushChanges(ctx context.Context, owner, repository, branch, branchFrom stri
 	log("Branch: %s\n", branch)
 	log("Commits: %s\n", strings.Join(hashes, ", "))
 
-	if branchFrom != "" && (!hashRegex.MatchString(branchFrom) || len(branchFrom) != 40) {
-		return fmt.Errorf("cannot branch from %q, must be a full 40 hex digit commit hash", branchFrom)
+	if headSha != "" && (!hashRegex.MatchString(headSha) || len(headSha) != 40) {
+		return fmt.Errorf("invalid head-sha %q, must be a full 40 hex digit commit hash", headSha)
+	}
+
+	if createBranch && headSha == "" {
+		return errors.New("cannot use --create-branch without supplying --head-sha")
 	}
 
 	token := getToken(os.Getenv)
@@ -37,12 +41,21 @@ func pushChanges(ctx context.Context, owner, repository, branch, branchFrom stri
 	client := NewClient(ctx, token, owner, repository, branch)
 	client.dryrun = dryrun
 
-	headRef, err := client.GetHeadCommitHash(context.Background(), branchFrom)
-	if err != nil {
-		return err
+	if headSha == "" {
+		remoteSha, err := client.GetHeadCommitHash(context.Background())
+		if err != nil {
+			return err
+		}
+		headSha = remoteSha
+	} else if createBranch {
+		remoteSha, err := client.CreateBranch(ctx, headSha)
+		if err != nil {
+			return err
+		}
+		headSha = remoteSha
 	}
 
-	log("Current head commit: %s\n", headRef)
+	log("Remote head commit: %s\n", headSha)
 	for _, c := range changes {
 		log("Commit %s\n", c.hash)
 		log("  Headline: %s\n", c.Headline())
@@ -57,7 +70,7 @@ func pushChanges(ctx context.Context, owner, repository, branch, branchFrom stri
 		}
 	}
 
-	pushed, newHead, err := client.PushChanges(ctx, headRef, changes...)
+	pushed, newHead, err := client.PushChanges(ctx, headSha, changes...)
 	if err != nil {
 		return err
 	} else if pushed != len(changes) {

version.go

@@ -1,3 +1,3 @@
 package main
 
-const VERSION = "1.0.0"
+const VERSION = "2.0.0"