feat: add GitHub Check Runs for deployment authorization PR visibility

GitHub Deployments only appear in the PR Environments section. This adds
Check Runs via the Checks API so blocked deployments show a prominent
yellow "action_required" badge in the PR checks list. On authorization,
the check run is updated to green success.

Author: Flo4604

svc/ctrl/services/deployment/authorize_deployment.go

@@ -41,7 +41,7 @@ func (s *Service) AuthorizeDeployment(ctx context.Context, req *connect.Request[
 		return nil, connect.NewError(connect.CodeInternal, fmt.Errorf("failed to fetch branch HEAD from GitHub: %w", err))
 	}
 
-	// Re-derive all matching deploy contexts (same query handle_push uses)
+	// Find all deploy contexts for this branch
 	contexts, err := db.Query.ListRepoConnectionDeployContexts(ctx, s.db.RO(), db.ListRepoConnectionDeployContextsParams{
 		InstallationID: repoConn.InstallationID,
 		RepositoryID:   repoConn.RepositoryID,
@@ -178,5 +178,23 @@ func (s *Service) AuthorizeDeployment(ctx context.Context, req *connect.Request[
 		)
 	}
 
+	// Mark the PR check run as green now that the deployment is authorized
+	checkRuns, listErr := s.github.ListCheckRunsForRef(repoConn.InstallationID, repoConn.RepositoryFullName, headCommit.SHA, "Unkey Deployment Authorization")
+	if listErr == nil {
+		for _, cr := range checkRuns {
+			if updateErr := s.github.UpdateCheckRun(
+				repoConn.InstallationID,
+				repoConn.RepositoryFullName,
+				cr.ID,
+				"completed",
+				"success",
+				"Deployment authorized",
+				"Deployment authorized and started by a project member.",
+			); updateErr != nil {
+				logger.Error("failed to update check run to success", "check_run_id", cr.ID, "error", updateErr)
+			}
+		}
+	}
+
 	return connect.NewResponse(&ctrlv1.AuthorizeDeploymentResponse{}), nil
 }

svc/ctrl/worker/github/client.go

@@ -333,6 +333,93 @@ func (c *Client) CreateDeploymentStatus(installationID int64, repo string, deplo
 	return httpclient.Do(c.httpClient, http.MethodPost, apiURL, headers, payload, http.StatusCreated)
 }
 
+// CreateCheckRun creates a GitHub Check Run on a commit SHA. The check run
+// appears in the PR checks list. Returns the check run ID.
+func (c *Client) CreateCheckRun(installationID int64, repo string, headSHA string, name string, status string, conclusion string, title string, summary string, detailsURL string) (int64, error) {
+	headers, err := c.ghHeaders(installationID)
+	if err != nil {
+		return 0, err
+	}
+
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/check-runs", repo)
+
+	type ghCheckRunResponse struct {
+		ID int64 `json:"id"`
+	}
+
+	payload := map[string]interface{}{
+		"name":       name,
+		"head_sha":   headSHA,
+		"status":     status,
+		"conclusion": conclusion,
+		"output": map[string]string{
+			"title":   title,
+			"summary": summary,
+		},
+	}
+	if detailsURL != "" {
+		payload["details_url"] = detailsURL
+	}
+
+	result, err := httpclient.Request[ghCheckRunResponse](c.httpClient, http.MethodPost, apiURL, headers, payload, http.StatusCreated)
+	if err != nil {
+		return 0, err
+	}
+
+	return result.ID, nil
+}
+
+// UpdateCheckRun updates an existing GitHub Check Run's status and conclusion.
+func (c *Client) UpdateCheckRun(installationID int64, repo string, checkRunID int64, status string, conclusion string, title string, summary string) error {
+	headers, err := c.ghHeaders(installationID)
+	if err != nil {
+		return err
+	}
+
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/check-runs/%d", repo, checkRunID)
+
+	return httpclient.Do(c.httpClient, http.MethodPatch, apiURL, headers, map[string]interface{}{
+		"status":     status,
+		"conclusion": conclusion,
+		"output": map[string]string{
+			"title":   title,
+			"summary": summary,
+		},
+	}, http.StatusOK)
+}
+
+// ListCheckRunsForRef lists check runs for a commit ref, optionally filtered by name.
+func (c *Client) ListCheckRunsForRef(installationID int64, repo string, ref string, checkName string) ([]CheckRun, error) {
+	headers, err := c.ghHeaders(installationID)
+	if err != nil {
+		return nil, err
+	}
+
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/commits/%s/check-runs", repo, url.PathEscape(ref))
+	if checkName != "" {
+		apiURL += "?check_name=" + url.QueryEscape(checkName)
+	}
+
+	type ghCheckRun struct {
+		ID   int64  `json:"id"`
+		Name string `json:"name"`
+	}
+	type ghCheckRunsResponse struct {
+		CheckRuns []ghCheckRun `json:"check_runs"`
+	}
+
+	result, err := httpclient.Request[ghCheckRunsResponse](c.httpClient, http.MethodGet, apiURL, headers, nil, http.StatusOK)
+	if err != nil {
+		return nil, err
+	}
+
+	runs := make([]CheckRun, len(result.CheckRuns))
+	for i, r := range result.CheckRuns {
+		runs[i] = CheckRun{ID: r.ID, Name: r.Name}
+	}
+	return runs, nil
+}
+
 // IsCollaborator checks whether a GitHub user is a collaborator on a repository.
 // Results are cached for 5 minutes to avoid redundant API calls for the same user.
 func (c *Client) IsCollaborator(installationID int64, repo string, username string) (bool, error) {

svc/ctrl/worker/github/interface.go

@@ -26,6 +26,22 @@ type GitHubClient interface {
 
 	// IsCollaborator checks whether a GitHub user is a collaborator on a repository.
 	IsCollaborator(installationID int64, repo string, username string) (bool, error)
+
+	// CreateCheckRun creates a GitHub Check Run on a commit SHA. Returns the
+	// check run ID. Check runs appear in the PR checks list with prominent visibility.
+	CreateCheckRun(installationID int64, repo string, headSHA string, name string, status string, conclusion string, title string, summary string, detailsURL string) (int64, error)
+
+	// UpdateCheckRun updates an existing GitHub Check Run.
+	UpdateCheckRun(installationID int64, repo string, checkRunID int64, status string, conclusion string, title string, summary string) error
+
+	// ListCheckRunsForRef lists check runs for a given ref, filtered by check name.
+	ListCheckRunsForRef(installationID int64, repo string, ref string, checkName string) ([]CheckRun, error)
+}
+
+// CheckRun holds the minimal fields of a GitHub Check Run needed for updates.
+type CheckRun struct {
+	ID   int64
+	Name string
 }
 
 // CommitInfo holds metadata about a single Git commit retrieved from the GitHub API.

svc/ctrl/worker/github/noop.go

@@ -49,6 +49,21 @@ func (n *Noop) IsCollaborator(_ int64, _ string, _ string) (bool, error) {
 	return false, errNotConfigured
 }
 
+// CreateCheckRun returns an error indicating GitHub is not configured.
+func (n *Noop) CreateCheckRun(_ int64, _ string, _ string, _ string, _ string, _ string, _ string, _ string, _ string) (int64, error) {
+	return 0, errNotConfigured
+}
+
+// UpdateCheckRun returns an error indicating GitHub is not configured.
+func (n *Noop) UpdateCheckRun(_ int64, _ string, _ int64, _ string, _ string, _ string, _ string) error {
+	return errNotConfigured
+}
+
+// ListCheckRunsForRef returns an error indicating GitHub is not configured.
+func (n *Noop) ListCheckRunsForRef(_ int64, _ string, _ string, _ string) ([]CheckRun, error) {
+	return nil, errNotConfigured
+}
+
 // GetBranchHeadCommitPublic retrieves the HEAD commit using the public GitHub
 // API without authentication. Works for public repositories even when GitHub
 // App credentials are not configured.

svc/ctrl/worker/githubwebhook/handle_push.go

@@ -151,6 +151,22 @@ func (s *Service) HandlePush(ctx restate.ObjectContext, req *hydrav1.HandlePushR
 				}, restate.WithName("github deployment status: failure (awaiting auth)"), restate.WithMaxRetryDuration(30*time.Second))
 			}
 
+			// Create a GitHub Check Run for PR visibility (best-effort)
+			_ = restate.RunVoid(ctx, func(_ restate.RunContext) error {
+				_, crErr := s.github.CreateCheckRun(
+					repo.InstallationID,
+					req.GetRepositoryFullName(),
+					req.GetAfter(),
+					"Unkey Deployment Authorization",
+					"completed",
+					"action_required",
+					"Awaiting authorization from a project member",
+					fmt.Sprintf("An external contributor pushed to `%s`. A project member must authorize this deployment.", branch),
+					logURL,
+				)
+				return crErr
+			}, restate.WithName("create check run for authorization"), restate.WithMaxRetryDuration(30*time.Second))
+
 			logger.Info("deployment blocked for authorization",
 				"project_id", project.ID,
 				"app_id", app.ID,