From a5b88409120f29116db6b23bfe03d043e8fc76e1 Mon Sep 17 00:00:00 2001
From: Kingdon Barrett <kingdon@weave.works>
Date: Mon, 26 Apr 2021 12:32:04 -0400
Subject: [PATCH] Better example for image automation auto PR

The linked github actions workflow does not actually do what you need, I
found a better one and demonstrated how to use it in this example.

The "GitHub Actions Auto PR" use case could be expanded upon, but I
think maybe this short version already says everything it needs to say!

Signed-off-by: Kingdon Barrett <kingdon@weave.works>
---
 docs/guides/image-update.md          |  2 +-
 docs/use-cases/gh-actions-auto-pr.md | 54 ++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 docs/use-cases/gh-actions-auto-pr.md

diff --git a/docs/guides/image-update.md b/docs/guides/image-update.md
index 6cc399ef..fb4986e2 100644
--- a/docs/guides/image-update.md
+++ b/docs/guides/image-update.md
@@ -408,7 +408,7 @@ spec:
 ```
 
 You can use CI automation e.g. GitHub Actions such as
-[create-pull-request](https://github.com/peter-evans/create-pull-request)
+Flux's [GitHub Actions Auto PR](/use-cases/gh-actions-auto-pr) example
 to open a pull request against the checkout branch.
 
 This way you can manually approve the image updates before they are applied on your clusters.
diff --git a/docs/use-cases/gh-actions-auto-pr.md b/docs/use-cases/gh-actions-auto-pr.md
new file mode 100644
index 00000000..0a4aab76
--- /dev/null
+++ b/docs/use-cases/gh-actions-auto-pr.md
@@ -0,0 +1,54 @@
+# GitHub Actions Auto PR
+
+In the [Image Update Guide] we saw we can [Push updates to a different branch] by using `.spec.git.push.branch` to push image updates to a different branch than the one used for checkout.
+
+In this example, we configure an `ImageUpdateAutomation` resource to push to a `staging` branch, which we could set up separately as a preview environment to deploy automatic updates in a staging cluster or namespace.
+
+```yaml
+kind: ImageUpdateAutomation
+metadata:
+  name: flux-system
+spec:
+  git:
+    checkout:
+      ref:
+        branch: main
+    push:
+      branch: staging
+```
+
+In your manifest repository, add a GitHub Action workflow as below. This workflow watches for commits on the `staging` branch and opens a pull request with any labels, title, or body that you configure.
+
+```yaml
+# ./.github/workflows/staging-auto-pr.yaml
+name: Staging Auto-PR
+on:
+  push:
+    branches: ['staging']
+
+jobs:
+  pull-request:
+    name: Open PR to main
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      name: checkout
+
+    - uses: repo-sync/pull-request@v2
+      name: pull-request
+      with:
+        destination_branch: "main"
+        pr_title: "Pulling ${{ github.ref }} into main"
+        pr_body: ":crown: *An automated PR*"
+        pr_reviewer: "kingdonb"
+        pr_draft: true
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+You can use the [github-pull-request-action] workflow to automatically open a pull request against a destination branch. In this case, when a pull request is merged into the main changes are deployed in production.
+
+This way you can manually approve automatic image updates before they are applied on your production clusters.
+
+[Image Update Guide]: /guides/image-update/
+[Push updates to a different branch]: /guides/image-update/#push-updates-to-a-different-branch
+[github-pull-request-action]: https://github.com/marketplace/actions/github-pull-request-action