feat: add fast-forward_or_merge merge method

Attempt a fast-forward first; if the base branch is not an ancestor
of the head, fall back to a regular merge.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

Author: 3 people

README.md

@@ -12,7 +12,7 @@ Marketplace: https://github.com/marketplace/actions/pull-request-merge
 | ------------------------- | :------: | --------- | ----------------------------------------------------------------------------------------------------- |
 | `github-token`            |    yes   | —         | GitHub token used to call the REST API. Usually `${{ secrets.GITHUB_TOKEN }}`.                        |
 | `number`                  |    yes   | —         | Pull-request number to merge.                                                                         |
-| `merge-method`            |    no    | `merge`   | One of `merge`, `squash`, `rebase`, `fast-forward`.                                                   |
+| `merge-method`            |    no    | `merge`   | One of `merge`, `squash`, `rebase`, `fast-forward`, `fast-forward_or_merge`.                          |
 | `allowed-usernames-regex` |    no    | `^.*$`    | Regex the triggering actor (`github.actor`) must match. Skips the merge otherwise.                    |
 | `filter-label`            |    no    | *(empty)* | Regex matched against PR labels. When set, the merge is skipped unless a label matches, and the first matching label is removed after a successful merge. |
 | `merge-title`             |    no    | *(empty)* | Commit title used by the merge/squash/rebase API. Ignored for `fast-forward`.                         |
@@ -25,6 +25,9 @@ Marketplace: https://github.com/marketplace/actions/pull-request-merge
   move the base branch to the PR's head SHA. This is a *true* fast-forward: the
   base ref must already be an ancestor of the head, otherwise GitHub refuses
   the update. No merge commit is created.
+- `fast-forward_or_merge` — attempt a fast-forward first; if the base branch is
+  not an ancestor of the head (i.e. the fast-forward fails), fall back to a
+  regular `merge`.
 
 ## Required permissions
 

action.yml

@@ -9,7 +9,7 @@ inputs:
         description: "Pull Request number"
         required: true
     merge-method:
-        description: "The merge method: merge,squash,rebase,fast-forward"
+        description: "The merge method: merge,squash,rebase,fast-forward,fast-forward_or_merge"
         required: false
         default: "merge"
     allowed-usernames-regex:

src/action.rs

@@ -91,6 +91,44 @@ pub async fn run<C: GithubClient + ?Sized, L: Logger + ?Sized>(
                 .context("fast-forward update_ref failed")?;
             Outcome::FastForwarded
         }
