feat!: Support workflow dispatch run details in response

[LinaKACI-pro]

BREAKING CHANGE: CreateWorkflowDispatchEventByID and CreateWorkflowDispatchEventByFileName now return *WorkflowDispatchRunDetails.

Summary

Resolves #4027

• Added ReturnRunDetails field to CreateWorkflowDispatchEventRequest to support the new return_run_details API parameter
• Added CreateWorkflowDispatchEventResponse struct with WorkflowRunID, RunURL, and HTMLURL fields
• Updated CreateWorkflowDispatchEventByID and CreateWorkflowDispatchEventByFileName to return (*CreateWorkflowDispatchEventResponse, *Response, error) instead of (*Response, error)
• Updated max inputs comment from 10 to 25 to match current API docs
• Added tests for both ReturnRunDetails: true (200 OK with body) and omitted (204 No Content) cases

Breaking change

The method signatures for CreateWorkflowDispatchEventByID and CreateWorkflowDispatchEventByFileName changed from returning (*Response, error) to (*CreateWorkflowDispatchEventResponse, *Response, error).

API reference

https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event

Manual test

Tested against a real repository with a workflow_dispatch workflow using the following program:
To reproduce, create a test program in a separate directory and use go.mod replace to point to the local changes:

mkdir /tmp/test_dispatch && cd /tmp/test_dispatch
go mod init test_dispatch
go mod edit -replace github.com/google/go-github/v83=/path/to/your/local/go-github
go mod tidy

Then run:

go run main.go -owner <owner> -repo <repo> -workflow <workflow.yml> -token <token>

Test program

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"flag"
	"fmt"
	"io"
	"net/http"
	"os"

	"github.com/google/go-github/v83/github"
)

type loggingTransport struct{}

func (t *loggingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
	fmt.Printf("\n--- REQUEST ---\n")
	fmt.Printf("%s %s\n", req.Method, req.URL)
	for k, v := range req.Header {
		fmt.Printf("%s: %s\n", k, v)
	}
	if req.Body != nil {
		bodyBytes, _ := io.ReadAll(req.Body)
		req.Body.Close()
		var pretty bytes.Buffer
		if json.Indent(&pretty, bodyBytes, "", "  ") == nil {
			fmt.Printf("Body:\n%s\n", pretty.String())
		} else {
			fmt.Printf("Body: %s\n", string(bodyBytes))
		}
		req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
	}

	resp, err := http.DefaultTransport.RoundTrip(req)
	if err != nil {
		return resp, err
	}

	fmt.Printf("\n--- RESPONSE ---\n")
	fmt.Printf("Status: %s\n", resp.Status)
	if resp.Body != nil {
		bodyBytes, _ := io.ReadAll(resp.Body)
		resp.Body.Close()
		if len(bodyBytes) > 0 {
			var pretty bytes.Buffer
			if json.Indent(&pretty, bodyBytes, "", "  ") == nil {
				fmt.Printf("Body:\n%s\n", pretty.String())
			} else {
				fmt.Printf("Body: %s\n", string(bodyBytes))
			}
		} else {
			fmt.Println("Body: (empty)")
		}
		resp.Body = io.NopCloser(bytes.NewReader(bodyBytes))
	}
	fmt.Println()

	return resp, nil
}

