feat: LTS release process (#2155)

* feat: auto-update dependencies

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

* docs: add release docs

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

* fix: remove note about image tag

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

* fix: add variables to allow build from release branch

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

* Update design/006-LTS-release.md

Co-authored-by: Gustavo Fernandes de Carvalho <gusfcarvalho@gmail.com>
Signed-off-by: Moritz Johner <moolen@users.noreply.github.com>

* Update design/006-LTS-release.md

Co-authored-by: Gustavo Fernandes de Carvalho <gusfcarvalho@gmail.com>
Signed-off-by: Moritz Johner <moolen@users.noreply.github.com>

* Update design/006-LTS-release.md

Co-authored-by: Gustavo Fernandes de Carvalho <gusfcarvalho@gmail.com>
Signed-off-by: Moritz Johner <moolen@users.noreply.github.com>

* Update design/006-LTS-release.md

Co-authored-by: Gustavo Fernandes de Carvalho <gusfcarvalho@gmail.com>
Signed-off-by: Moritz Johner <moolen@users.noreply.github.com>

* fix: github ref regex match release branch

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

* feat: migrate to new issue template format

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

---------

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>
Signed-off-by: Moritz Johner <moolen@users.noreply.github.com>
Co-authored-by: Gustavo Fernandes de Carvalho <gusfcarvalho@gmail.com>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: kind/bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. provide all relevant manifests
+2. provide the Kubernetes and ESO version
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/create_release.md

@@ -0,0 +1,30 @@
+---
+name: Create Release
+about: Release template to track the next release
+title: Release x.y
+labels: area/release
+assignees: ''
+
+---
+
+This Issue tracks the next ESO release. Please follow the guideline below. If anything is missing or unclear, please add a comment to this issue so this can be improved after the release.
+
+#### Preparation Tasks
+
+- [ ] ask in `#external-secrets-dev` if we're ready for a release cut-off or if something needs to get urgently in
+- [ ] docs: [stability & support page](https://external-secrets.io/main/introduction/stability-support/) is up to date
+  - [ ] version table
+  - [ ] Provider Stability and Support table
+  - [ ] Provider Feature Support table
+- [ ] docs: update [roadmap page](https://external-secrets.io/main/contributing/roadmap/)
+- [ ] tidy up [Project Board](https://github.com/orgs/external-secrets/projects/2)
+  - [ ] move issues to next milestone
+  - [ ] close milestone
+
+#### Release Execution
+
+- [ ] Follow the [Release Process guide](https://external-secrets.io/main/contributing/release/)
+
+#### After Release Tasks
+
+- [ ] Announce release on `#external-secrets` in Slack

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: kind/feature
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -1,9 +1,5 @@
 version: 2
 updates:
-  - package-ecosystem: "gomod"
-    directory: "/"
-    schedule:
-      interval: "weekly"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/issue_template.md

@@ -1,13 +0,0 @@
-**Describe the solution you'd like**
-Describe the end goal of this proposal. What is this new functionality or the new behaviour (or what problem does it fix)? 
-
-**What is the added value?**
-Explain the value that it adds. e.g. "Secret refreshing will make internal secrets up to date with external secrets".
-
-**Give us examples of the outcome**
-
-Provide templates if you are proposing changes in the CRD. Provide example workflows or code snippets if they make sense to present.
-
-**Observations (Constraints, Context, etc):**
-
-Give here all extra information that could be interesting. Such as Golang version and Kubernetes version if you are reporting a bug/problem. You can also foresee technical constrains like "this could only be implementing using this specific technology or approach, because of this and that".

.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - release-*
   pull_request: {}
 
 env:

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - release-*
 
 jobs:
   deploy:

.github/workflows/publish.yml

@@ -107,10 +107,13 @@ jobs:
         env:
           GITHUB_REF: ${{ github.ref }}
         run: |
+          # rebuild-image
           if [ "${{ inputs.image-tag }}" != "" ]; then
             TAG="${{ inputs.image-tag }}${{ inputs.tag-suffix }}"
-          elif [ "$GITHUB_REF" == "refs/heads/main" ]; then
-            TAG=main${{ inputs.tag-suffix }}
+          # main / release-x.y
+          elif [[ "$GITHUB_REF" == "refs/heads/main" || "$GITHUB_REF" =~ refs/heads/release-.*  ]]; then
+            TAG=${GITHUB_REF#refs/heads/}${{ inputs.tag-suffix }}
+          # Pull Request
           else
             TAG=$(make docker.tag)
           fi

.github/workflows/release.yml

@@ -7,6 +7,10 @@ on:
         description: 'version to release, e.g. v1.5.13'
         required: true
         default: 'v0.1.0'
+      source_ref:
+        description: 'source ref to publish from. E.g.: main or release-x.y'
+        required: true
+        default: 'main'
 
 env:
   IMAGE_NAME: ghcr.io/${{ github.repository }}
@@ -65,6 +69,7 @@ jobs:
           git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
 
       - name: Update Docs
+        if: github.ref == 'refs/heads/main'
         run: make docs.publish DOCS_VERSION=${{ github.event.inputs.version }} DOCS_ALIAS=latest
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
@@ -84,7 +89,7 @@ jobs:
       contents: write
 
     env:
-      SOURCE_TAG: main${{ matrix.tag_suffix }}
+      SOURCE_TAG: ${{ github.event.inputs.source_ref }}${{ matrix.tag_suffix }}
       RELEASE_TAG: ${{ github.event.inputs.version }}${{ matrix.tag_suffix }}
 
     steps:

.github/workflows/update-deps.yml

@@ -0,0 +1,73 @@
+name: "Update dependencies"
+on:
+  schedule:
+    # Monday, 10AM UTC
+    - cron: "0 10 * * 1"
+
+  workflow_dispatch:
+    inputs: {}
+
+
+jobs:
+  branches:
+    name: get branch data
+    runs-on: ubuntu-latest
+    outputs:
+      branches: ${{ steps.branches.outputs.branches }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.ref }}
+      - name: set branches output
+        id: branches
+        # outputs the two most recent `release-x.y` branches plus `main` as JSON
+        run: |
+          echo "branches=$(git branch -a | grep -E "remotes/origin/(main|release-)" | sed 's/  remotes\/origin\///' | sort -V | tail -2 | jq -R -s -c 'split("\n") | map(select(length > 0)) | . + ["main"]')" >> $GITHUB_OUTPUT
+
+  update-dependencies:
+    runs-on: ubuntu-latest
+    needs: branches
+    strategy:
+      matrix:
+        branch: ${{ fromJson(needs.branches.outputs.branches) }}
+    steps:
+    - name: Setup Go
+      uses: actions/setup-go@v3
+      with:
+        go-version: "1.19"
+
+      # we can not use the default GHA token, as it prevents subsequent GHA
+      # from running: we can create a PR but the tests won't run :/
+    - name: Generate token
+      id: generate_token
+      uses: tibdex/github-app-token@v1
+      with:
+        app_id: ${{ secrets.APP_ID }}
+        private_key: ${{ secrets.PRIVATE_KEY }}
+    - uses: actions/checkout@v3
+      with:
+        token: ${{ steps.generate_token.outputs.token }}
+        ref: ${{ matrix.branch }}
+        fetch-depth: 0
+    - name: create pull request
+      run: |
+        git config --global user.email "ExternalSecretsOperator@users.noreply.github.com"
+        git config --global user.name "External Secrets Operator"
+        BRANCH=update-deps-$(date "+%s")
+        make update-deps || true
+
+        if git diff-index --quiet HEAD --; then
+          echo "nothing changed. skipping."
+          exit 0;
+        fi
+
+        git checkout -b $BRANCH
+        git add -A
+        git commit -m "update dependencies" -s
+        git push origin $BRANCH
+        gh pr create -B ${{ matrix.branch }} -H ${BRANCH} --title 'chore: update dependencies' --body 'Update dependencies'
+      env:
+        GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}

design/006-LTS-release.md

@@ -0,0 +1,60 @@
+# Long Term Support Policy
+
+WRT: https://github.com/external-secrets/external-secrets/issues/2044
+
+We want to provide security patches and critical bug fixes in a timely manner to our users.
+To do so, we offer long-term support for our latest two (N, N-1) software releases.
+We aim for a 2-3 month **minor** release cycle, i.e. a given release is supported for about 4-6 months.
+
+We want to cover the following cases:
+
+- weekly image rebuilds to update OS dependencies
+- weekly go dependency updates
+- backport bug fixes on demand
+
+Note: features cut off on a minor release will not be backported to older releases.
+
+## Automatic Updates
+
+We have set up a Github Action (GHA) which will automatically update the `go.mod` dependencies once per week or on request.
+The GHA will make the necessary code changes and opens a PR. Once approved and merged into `main` or `release-x.y` our build pipelines
+will build and push the artifact to ghcr.
+
+## Manual Updates
+
+Bug Fixes will be merged onto each release branch individually.
+This is achieved by creating separate PRs from a corresponding branch of the release
+(e.g. bug fixes targetting `release-1.0` should be created from `release-1.0` branch).
+Once approved and merged into `main` or `release-x.y`, ou build pipeline will build and push the artifact to ghcr
+
+## Process
+
+### Branch Management
+
+When a new **minor release** is cut and merged into `main`, we must branch off to `release-{major}.{minor}`.
+This is the long-lived release branch that will get dependency updates and bug fixes.
+In case we do a `patch` release we **must also merge** into the correct `release-{major}.{minor}` branch.
+
+### Release Issue Template
+
+We'll have a release issue template that gives the release lead a task list to work through all the steps needed to create a release.
+
+#### Release Preparation Tasks
+
+- [ ] ask in `#external-secrets-dev` if we're ready for a release cut-off or if something needs to get urgently in
+- [ ] docs: [stability & support page](https://external-secrets.io/main/introduction/stability-support/) is up to date
+  - [ ] version table
+  - [ ] Provider Stability and Support table
+  - [ ] Provider Feature Support table
+- [ ] docs: update [roadmap page](https://external-secrets.io/main/contributing/roadmap/)
+- [ ] tidy up [Project Board](https://github.com/orgs/external-secrets/projects/2)
+  - [ ] move issues to next milestone
+  - [ ] close milestone
+
+#### Release Execution
+
+- [ ] Follow the [Release Process guide](https://external-secrets.io/main/contributing/release/)
+
+#### After Release Tasks
+
+- [ ] Announce release on `#external-secrets` in Slack

docs/contributing/release.md

@@ -5,10 +5,10 @@ The external-secrets project is released on a as-needed basis. Feel free to open
 ## Release ESO
 
 1. Run `Create Release` Action to create a new release, pass in the desired version number to release.
-2. GitHub Release, Changelog will be created by the `release.yml` workflow which also promotes the container image.
-3. update Helm Chart, see below
-4. update OLM bundle, see [helm-operator docs](https://github.com/external-secrets/external-secrets-helm-operator/blob/main/docs/release.md#operatorhubio)
-5. Announce the new release in the `#external-secrets` Kubernetes Slack
+    1. note: choose the right `branch` to execute the action: use `main` when creating a new release. Use `release-x.y` when you want to bump a LTS release.
+1. GitHub Release, Changelog will be created by the `release.yml` workflow which also promotes the container image.
+1. update Helm Chart, see below
+1. update OLM bundle, see [helm-operator docs](https://github.com/external-secrets/external-secrets-helm-operator/blob/main/docs/release.md#operatorhubio)
 
 ## Release Helm Chart
 
@@ -18,6 +18,9 @@ The external-secrets project is released on a as-needed basis. Feel free to open
 1. run `/ok-to-test-managed` commands for all cloud providers
 1. merge PR if everyhing is green
 1. CI picks up the new chart version and creates a new GitHub Release for it
+1. create/merge into release branch
+    1. on a `minor` release: create a new branch `release-x.y`
+    1. on a `patch` release: merge main into `release-x.y`
 
 ## Release OLM Bundle
 

docs/introduction/stability-support.md

@@ -5,18 +5,26 @@ hide:
 
 This page lists the status, timeline and policy for currently supported ESO releases and its providers. Please also see our [deprecation policy](deprecation-policy.md) that describes API versioning, deprecation and API surface.
 
-## External Secrets Operator
-
-We are currently in beta and support **only the latest release** for the time being.
-
-| ESO Version | Kubernetes Version |
-| ----------- | ------------------ |
-| 0.8.x       | 1.19 → 1.26        |
-| 0.7.x       | 1.19 → 1.26        |
-| 0.6.x       | 1.19 → 1.24        |
-| 0.5.x       | 1.19 → 1.24        |
-| 0.4.x       | 1.16 → 1.24        |
-| 0.3.x       | 1.16 → 1.24        |
+## Supported Versions
+
+We want to provide security patches and critical bug fixes in a timely manner to our users.
+To do so, we offer long-term support for our latest two (N, N-1) software releases.
+We aim for a 2-3 month minor release cycle, i.e. a given release is supported for about 4-6 months.
+
+We want to cover the following cases:
+
+- regular image rebuilds to update OS dependencies
+- regular go dependency updates
+- backport bug fixes on demand
+
+| ESO Version | Kubernetes Version | Release Date | End of Life    |
+| ----------- | ------------------ | ------------ | -------------- |
+| 0.8.x       | 1.19 → 1.26        | Mar 16, 2023 | Release of 1.0 |
+| 0.7.x       | 1.19 → 1.26        | Dec 11, 2022 | Release of 0.9 |
+| 0.6.x       | 1.19 → 1.24        | Oct 9, 2022  | Mar 16, 2023   |
+| 0.5.x       | 1.19 → 1.24        | Apr 6, 2022  | Dec 11, 2022   |
+| 0.4.x       | 1.16 → 1.24        | Feb 2, 2022  | Oct 9, 2022    |
+| 0.3.x       | 1.16 → 1.24        | Jul 25, 2021 | Apr 6, 2022    |
 
 ## Provider Stability and Support Level