docs: add GitHub Actions Code References integration documentation #6600
Conversation
TyroneOrrego
requested review from
matthewelwell
and removed request for
a team
|
@TyroneOrrego is attempting to deploy a commit to the Flagsmith Team on Vercel. A member of the Team first needs to authorize it. |
|
|
||
| 1. **Your repository** triggers a GitHub Actions workflow (via schedule, push, pull request, or release) | ||
| 2. **Reusable workflow** from `github.com/Flagsmith/ci-tools` (`.github/workflows/collect-code-references.yml`) is invoked | ||
| 3. **Docker image** (`flagsmith-find-code-references`) is pulled and executed in your CI environment |
There was a problem hiding this comment.
Not true. The workflow is using composite actions, not Docker-based ones.
| Before you begin, ensure you have: | ||
|
|
||
| - A Flagsmith project with feature flags configured | ||
| - A Flagsmith Admin API key with permissions to create code references (found in **Settings** > **API Keys** in your Flagsmith dashboard) |
There was a problem hiding this comment.
@emyller I don't think we've got specific permissions for that?
There was a problem hiding this comment.
Nope. This just needs an admin key.
|
|
||
| - **Daily crontab (scheduled)**: Proactively finds references and helps identify stale flags in Flagsmith that may no longer be used in your codebase. Running daily ensures you catch flags that have been removed from code but still exist in Flagsmith. | ||
|
|
||
| - **Pull request**: Notifies you when references are removed in PRs, helping you catch flag removals before they're merged. This allows you to review and clean up flags as part of your code review process. |
There was a problem hiding this comment.
Notifies you when references are removed in PRs
@emyller is this true?
| ## How It Works | ||
|
|
||
| The reusable workflow (`collect-code-references.yml` in `Flagsmith/ci-tools`) performs the following steps: | ||
|
|
||
| 1. **Fetches feature names**: Retrieves all feature flag names from your Flagsmith project using the Admin API. This provides the list of flags to search for in your codebase. | ||
|
|
||
| 2. **Pulls Docker image**: Downloads the `flagsmith-find-code-references` Docker image from the container registry. This image contains the scanning logic and runs entirely in your CI environment. | ||
|
|
||
| 3. **Scans your codebase**: The Docker image searches through your repository files for references to feature flag names using regex pattern matching. It processes files in your repository, looking for exact matches of feature flag names. | ||
|
|
||
| 4. **Collects references**: For each match found, the scanner gathers: | ||
| - File path (relative to repository root) | ||
| - Line number where the flag is referenced | ||
| - Code context around the reference | ||
|
|
||
| 5. **Uploads to Flagsmith**: Sends the collected code references to the Flagsmith API via the Admin API endpoint. The references are associated with the corresponding feature flags in your project. | ||
|
|
||
| The scanning process uses regex patterns to find feature flag references in your code. It automatically excludes common build artifacts and dependencies (like `node_modules`, `.git`, `venv`, `.cache`, `dist`, `build`, etc.) to focus on your source code. You can customize the exclusion patterns using the `exclude_patterns` input parameter. | ||
|
|
There was a problem hiding this comment.
This entire section feels quite redundant
| In the Flagsmith dashboard, you'll see these references listed under each feature flag, allowing you to: | ||
| - Click through to the exact file and line in your repository | ||
| - See how the flag is being used in context | ||
| - Identify all locations where a flag is referenced across your codebase |
There was a problem hiding this comment.
I feel like a single screenshot example would work better here than a bullet point list.
|
|
||
| ### Workflow Fails with "Failed to obtain features from Flagsmith" | ||
|
|
||
| This error indicates an authentication or API access issue. | ||
|
|
||
| **Solutions:** | ||
| - Verify your `FLAGSMITH_ADMIN_API_KEY` secret is correctly set in your repository. | ||
| - Ensure your API key has the necessary permissions to read project features. | ||
| - Check that the `flagsmith_admin_api_url` is correct for your Flagsmith instance. | ||
| - Verify your `FLAGSMITH_PROJECT_ID` variable matches a valid project in your Flagsmith organisation. | ||
|
|
||
| ### Workflow Fails with "Failed to read feature references from code" | ||
|
|
||
| This error suggests an issue with the code scanning process. | ||
|
|
||
| **Solutions:** | ||
| - Check that your repository has code checked out (the workflow handles this automatically). | ||
| - Review the workflow logs for specific file access errors. | ||
| - Ensure your repository structure is accessible to the GitHub Actions runner. | ||
|
|
||
| ### Workflow Fails with "Failed to upload code references to Flagsmith" | ||
|
|
||
| This error indicates a problem sending data to the Flagsmith API. | ||
|
|
||
| **Solutions:** | ||
| - Verify your API key has write permissions for code references. | ||
| - Check that your Flagsmith instance is accessible from GitHub Actions runners. | ||
| - Review the API response in the workflow logs for specific error messages. | ||
| - Ensure your project ID is correct and the project exists. |
There was a problem hiding this comment.
I'd rather not have a troubleshooting section at all than have a troubleshooting section this vague.
@emyller I'm not sure any of this is at all based on any real usage?
There was a problem hiding this comment.
Seems not. I do not recognise the error messages, or even the scenarios. 🤔
| If the scan includes files you want to exclude, or excludes files you want to include: | ||
|
|
||
| **Solutions:** | ||
| - Use the `exclude_patterns` input to add additional exclusion patterns. |
There was a problem hiding this comment.
We're not shipping the exclude_patterns input.
| - Schedule scans during off-peak hours if running on a schedule. | ||
| - For very large repositories, consider scanning only specific directories by excluding others. | ||
|
|
||
| ## Verifying Your Setup |
There was a problem hiding this comment.
How is this different from the ### Step 4: Verify the Setup section earlier?
|
|
||
| ## Simple Setup | ||
|
|
||
| The quickest way to set up code references is using the reusable workflow from the Flagsmith CI tools repository (`github.com/Flagsmith/ci-tools`). This approach is recommended for most scenarios as it requires minimal configuration and handles all the steps automatically. |
There was a problem hiding this comment.
This repository does not exist. 🤔 Did you mean https://github.com/Flagsmith/ci?
…curacy and clarity
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
docs/docs/third-party-integrations/ci-cd/github-actions-code-references.md
Outdated
Show resolved
Hide resolved
| with: | ||
| flagsmith_project_id: ${{ vars.FLAGSMITH_PROJECT_ID }} | ||
| flagsmith_admin_api_url: https://api.flagsmith.com/ | ||
| ``` |
There was a problem hiding this comment.
Highly repetitive trigger examples with minimal variation
Low Severity
Three near-identical YAML code blocks (Pull Requests, Push Events, Releases) repeat the same jobs: configuration verbatim—only the on: trigger differs. This pattern of duplicating ~10 lines of identical boilerplate across three examples increases maintenance burden and makes the documentation harder to scan. A single consolidated example showing the common job configuration with annotated trigger options would be clearer and more maintainable.
…nces documentation
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 3 potential issues.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| 3. **Collects references** including file paths, line numbers, and code context | ||
| 4. **Uploads to Flagsmith** via the Admin API endpoint | ||
|
|
||
| The scanning process automatically excludes common build artifacts and dependencies (like `node_modules`, `.git`, `venv`, `.cache`, `dist`, `build`, etc.) to focus on your source code. |
There was a problem hiding this comment.
Redundant workflow steps explanation duplicates Architecture Overview
Low Severity
The "How It Works" section (lines 291-300) largely duplicates the "Architecture Overview" section (lines 11-19). Both sections describe the same workflow steps: fetching feature names, scanning the codebase, collecting references, and uploading to Flagsmith. This redundancy increases maintenance burden and risks inconsistent updates if only one section is modified.
Additional Locations (1)
| 3. **Collects references** including file paths, line numbers, and code context | ||
| 4. **Uploads to Flagsmith** via the Admin API endpoint | ||
|
|
||
| The scanning process automatically excludes common build artifacts and dependencies (like `node_modules`, `.git`, `venv`, `.cache`, `dist`, `build`, etc.) to focus on your source code. |
There was a problem hiding this comment.
Excluded directories list repeated in two locations
Low Severity
The exclusion patterns (node_modules, .git, venv, .cache, dist, build, etc.) are documented both in the "What Gets Scanned" section (lines 103-106) and again in line 300 within "How It Works". This duplication means any future changes to exclusion patterns would need updates in both places, risking inconsistency.
Additional Locations (1)
|
|
||
| :::tip | ||
| For most use cases, a combination of **daily scheduled scans** and **pull request or push triggers** provides good coverage without excessive CI usage. | ||
| ::: |
There was a problem hiding this comment.
Trigger use cases section redundant with trigger examples
Low Severity
The "Trigger Types and Use Cases" section (lines 273-289) summarizes when to use each trigger type (scheduled, pull request, release, push, manual), but this information is already implicitly conveyed by the "Running on Triggers" section (lines 160-226) which provides examples for each trigger type with descriptive headings and context.
Additional Locations (1)
…d clarity and structure
emyller
left a comment
emyller
left a comment
There was a problem hiding this comment.
The document is much easier to review now, thank you.
I've added some comments that need addressing, and a suggestion of structure to the document.
Additionally:
- Please do not make GitHub the core of this document. Code References will likely expand to other vendors in the future. GitHub is but an integration option — just currently the only one.
- If possible please try this functionality yourself. I believe the user experience will improve understanding of this product.
There was a problem hiding this comment.
I don't think this is the right place for this document to live, because Code References is not a CI/CD product. Rather, it is a feature flag management feature that currently uses CI scripting to integrate — in the future, we might use other forms, e.g. a GitHub app.
Suggested file location: docs/docs/managing-flags/code-references.md.
| @@ -0,0 +1,113 @@ | |||
| --- | |||
| title: GitHub Actions Code References | |||
There was a problem hiding this comment.
The product name is "Code References". GitHub is but one of the vendors we integrate with Code References — in all fairness, currently the only one, but we do intend to expand.
| --- | ||
| title: GitHub Actions Code References | ||
| sidebar_label: GitHub Actions Code References | ||
| sidebar_position: 1 |
There was a problem hiding this comment.
Please ensure this comes last in the sidebar section.
|
|
||
| ## How it Works | ||
|
|
||
| The integration uses a GitHub Action to scan your code for feature flag keys. |
There was a problem hiding this comment.
What does "feature flag keys" mean? To be clear: the integration scans the code for feature flag evaluations.
| The integration uses a GitHub Action to scan your code for feature flag keys. | ||
|
|
||
| 1. **Local Scan**: The runner searches your repository for flag keys using pattern matching. | ||
| 2. **Metadata Sync**: File paths, line numbers, and context snippets are sent to the Flagsmith Admin API. |
There was a problem hiding this comment.
We do not send "context snippets". I would not use Code References if Flagsmith would copy any portion of my actual code.
| * `FLAGSMITH_ADMIN_API_KEY` (Secret) | ||
| * `FLAGSMITH_PROJECT_ID` (Variable) |
There was a problem hiding this comment.
This should be the correct place to explain where to find each value, rather than a "Prerequisites" section IMO.
|
|
||
| ### 2. Create the Workflow | ||
|
|
||
| Add `.github/workflows/flagsmith-sync.yml` to your repository: |
There was a problem hiding this comment.
"flagsmith-sync" is a very generic name. Code References is not the only integration we offer with GitHub.
| :::caution Why no Pull Request triggers? | ||
| This workflow syncs the current state of your code to the dashboard. Running it on Pull Requests will overwrite your dashboard with unmerged code references. Only run this on your default branch. | ||
| ::: |
There was a problem hiding this comment.
This adds no value to the document. Please remove.
| ### Self-Hosted Flagsmith | ||
|
|
||
| If you are self-hosting Flagsmith, provide your API URL in the `with` block: | ||
|
|
||
| ```yaml | ||
| with: | ||
| flagsmith_project_id: ${{ vars.FLAGSMITH_PROJECT_ID }} | ||
| flagsmith_admin_api_url: https://your-api-url.com/api/v1/ | ||
|
|
||
| ``` |
There was a problem hiding this comment.
The YAML snippet here is out of context. I'm not sure if this should be a separate section, given how close knitted it is with both Simple and Advanced configuration options.
| ### Exclusions | ||
|
|
||
| The scanner automatically ignores common directories like `node_modules`, `dist`, `.git`, and `bin`. |
There was a problem hiding this comment.
This is not true. The scanner simply relies on git ls-files. We don't need to mention it here I think.
3 participants
Thanks for submitting a PR! Please check the boxes below:
docs/if required so people know about the feature.Changes
Contributes to #5704.
I clarified the GitHub Actions Code References docs by introducing a short “Setup options” section that contrasts Simple Setup (reusable workflow, quickest for most users) with Advanced Setup (granular individual actions for customization), kept the simple path as the recommended default, added a concrete advanced workflow example, strengthened the privacy/security explanation that the Docker image runs entirely in your CI and only sends metadata to Flagsmith, and tidied up minor duplication and formatting (including normalising the audit-logs.md frontmatter without changing its content).
How did you test this code?
This PR went through a QA process with Flagsmith's team