Merge pull request #157 from controlplaneio-fluxcd/docs-flux-operator…

…-v0.15.0 Update docs for Flux Operator v0.15.0
controlplaneio-fluxcd · Feb 20, 2025 · 2d10024 · 2d10024
2 parents 3629038 + 40c6a73
commit 2d10024
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 27 deletions.
diff --git a/docs/operator/resourcesetinputprovider.md b/docs/operator/resourcesetinputprovider.md
@@ -172,8 +172,8 @@ metadata:
   name: github-pat
   namespace: default
 stringData:
-    username: flux
-    password: <GITHUB PAT>
+  username: flux
+  password: <GITHUB PAT>
 ```
 
 Example secret reference:
@@ -184,6 +184,41 @@ spec:
     name: github-pat
 ```
 
+#### GitHub App authentication
+
+For GitHub, GitHub App authentication is also supported. Instead of adding the basic
+auth keys `username` and `password`, you can add the following GitHub App keys to the
+secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: github-app
+  namespace: default
+stringData:
+  githubAppID: "<GITHUB APP ID>"
+  githubAppInstallationID: "<GITHUB APP INSTALLATION ID>"
+  githubAppBaseURL: <github-enterprise-api-url> # optional, for self-hosted GitHub Enterprise
+  githubAppPrivateKey: |
+    -----BEGIN RSA PRIVATE KEY-----
+    ...
+    -----END RSA PRIVATE KEY-----
+```
+
+Example secret reference:
+
+```yaml
+spec:
+  secretRef:
+    name: github-app
+```
+
+The GitHub App ID and Installation ID are integer numbers, so remember to quote them in the secret
+if using the `stringData` field as all values in this field must be strings.
+
+A simpler alternative is creating the secret using the Flux CLI command `flux create secret githubapp`.
+
 ### TLS certificate configuration
 
 The `.spec.certSecretRef` field is optional and specifies the Kubernetes Secret containing the
@@ -201,11 +236,11 @@ metadata:
   name: gitlab-ca
   namespace: default
 stringData:
-    ca.crt: |
-      -----BEGIN CERTIFICATE-----
-      MIIDpDCCAoygAwIBAgIUI7z
-      ...
-      -----END CERTIFICATE-----
+  ca.crt: |
+    -----BEGIN CERTIFICATE-----
+    MIIDpDCCAoygAwIBAgIUI7z
+    ...
+    -----END CERTIFICATE-----
 ```
 
 Example certificate reference:
@@ -298,20 +333,20 @@ Example:
 
 ```yaml
 status:
-   exportedInputs:
-   - author: stefanprodan
-     branch: kubernetes/helm-set-limits
-     id: "4"
-     sha: bf5d6e01cf802734853f6f3417b237e3ad0ba35d
-     title: 'kubernetes(helm): Add default resources limits'
-   - author: stefanprodan
-     branch: feat/ui-footer
-     id: "3"
-     sha: 8492c0b5b2094fe720776c8ace1b9690ff258f53
-     title: 'feat(ui): Add footer'
-   - author: stefanprodan
-     branch: feat/ui-color-scheme
-     id: "2"
-     sha: 8166bdecd6b078b9e5dd14fa3b7b67a847f76893
-     title: 'feat(ui): Default color scheme'
+  exportedInputs:
+    - author: stefanprodan
+      branch: kubernetes/helm-set-limits
+      id: "4"
+      sha: bf5d6e01cf802734853f6f3417b237e3ad0ba35d
+      title: 'kubernetes(helm): Add default resources limits'
+    - author: stefanprodan
+      branch: feat/ui-footer
+      id: "3"
+      sha: 8492c0b5b2094fe720776c8ace1b9690ff258f53
+      title: 'feat(ui): Add footer'
+    - author: stefanprodan
+      branch: feat/ui-color-scheme
+      id: "2"
+      sha: 8166bdecd6b078b9e5dd14fa3b7b67a847f76893
+      title: 'feat(ui): Default color scheme'
 ```
diff --git a/docs/operator/resourcesets/github-pull-requests.md b/docs/operator/resourcesets/github-pull-requests.md
@@ -54,16 +54,29 @@ subjects:
     namespace: app-preview
 ```
 
-In this namespace, we'll create a Kubernetes Secret
+### GitHub authentication
+
+In the `app-preview` namespace, we'll create a Kubernetes Secret
 containing a GitHub PAT that grants read access to the app repository and PRs.
 
 ```shell
-flux -n app-preview create secret git github-token-readonly \
+flux -n app-preview create secret git github-auth \
   --url=https://github.com/org/app \
   --username=flux \
   --password=${GITHUB_TOKEN}
 ```
 
+Alternatively, we can use a GitHub App token for authentication:
+
+```shell
+flux create secret githubapp github-auth \
+  --app-id="1" \
+  --app-installation-id="2" \
+  --app-private-key=./private-key-file.pem
+```
+
+Note that GitHub App support was added in Flux v2.5 and Flux Operator v0.15.
+
 ### ResourceSet input provider
 
 In the `app-preview` namespace, we'll create a [ResourceSetInputProvider](../resourcesetinputprovider.md)
@@ -81,7 +94,7 @@ spec:
   type: GitHubPullRequest
   url: https://github.com/org/app
   secretRef:
-    name: github-token-readonly
+    name: github-auth
   filter:
     labels:
       - "deploy/flux-preview"
@@ -134,12 +147,13 @@ spec:
         name: app-<< inputs.id >>
         namespace: app-preview
       spec:
+        provider: generic # or 'github' if using GitHub App
         interval: 1h
         url: https://github.com/org/app
         ref:
           commit: << inputs.sha >>
         secretRef:
-          name: github-token-readonly
+          name: github-auth
     - apiVersion: helm.toolkit.fluxcd.io/v2
       kind: HelmRelease
       metadata: