Epic: GitHub Actions code references integration

[emyller]

From #5066.

User Experience Proposal

When viewing stale feature flags in the Flagsmith UI, display feature flag references found in repositories from the team's GitHub organization.

Pending feature mockups.

This is intended to prompt developers to clean up stale feature flags by making it easier to coordinate work — and maybe positively annoying.

GitHub Actions

By leveraging GitHub Actions, we can build a CI product that's easy to plug in and comes with a great architecture fit.

• GHA allows for code scans triggered by each team's git-push activity, also expanding visibility to PRs and releases.
• Favoring privacy, our code runs in CI runners chosen by each team — could be GitHub runners, or their own. We don't have access to anyone's code.
• It offloads computer work to each team's CI cost with GHA.

The above diagram is an architecture overview of how customers, such as github.com/acmeinc, can plug in a GitHub action from github.com/Flagsmith/ci-tools. A CI workflow snippet in GitHub Actions language would resemble this untested snippet:

name: find-flagsmith-code-references

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 8 * * *'  # Every day at 8 am UTC

jobs:

  fetch-stale-feature-flags:
    if: github.event_name == 'schedule'
    uses: flagsmith/ci-tools/.github/workflows/fetch-stale-feature-flags.yml@0.0.1
    secrets:
      flagsmith_server_key: ${{ secrets.FLAGSMITH_SERVER_KEY }}
    
  report-code-references-from-stale-feature-flags:
    needs: [fetch-stale-feature-flags]
    if: ${{ needs.fetch-stale-feature-flags.outputs.stale_features }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker://ghcr.io/flagsmith/flagsmith-find-code-references:0.0.1
        id: find_stale_flag_code_references
        with:
          features: ${{ needs.fetch-stale-feature-flags.outputs.stale_features }}
          flagsmith_server_key: ${{ secrets.FLAGSMITH_SERVER_KEY }}
      - uses: flagsmith/ci-tools/.github/actions/report-code-references-to-flagsmith.yml@0.0.1
        with:
          references_json: ${{ steps.find_stale_flag_code_references.outputs.references_json }}

  report-code-references-from-diff:
    if: contains(fromJSON('["push", "pull_request"]'), github.event_name)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker://ghcr.io/flagsmith/flagsmith-find-code-references:0.0.1
        id: find_diff_flag_code_references
        with:
          from_diff_since: ${{ github.event.pull_request.head.sha }}
          flagsmith_server_key: ${{ secrets.FLAGSMITH_SERVER_KEY }}
      - uses: flagsmith/ci-tools/.github/actions/report-code-references-to-flagsmith.yml@0.0.1
        with:
          references_json: ${{ steps.find_diff_flag_code_references.outputs.references_json }}

Suggested Plan

Here's an overview of the effort this PoC will take, as action items:

Backend

1. Ensure there is, or implement an API path to list stale feature flags.
2. Implement a reusable GitHub Action to fetch stale feature flags using that endpoint.
3. Implement a code scanning algorithm that will find feature flag references into a public Docker image.
   • It should accept either a list of feature flags, or some Git diff.
   • It should return code references in JSON format, e.g. [{file_path, line_number, column_number, code_portion?}, ...]
4. Implement an API path to receive and persist code references associated to feature flags.
5. Implement a reusable GitHub Action to report code references to the Flagsmith API.
   • This functionality could be bundled to the Docker image, but it might be best to keep steps granular and clear.
6. BONUS: Ship this functionality to customers via GitHub Actions directory.

UI Changes

1. Display code references in:
   • The list of [stale] feature flags, summarized, e.g. "3 code references" (click to expand).
   • The feature flag modal, detailed, e.g. "Code references: - foo.py:12, - bar.js:34" (click to visit in GitHub).
2. Add the ability to list stale features only.

[khvn26]

1. As far as I understand our product, instead of inventing arbitrary logic for detecting stale flags, we should look for features tagged as Stale, and improve the tagging logic instead. This invalidates Add "last updated" date to feature flags API #5703 and, in part, Epic: GitHub Actions code references integration #5701. @matthewelwell feel free to intervene here.

2. I'd rather we think on the UX more, and provide a more meaningful and ergonomic set of actions. For instance, I don't understand yet why we need a dedicated reusable workflow to perform one API call. Why can't we bundle it with the action itself, and cache the results? It would shave off a whole job from your example workflow code.

[emyller]

we should look for features tagged as Stale, and improve the tagging logic instead.

I just came across the stale tag type in the code, thanks for pointing it out! I was under the impression the definition of stale was time-based since the flag's last update. Let's use #5703 to discuss and reshape or close the issue.

I don't understand yet why we need a dedicated reusable workflow to perform one API call.

One reason is privacy: actions can have access to the code (if they come after actions/checkout), while reusable workflows don't need to. With that in mind, a granular trio (1. retrieve flags, 2. scan code, and 3. push references) would allow us to prevent privacy concerns. However, it's important to note that we don't need to go that route yet for a POC.

Another reason is CI flexibility. If we ship reusable workflows along with an action, we can make it easier for customers to set up Flagsmith CI, as they can just use one workflow from github.com/flagsmith/ci for both releases, pull-requests, or any other event, rather than having to set up a new workflow and rely on instructions on how to use the action along with it.

And then another reason is portability. Having granular steps makes it easier for us to develop and maintain the same functionality across multiple CI vendors besides GHA in the future.

The architecture is meant to reduce the integration steps, in despite of giving us a bit more work. Then again: during this POC phase, we'll likely skip a lot of that.

Let me know if that makes sense.