func main() {
	owner := flag.String("owner", "", "Repository owner")
	repo := flag.String("repo", "", "Repository name")
	workflow := flag.String("workflow", "", "Workflow filename")
	ref := flag.String("ref", "main", "Git ref (default: main)")
	token := flag.String("token", "", "GitHub token (or set GITHUB_TOKEN)")
	flag.Parse()

	if *owner == "" || *repo == "" || *workflow == "" {
		fmt.Println("Usage: test_dispatch -owner <owner> -repo <repo> -workflow <file> [-ref <branch>] [-token <token>]")
		os.Exit(1)
	}

	t := *token
	if t == "" {
		t = os.Getenv("GITHUB_TOKEN")
	}
	if t == "" {
		fmt.Println("Error: provide -token flag or set GITHUB_TOKEN env var")
		os.Exit(1)
	}

	httpClient := &http.Client{Transport: &loggingTransport{}}
	client := github.NewClient(httpClient).WithAuthToken(t)

	fmt.Println("=== Test 1: ReturnRunDetails = true ===")
	event := github.CreateWorkflowDispatchEventRequest{
		Ref:              *ref,
		ReturnRunDetails: github.Ptr(true),
		Inputs:           map[string]any{"name": "go-github-test"},
	}

	resp, _, err := client.Actions.CreateWorkflowDispatchEventByFileName(
		context.Background(), *owner, *repo, *workflow, event,
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("\nWorkflow Run ID: %d\n", resp.GetWorkflowRunID())
	fmt.Printf("Run URL: %s\n", resp.GetRunURL())
	fmt.Printf("HTML URL: %s\n", resp.GetHTMLURL())

	fmt.Println("\n=== Test 2: ReturnRunDetails omitted ===")
	event2 := github.CreateWorkflowDispatchEventRequest{
		Ref:    *ref,
		Inputs: map[string]any{"name": "go-github-test-no-details"},
	}

	resp2, _, err := client.Actions.CreateWorkflowDispatchEventByFileName(
		context.Background(), *owner, *repo, *workflow, event2,
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("\nWorkflowRunID is nil: %v\n", resp2.WorkflowRunID == nil)
	fmt.Printf("RunURL is nil: %v\n", resp2.RunURL == nil)
	fmt.Printf("HTMLURL is nil: %v\n", resp2.HTMLURL == nil)

	fmt.Println("\nAll tests passed!")
}

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[rmacklin]

Nice, thanks for working on this - I saw the GitHub Changelog post about this yesterday and was planning to contribute this today but you beat me to it! I'm excited to remove our project's workaround for getting the run URL once this is merged and released!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.10%. Comparing base (92a3830) to head (40a1676).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4028      +/-   ##
==========================================
+ Coverage   94.07%   94.10%   +0.02%     
==========================================
  Files         207      207              
  Lines       19163    19207      +44     
==========================================
+ Hits        18028    18074      +46     
+ Misses        936      935       -1     
+ Partials      199      198       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gmlewis]

Thank you, @LinaKACI-pro!
LGTM.
Awaiting second LGTM+Approval from any other contributor to this repo before merging.

cc: @stevehipwell - @alexandear - @zyfy29 - @Not-Dhananjay-Mishra

[gmlewis]

Excellent! Thank you, @LinaKACI-pro!
LGTM.
Awaiting second LGTM+Approval from any other contributor to this repo before merging.

cc: @stevehipwell - @alexandear - @zyfy29 - @Not-Dhananjay-Mishra

[stevehipwell]

LGTM

[stevehipwell]

LGTM

[gmlewis]

No need to force push, just FYI.

[Not-Dhananjay-Mishra]

LGTM 🚀

[gmlewis]

Thank you, everyone!
Merging.

[LinaKACI-pro]

Thank you everyone!🚀

[rmacklin]

@gmlewis Just curious - do you know when you'll cut a new release that includes this?

[gmlewis]

@gmlewis Just curious - do you know when you'll cut a new release that includes this?

We typically make releases about once per month (which would mean the next one is in about 3 weeks), but if people ask for a release earlier than that, we can usually accomodate such requests. Right now we have a bunch of PRs in-flight and it might be nice to get those in... feel free to help with code reviews if you have time, and please let me know if you need a release earlier than in 3 weeks.

[rmacklin]

Sounds good! I'm definitely eager for this one but certainly understand waiting to get some other in-flight work across the finish line. Thanks for the answer! (and for all the hard work maintaining this library!)

[sunggun-yu]

Yeah, I'm eager for this feature! It will make my proj way easier. Looking forward to it!!!

[gmlewis]

Yeah, I'm eager for this feature! It will make my proj way easier. Looking forward to it!!!

OK, two requests sound good enough to me. I'll work on a release today or tomorrow after I take a look at what PRs are currently in-flight and hopefully close-to-merging.

[gmlewis]

@rmacklin and @sunggun-yu - this is now released here:
https://github.com/google/go-github/releases/tag/v84.0.0

[rmacklin]

Awesome, thank you!!

[sunggun-yu]

Thank you!