git-wait-for-pr

git-wait-for-pr waits for a specified open pull request to be merged or closed. This step commonly follows a git-open-pr step and is commonly followed by an argocd-update step.

Accelerate with webhooks

By default, Kargo polls the Git provider every 30 seconds (see pollInterval below) to check whether the PR has been merged or closed. If you configure a webhook receiver that supports PR/MR closed events (Azure DevOps, Bitbucket, GitHub, GitLab, Gitea), Kargo detects PR changes near-instantly. The polling fallback remains active for reliability. See Webhook Receivers for setup instructions.

Credentials

Git steps are utilizing the repository credentials system to access the git repos.

Configuration

Name	Type	Required	Description
repoURL	string	Y	The URL of a remote Git repository. Deprecated: Support for SSH URLs (ssh:// and SCP-style git@host:path) is deprecated as of v1.10.0 and will be removed in v1.13.0. Use HTTPS URLs instead.
provider	string	N	The name of the Git provider to use. Currently azure, bitbucket, gitea, github, and gitlab are supported. Kargo will try to infer the provider if it is not explicitly specified.
insecureSkipTLSVerify	boolean	N	Indicates whether to bypass TLS certificate verification when interfacing with the Git provider. Setting this to true is highly discouraged in production.
prNumber	integer	Y	The pull request number to wait for.
pollInterval	string	N	The suggested interval at which to poll the PR's status while waiting (e.g. 30s, 2m). This is only a suggestion: Kargo enforces a lower bound of 10 seconds and may reconcile sooner in response to other events, such as the PR-closed webhooks described above. Defaults to 30s.

Output

Name	Type	Description
commit	string	The ID (SHA) of the new commit at the head of the target branch after merge. Typically, a subsequent argocd-update step will reference this output to learn the ID of the commit that an applicable Argo CD ApplicationSource should be observably synced to under healthy conditions.
pr	object	An object containing details about the pull request being monitored.
pr.id	number	The numeric identifier of the pull request.
pr.url	string	The URL of the pull request.
pr.open	boolean	Whether the pull request is still open.
pr.merged	boolean	Whether the pull request has been merged.

Waiting, Retries, and Timeouts

Each time the step runs, it asks the Git provider for the PR's current state:

• Open: The step reports a Running status and the PR is checked again after pollInterval, or sooner if a webhook or a refresh (see below) prompts it. Waiting on an open PR is not an error and does not count toward the step's error threshold.
• Merged: The step succeeds.
• Closed without being merged: The step fails, and so does the Promotion. This is not retried.

If the step cannot learn the PR's state at all, for example because the credentials are invalid, the PR does not exist, or the Git provider is unavailable, that is an error. As with any other step, a single error fails the Promotion by default. Use retry.errorThreshold to tolerate transient errors.

By default, the step waits on an open PR indefinitely. To give up on a PR that has gone unmerged for too long, set retry.timeout:

- uses: git-wait-for-pr
  as: wait-for-pr
  retry:
    timeout: 48h
  config:
    repoURL: https://github.com/example/repo.git
    prNumber: ${{ outputs['open-pr'].pr.id }}

To check the PR again right away instead of waiting for the next poll, click Refresh on the Promotion in the UI, or refresh its Stage from the CLI. Refreshing a Stage also refreshes its current Promotion.

kargo refresh stage --project=my-project my-stage

Examples

Common Usage

In this example, a complete promotion flow is demonstrated where changes are pushed to a generated branch, a pull request is opened, and then the process waits for the pull request to be merged or closed. The git-wait-for-pr step references both the repository URL and the PR number (obtained from the open-pr step's output) to track the PR's status.

This pattern is common when you want to ensure changes have been properly reviewed and merged before proceeding with subsequent steps in your promotion process, such as updating Argo CD applications.

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
# ...
spec:
  # ...
  promotionTemplate:
    spec:
      steps:
      # Clone, prepare the contents of ./out, commit, etc...
      - uses: git-push
        as: push
        config:
          path: ./out
          generateTargetBranch: true
      - uses: git-open-pr
        as: open-pr
        config:
          repoURL: https://github.com/example/repo.git
          sourceBranch: ${{ outputs.push.branch }} # Or task.outputs in a (Cluster)PromotionTask
          targetBranch: stage/${{ ctx.stage }}
      - uses: git-wait-for-pr
        as: wait-for-pr
        config:
          repoURL: https://github.com/example/repo.git
          prNumber: ${{ outputs['open-pr'].pr.id }}