-
Notifications
You must be signed in to change notification settings - Fork 566
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4052 from fluxcd/docs-gh-action
docs: Link to the Flux GitHub Action documentation
- Loading branch information
Showing
1 changed file
with
13 additions
and
207 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,216 +1,22 @@ | ||
| # Flux GitHub Action | ||
|
|
||
| Usage: | ||
| To install the latest Flux CLI on Linux, macOS or Windows GitHub runners: | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| - name: Run Flux commands | ||
| run: flux -v | ||
| steps: | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| with: | ||
| version: 'latest' | ||
| - name: Run Flux CLI | ||
| run: flux version --client | ||
| ``` | ||
|
|
||
| The latest stable version of the `flux` binary is downloaded from | ||
| GitHub [releases](https://github.com/fluxcd/flux2/releases) | ||
| and placed at `/usr/local/bin/flux`. | ||
| The Flux GitHub Action can be used to automate various tasks in CI, such as: | ||
|
|
||
| Note that this action can only be used on GitHub **Linux** runners. | ||
| You can change the arch (defaults to `amd64`) with: | ||
| - [Automate Flux upgrades on clusters via Pull Requests](https://fluxcd.io/flux/flux-gh-action/#automate-flux-updates) | ||
| - [Push Kubernetes manifests to container registries](https://fluxcd.io/flux/flux-gh-action/#push-kubernetes-manifests-to-container-registries) | ||
| - [Run end-to-end testing with Flux and Kubernetes Kind](https://fluxcd.io/flux/flux-gh-action/#end-to-end-testing) | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| with: | ||
| arch: arm64 # can be amd64, arm64 or arm | ||
| ``` | ||
|
|
||
| You can download a specific version with: | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| with: | ||
| version: 0.32.0 | ||
| ``` | ||
|
|
||
| You can also authenticate against the GitHub API using GitHub Actions' `GITHUB_TOKEN` secret. | ||
|
|
||
| For more information, please [read about the GitHub token secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret). | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| with: | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| ``` | ||
|
|
||
| This is useful if you are seeing failures on shared runners, those failures are usually API limits being hit. | ||
|
|
||
| ### Automate Flux updates | ||
|
|
||
| Example workflow for updating Flux's components generated with `flux bootstrap --path=clusters/production`: | ||
|
|
||
| ```yaml | ||
| name: update-flux | ||
|
|
||
| on: | ||
| workflow_dispatch: | ||
| schedule: | ||
| - cron: "0 * * * *" | ||
|
|
||
| permissions: | ||
| contents: write | ||
| pull-requests: write | ||
|
|
||
| jobs: | ||
| components: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Check out code | ||
| uses: actions/checkout@v3 | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| - name: Check for updates | ||
| id: update | ||
| run: | | ||
| flux install \ | ||
| --export > ./clusters/production/flux-system/gotk-components.yaml | ||
| VERSION="$(flux -v)" | ||
| echo "flux_version=$VERSION" >> $GITHUB_OUTPUT | ||
| - name: Create Pull Request | ||
| uses: peter-evans/create-pull-request@v4 | ||
| with: | ||
| token: ${{ secrets.GITHUB_TOKEN }} | ||
| branch: update-flux | ||
| commit-message: Update to ${{ steps.update.outputs.flux_version }} | ||
| title: Update to ${{ steps.update.outputs.flux_version }} | ||
| body: | | ||
| ${{ steps.update.outputs.flux_version }} | ||
| ``` | ||
|
|
||
| ### Push Kubernetes manifests to container registries | ||
|
|
||
| Example workflow for publishing Kubernetes manifests bundled as OCI artifacts to GitHub Container Registry: | ||
|
|
||
| ```yaml | ||
| name: push-artifact-staging | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - 'main' | ||
|
|
||
| permissions: | ||
| packages: write # needed for ghcr.io access | ||
|
|
||
| env: | ||
| OCI_REPO: "oci://ghcr.io/my-org/manifests/${{ github.event.repository.name }}" | ||
|
|
||
| jobs: | ||
| kubernetes: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v3 | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| - name: Login to GHCR | ||
| uses: docker/login-action@v2 | ||
| with: | ||
| registry: ghcr.io | ||
| username: ${{ github.actor }} | ||
| password: ${{ secrets.GITHUB_TOKEN }} | ||
| - name: Generate manifests | ||
| run: | | ||
| kustomize build ./manifests/staging > ./deploy/app.yaml | ||
| - name: Push manifests | ||
| run: | | ||
| flux push artifact $OCI_REPO:$(git rev-parse --short HEAD) \ | ||
| --path="./deploy" \ | ||
| --source="$(git config --get remote.origin.url)" \ | ||
| --revision="$(git branch --show-current)@sha1:$(git rev-parse HEAD)" | ||
| - name: Deploy manifests to staging | ||
| run: | | ||
| flux tag artifact $OCI_REPO:$(git rev-parse --short HEAD) --tag staging | ||
| ``` | ||
|
|
||
| ### Push and sign Kubernetes manifests to container registries | ||
|
|
||
| Example workflow for publishing Kubernetes manifests bundled as OCI artifacts | ||
| which are signed with Cosign and GitHub OIDC: | ||
|
|
||
| ```yaml | ||
| name: push-sign-artifact | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - 'main' | ||
|
|
||
| permissions: | ||
| packages: write # needed for ghcr.io access | ||
| id-token: write # needed for keyless signing | ||
|
|
||
| env: | ||
| OCI_REPO: "oci://ghcr.io/my-org/manifests/${{ github.event.repository.name }}" | ||
|
|
||
| jobs: | ||
| kubernetes: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v3 | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| - name: Setup Cosign | ||
| uses: sigstore/cosign-installer@main | ||
| - name: Login to GHCR | ||
| uses: docker/login-action@v2 | ||
| with: | ||
| registry: ghcr.io | ||
| username: ${{ github.actor }} | ||
| password: ${{ secrets.GITHUB_TOKEN }} | ||
| - name: Push and sign manifests | ||
| run: | | ||
| digest_url=$(flux push artifact \ | ||
| $OCI_REPO:$(git rev-parse --short HEAD) \ | ||
| --path="./manifests" \ | ||
| --source="$(git config --get remote.origin.url)" \ | ||
| --revision="$(git branch --show-current)@sha1:$(git rev-parse HEAD)" |\ | ||
| jq -r '. | .repository + "@" + .digest') | ||
| cosign sign $digest_url | ||
| ``` | ||
|
|
||
| ### End-to-end testing | ||
|
|
||
| Example workflow for running Flux in Kubernetes Kind: | ||
|
|
||
| ```yaml | ||
| name: e2e | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - '*' | ||
|
|
||
| jobs: | ||
| kubernetes: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v3 | ||
| - name: Setup Flux CLI | ||
| uses: fluxcd/flux2/action@main | ||
| - name: Setup Kubernetes Kind | ||
| uses: engineerd/setup-kind@v0.5.0 | ||
| - name: Install Flux in Kubernetes Kind | ||
| run: flux install | ||
| ``` | ||
| For more information, please see the [Flux GitHub Action documentation](/flux/flux-gh-action.md). | ||
|
|
||
| A complete e2e testing workflow is available here | ||
| [flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example/blob/main/.github/workflows/e2e.yaml) |