octocrab 0.54.7

A modern, extensible GitHub API client.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! Asynchronous pull request merge builder.
//!
//! See <https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously>

use crate::models::pr_stacks::{AsyncMergeAction, AsyncMergeMethod, AsyncMergeResult};

use super::PullRequestHandler;

/// Builder for submitting an asynchronous pull request merge.
///
/// Created with [`PullRequestHandler::merge_async`].
///
/// Merging asynchronously allows complex merges to be retried and avoids
/// request timeouts. This is the **required** method for merging stacked pull
/// requests — when merging a stacked PR, all PRs below it in the stack are
/// also merged.
///
/// # GitHub Documentation
/// <https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request-asynchronously>
///
/// # Example
/// ```no_run
/// # async fn run() -> octocrab::Result<()> {
/// use octocrab::models::pr_stacks::{AsyncMergeMethod, AsyncMergeStatus};
///
/// let result = octocrab::instance()
///     .pulls("owner", "repo")
///     .merge_async(42)
///     .merge_method(AsyncMergeMethod::Squash)
///     .send()
///     .await?;
///
/// println!("Merge status: {:?}", result.status);
/// # Ok(()) }
/// ```
#[derive(serde::Serialize)]
pub struct MergeAsyncBuilder<'octo, 'b> {
    #[serde(skip)]
    handler: &'b PullRequestHandler<'octo>,
    #[serde(skip)]
    pr_number: u64,
    /// Title for the automatic commit message.
    #[serde(skip_serializing_if = "Option::is_none")]
    commit_title: Option<String>,
    /// Extra detail to append to the automatic commit message.
    #[serde(skip_serializing_if = "Option::is_none")]
    commit_message: Option<String>,
    /// SHA that the PR head must match at merge time. If omitted, the current
    /// head SHA is used; if the PR is pushed to between submission and
    /// execution, the merge is cancelled.
    #[serde(skip_serializing_if = "Option::is_none")]
    sha: Option<String>,
    /// Merge method to use.
    #[serde(skip_serializing_if = "Option::is_none")]
    merge_method: Option<AsyncMergeMethod>,
    /// Merge action strategy.
    #[serde(skip_serializing_if = "Option::is_none")]
    merge_action: Option<AsyncMergeAction>,
    /// Whether to bypass repository rules that the authenticated actor is
    /// permitted to bypass.
    #[serde(skip_serializing_if = "Option::is_none")]
    bypass_rules: Option<bool>,
}

impl<'octo, 'b> MergeAsyncBuilder<'octo, 'b> {
    pub(crate) fn new(handler: &'b PullRequestHandler<'octo>, pr_number: u64) -> Self {
        Self {
            handler,
            pr_number,
            commit_title: None,
            commit_message: None,
            sha: None,
            merge_method: None,
            merge_action: None,
            bypass_rules: None,
        }
    }

    /// Title for the automatic commit message.
    pub fn commit_title(mut self, title: impl Into<String>) -> Self {
        self.commit_title = Some(title.into());
        self
    }

    /// Extra detail to append to the automatic commit message.
    pub fn commit_message(mut self, msg: impl Into<String>) -> Self {
        self.commit_message = Some(msg.into());
        self
    }

    /// SHA that the pull request head must match to allow merge.
    pub fn sha(mut self, sha: impl Into<String>) -> Self {
        self.sha = Some(sha.into());
        self
    }

    /// Merge method to use (merge, squash, or rebase).
    pub fn merge_method(mut self, method: AsyncMergeMethod) -> Self {
        self.merge_method = Some(method);
        self
    }

    /// Merge action strategy (default, direct_merge, or merge_queue).
    pub fn merge_action(mut self, action: AsyncMergeAction) -> Self {
        self.merge_action = Some(action);
        self
    }

    /// Whether to bypass repository rules that the authenticated actor is
    /// permitted to bypass.
    pub fn bypass_rules(mut self, bypass: bool) -> Self {
        self.bypass_rules = Some(bypass);
        self
    }

    /// Submit the asynchronous merge request.
    ///
    /// Returns the current merge result. A `200` response means the PR was
    /// already merged or is already in a merge queue; `202` means the request
    /// was accepted and is running in the background. Both cases return an
    /// [`AsyncMergeResult`].
    pub async fn send(self) -> crate::Result<AsyncMergeResult> {
        let route = format!(
            "/repos/{owner}/{repo}/pulls/{pr}/merge-async",
            owner = self.handler.owner,
            repo = self.handler.repo,
            pr = self.pr_number,
        );
        self.handler.http_put(route, Some(&self)).await
    }
}