Skip to content

Commit 7097e80

Browse files
michaeljguarinomichaeljguarino
authored
Add federated credentials docs (#497)
Documents how to use federated credentials, specifically related to gh actions
1 parent bab017b commit 7097e80

File tree

3 files changed

+163
-0
lines changed

3 files changed

+163
-0
lines changed

‎generated/routes.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,10 @@
135135
"relPath": "/plural-features/continuous-deployment/pipelines.md",
136136
"lastmod": "2025-05-12T06:30:23.000Z"
137137
},
138+
"/plural-features/continuous-deployment/github-actions-ci": {
139+
"relPath": "/plural-features/continuous-deployment/github-actions-ci.md",
140+
"lastmod": "2025-08-04T01:09:39.000Z"
141+
},
138142
"/plural-features/k8s-upgrade-assistant": {
139143
"relPath": "/plural-features/k8s-upgrade-assistant/index.md",
140144
"lastmod": "2025-05-11T23:04:59.000Z"

‎pages/plural-features/continuous-deployment/github-actions-ci.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Integration With Github Actions
3+
description: How to integrate Plural with Github Actions and other CI providers
4+
---
5+
6+
Plural is generally meant to implement a GitOps based workflow that is somewhat tangential to general CI strategies. The main point of friction is that CI will usually run against commits against application code, usually resulting in a complete docker image build, but GitOps workflows require a follow-on commit in a secondary infrastructure config repo (or subsection of a monorepo).
7+
8+
Automating that is typically not done, with teams manually managing config files and executing tedious processes. You also don't want to compromise the security of your GitOps controller by exposing its credentials to a public CI solution like Github Actions. Plural takes the following approach:
9+
10+
1. You can delegate federated credentials to issue temporary JWTs against your Plural instance to authenticate, with scopes usually limited to minimal changes (eg create a PR)
11+
2. We provide decent prebuilt actions to make integration as simple as possible.
12+
13+
Lets show how its done.
14+
15+
## Create a federated credential
16+
17+
The first step is creating a federated credential to allow a token exchange between Github's OIDC provider and Plural:
18+
19+
```yaml
20+
apiVersion: deployments.plural.sh/v1alpha1
21+
kind: FederatedCredential
22+
metadata:
23+
name: gh-actions
24+
spec:
25+
issuer: https://token.actions.githubusercontent.com # the oidc issuer url for gh actions, can be swapped for any other platform with oidc federation support
26+
user: [email protected] # should point to the user email you want the federated credential to auth as
27+
scopes:
28+
- createPullRequest
29+
claimsLike:
30+
sub: "repo:pluralsh/console:ref:refs/heads/master" # any regex is supported
31+
```
32+
33+
{% callout severity="info" %}
34+
You can actually use Plural AI to generate these with its built in Kubernetes API discovery integration! Just be sure to select your management cluster in the chat context.
35+
{% /callout %}
36+
37+
## Define the PR Automation
38+
39+
In this case we're going to have Github Actions trigger a PR automation, it can also perform other api actions like kicking a Plural Pipeline as well. Just to show how it would work, here's an example PR automation spec:
40+
41+
```yaml
42+
apiVersion: deployments.plural.sh/v1alpha1
43+
kind: PrAutomation
44+
metadata:
45+
name: console-updater
46+
spec:
47+
name: console-updater
48+
documentation: Updates the console image version
49+
updates:
50+
yamlOverlays:
51+
- file: "bootstrap/console.yaml"
52+
yaml: |
53+
spec:
54+
helm:
55+
values:
56+
image:
57+
tag: {{ context.tag }}
58+
scmConnectionRef:
59+
name: plural
60+
title: "Updating console to use {{ context.tag }}"
61+
message: "Updating console to use {{ context.tag }}"
62+
identifier: mgmt
63+
configuration:
64+
- name: tag
65+
type: STRING
66+
documentation: The new image tag to use
67+
```
68+
69+
Notice this is really just overlaying some templated yaml on the existing `bootstrap/console.yaml` file which is deploying our console service. Nothing too crazy, usually image updates are simple.
70+
71+
## Define the Github Action to trigger a PR
72+
73+
Then your github actions file can look something like this, in this case it is executing on all pushes to master
74+
75+
```yaml
76+
name: CI / Trigger PR
77+
78+
env:
79+
# this configures docker/metadata-action to use the true commit sha when tagging
80+
DOCKER_METADATA_PR_HEAD_SHA: 'true'
81+
82+
on:
83+
push:
84+
branches:
85+
- master
86+
jobs:
87+
pr:
88+
permissions:
89+
id-token: write # this is necessary to get a gh id token
90+
contents: read
91+
packages: write
92+
name: Generate PR
93+
runs-on: ubuntu-latest
94+
steps:
95+
- name: Checkout the repo
96+
uses: actions/checkout@v3
97+
with:
98+
fetch-depth: 0
99+
################################################################
100+
# Boilerplate to build a docker image, feel free to skip below #
101+
################################################################
102+
- name: Docker meta
103+
id: meta
104+
uses: docker/metadata-action@v4
105+
with:
106+
# list of Docker images to use as base name for tags
107+
images: ghcr.io/pluralsh/console
108+
# generate Docker tags based on the following events/attributes
109+
tags: |
110+
type=sha
111+
- name: Set up QEMU
112+
uses: docker/setup-qemu-action@v2
113+
- name: Set up Docker Buildx
114+
uses: docker/setup-buildx-action@v2
115+
- name: Login to GHCR
116+
uses: docker/login-action@v2
117+
with:
118+
registry: ghcr.io
119+
username: ${{ github.repository_owner }}
120+
password: ${{ secrets.GITHUB_TOKEN }}
121+
- name: Test Build console image
122+
uses: docker/build-push-action@v3
123+
with:
124+
context: "."
125+
file: "./Dockerfile"
126+
push: true
127+
tags: ${{ steps.meta.outputs.tags }}
128+
labels: ${{ steps.meta.outputs.labels }}
129+
platforms: linux/amd64
130+
cache-from: type=gha
131+
cache-to: type=gha,mode=max
132+
###############################################################
133+
# Plural CLI Setup and trigger-pull-request action invocation #
134+
###############################################################
135+
- name: setup plural
136+
id: plural
137+
uses: pluralsh/setup-plural@v1
138+
with:
139+
email: [email protected]
140+
consoleUrl: https://my.console.cloud.plurall.sh
141+
- name: Set outputs
142+
id: sha
143+
run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT # unfortunately gh actions doesn't expose this natively lol
144+
- name: Trigger PR
145+
uses: pluralsh/trigger-pull-request@v1
146+
with:
147+
url: https://my.console.cloud.plurall.sh
148+
token: ${{ steps.plural.outputs.consoleToken }}
149+
branch: plrl/console/update-${{ steps.sha.outputs.sha_short }}
150+
prAutomation: console-updater # the pr automation name above
151+
context: |
152+
{
153+
"tag": "sha-${{ steps.sha.outputs.sha_short }}"
154+
}
155+
```

‎src/routing/docs-structure.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,10 @@ export const docsStructure: DocSection[] = [
8989
title: 'Plural Observers in Continuous Deployment',
9090
},
9191
{ path: 'pipelines', title: 'Pipelines' },
92+
{
93+
path: 'github-actions-ci',
94+
title: 'Integration with Github Actions/CI',
95+
},
9296
],
9397
},
9498
{

0 commit comments

Comments
 (0)