+        MergeMethod::FastForwardOrMerge => {
+            log.info(&format!(
+                "Attempting fast-forward: heads/{}@{}",
+                pr.base.ref_, pr.head.sha
+            ));
+            match client
+                .update_ref(
+                    &ctx.owner,
+                    &ctx.repo,
+                    &format!("heads/{}", pr.base.ref_),
+                    &pr.head.sha,
+                    false,
+                )
+                .await
+            {
+                Ok(()) => {
+                    log.info("Fast-forward succeeded.");
+                    Outcome::FastForwarded
+                }
+                Err(e) => {
+                    log.warning(&format!(
+                        "Fast-forward failed ({}), falling back to merge.",
+                        e
+                    ));
+                    let req = MergeRequest::from_inputs(
+                        MergeMethod::Merge,
+                        &pr.head.sha,
+                        &inputs.merge_title,
+                        &inputs.merge_message,
+                    );
+                    client
+                        .merge_pull(&ctx.owner, &ctx.repo, inputs.number, &req)
+                        .await
+                        .context("merge request failed (after fast-forward fallback)")?;
+                    Outcome::Merged
+                }
+            }
+        }
         method => {
             let req = MergeRequest::from_inputs(
                 method,
@@ -367,6 +405,76 @@ mod tests {
         assert!(client.merge_calls.lock().unwrap().is_empty());
     }
 
+    #[tokio::test]
+    async fn fast_forward_or_merge_succeeds_with_ff() {
+        let client = FakeClient::with_pr(open_pr(&[]));
+        let mut log = CaptureLogger::new();
+        let out = run(
+            &client,
+            &inputs(MergeMethod::FastForwardOrMerge, "^.*$", ""),
+            &ctx(),
+            &mut log,
+        )
+        .await
+        .unwrap();
+        assert_eq!(out, Outcome::FastForwarded);
+
+        let calls = client.update_ref_calls.lock().unwrap();
+        assert_eq!(calls.len(), 1);
+        assert!(client.merge_calls.lock().unwrap().is_empty());
+        assert!(log.contains("Fast-forward succeeded"));
+    }
+
+    #[tokio::test]
+    async fn fast_forward_or_merge_falls_back_to_merge() {
+        struct FailFfClient(FakeClient);
+        #[async_trait]
+        impl GithubClient for FailFfClient {
+            async fn get_pull(&self, o: &str, r: &str, n: u64) -> Result<PullRequest> {
+                self.0.get_pull(o, r, n).await
+            }
+            async fn update_ref(
+                &self,
+                _o: &str,
+                _r: &str,
+                _ref: &str,
+                _sha: &str,
+                _f: bool,
+            ) -> Result<()> {
+                Err(anyhow::anyhow!("not a fast-forward"))
+            }
+            async fn merge_pull(
+                &self,
+                o: &str,
+                r: &str,
+                n: u64,
+                req: &MergeRequest,
+            ) -> Result<()> {
+                self.0.merge_pull(o, r, n, req).await
+            }
+            async fn remove_label(&self, o: &str, r: &str, n: u64, l: &str) -> Result<()> {
+                self.0.remove_label(o, r, n, l).await
+            }
+        }
+
+        let client = FailFfClient(FakeClient::with_pr(open_pr(&[])));
+        let mut log = CaptureLogger::new();
+        let out = run(
+            &client,
+            &inputs(MergeMethod::FastForwardOrMerge, "^.*$", ""),
+            &ctx(),
+            &mut log,
+        )
+        .await
+        .unwrap();
+        assert_eq!(out, Outcome::Merged);
+
+        let merges = client.0.merge_calls.lock().unwrap();
+        assert_eq!(merges.len(), 1);
+        assert_eq!(merges[0].1.merge_method, "merge");
+        assert!(log.contains("falling back to merge"));
+    }
+
     #[tokio::test]
     async fn label_removal_failure_is_only_a_warning() {
         let client = FakeClient::with_pr(open_pr(&["merge-it"]));

src/github_client.rs

@@ -48,8 +48,8 @@ impl MergeRequest {
                 MergeMethod::Merge => "merge",
                 MergeMethod::Squash => "squash",
                 MergeMethod::Rebase => "rebase",
-                // FastForward is handled out-of-band; defensively fall back to merge.
-                MergeMethod::FastForward => "merge",
+                // FastForward / FastForwardOrMerge are handled out-of-band; defensively fall back to merge.
+                MergeMethod::FastForward | MergeMethod::FastForwardOrMerge => "merge",
             },
             sha: head_sha.to_string(),
             commit_title: Some(title.to_string()).filter(|s| !s.trim().is_empty()),

src/inputs.rs

@@ -73,6 +73,7 @@ pub enum MergeMethod {
     Squash,
     Rebase,
     FastForward,
+    FastForwardOrMerge,
 }
 
 impl MergeMethod {
@@ -82,8 +83,9 @@ impl MergeMethod {
             "squash" => Ok(Self::Squash),
             "rebase" => Ok(Self::Rebase),
             "fast-forward" => Ok(Self::FastForward),
+            "fast-forward_or_merge" => Ok(Self::FastForwardOrMerge),
             other => Err(anyhow!(
-                "invalid merge-method '{}': expected one of merge, squash, rebase, fast-forward",
+                "invalid merge-method '{}': expected one of merge, squash, rebase, fast-forward, fast-forward_or_merge",
                 other
             )),
         }
@@ -228,6 +230,10 @@ mod tests {
             MergeMethod::parse("fast-forward").unwrap(),
             MergeMethod::FastForward
         );
+        assert_eq!(
+            MergeMethod::parse("fast-forward_or_merge").unwrap(),
+            MergeMethod::FastForwardOrMerge
+        );
         assert!(MergeMethod::parse("nope").is_err());
     }
 }