Skip to content

Commit 0069cff

Browse files
emylleremyller
authored
ci(GHA): Collect feature flag code references using flagsmith/ci (#6590)
1 parent 88e448b commit 0069cff

File tree

5 files changed

+156
-153
lines changed

5 files changed

+156
-153
lines changed

‎.github/workflows/platform-collect-code-references.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Code references
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
jobs:
10+
collect-code-references:
11+
name: Collect
12+
uses: Flagsmith/ci/.github/workflows/collect-code-references.yml@v1.0.0
13+
permissions:
14+
contents: read # For scanning feature flag code references
15+
with:
16+
flagsmith_project_id: ${{ fromJSON(vars.FLAGSMITH_PROJECT_ID) }}
17+
flagsmith_admin_api_url: https://api.flagsmith.com
18+
secrets:
19+
flagsmith_admin_api_key: ${{ secrets.FLAGSMITH_CODE_REFERENCES_API_KEY }}

‎.github/workflows/poc-github-code-references.yml‎

Lines changed: 0 additions & 153 deletions
This file was deleted.

‎docs/docs/managing-flags/code-references.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: Code References
3+
sidebar_label: Code References
4+
sidebar_position: 30
5+
---
6+
7+
Integrate with Code References to track feature flag usage in your codebase, and unlock new functionality in Flagsmith:
8+
9+
- Identify the impact of each feature across multiple repositories
10+
- Navigate through the business logic in the code from a feature's perspective
11+
- Coordinate cleanup work around stale feature flags easier
12+
13+
![Code References badges displayed in the Features list, each containing a count of references of that feature](./code-references/feature-list.png)
14+
15+
<p style={{textAlign: 'center', fontSize: '0.9em', color: 'gray', marginTop: '-1.5rem'}}>Code Reference counts displayed in Features list</p>
16+
17+
:::info
18+
19+
We currently only offer integrating with GitHub. Support to other VCS platforms is coming soon.
20+
21+
:::
22+
23+
---
24+
25+
## Integrate with GitHub
26+
27+
### Simple configuration
28+
29+
For most cases, our [reusable workflow](https://github.com/Flagsmith/ci/blob/main/.github/workflows/collect-code-references.yml) is enough.
30+
31+
Add a new GitHub Actions workflow to **each repository** to integrate with Code References:
32+
33+
```yaml
34+
# .github/workflows/flagsmith-code-references.yml
35+
name: Flagsmith Code references
36+
on:
37+
push:
38+
branches:
39+
- main # Update references on every update to the default branch
40+
jobs:
41+
collect-code-references:
42+
name: Collect
43+
uses: Flagsmith/ci/.github/workflows/collect-code-references.yml@v1.0.0
44+
permissions:
45+
contents: read # For scanning feature flag code references
46+
with:
47+
flagsmith_project_id: ${{ fromJSON(vars.FLAGSMITH_PROJECT_ID) }}
48+
flagsmith_admin_api_url: https://api.flagsmith.com # Or your Flagsmith instance URL
49+
secrets:
50+
flagsmith_admin_api_key: ${{ secrets.FLAGSMITH_CODE_REFERENCES_API_KEY }}
51+
```
52+
53+
This workflow needs the following added to [_Settings > Secrets and variables > Actions_](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) in GitHub:
54+
55+
- `FLAGSMITH_PROJECT_ID` (variable): obtain from the Flagsmith dashboard URL, e.g. `/project/<id>/...`
56+
- `FLAGSMITH_CODE_REFERENCES_API_KEY` (secret): obtain from _Organisation Settings > API Keys_ in Flagsmith
57+
58+
### Advanced configuration
59+
60+
If you need a customised workflow, integrating with individual actions is also possible. They can be useful to certain use cases, for example:
61+
62+
- Customising cloning source code for reference scanning
63+
- Combining multiple repositories into a single workflow (umbrella repositories)
64+
- Any other customisation of the integration steps
65+
66+
```yaml
67+
name: Flagsmith Code References
68+
on:
69+
push:
70+
branches:
71+
- main
72+
jobs:
73+
collect-code-references:
74+
name: Collect code references
75+
runs-on: ubuntu-latest
76+
permissions:
77+
contents: read # For scanning feature flag code references
78+
env:
79+
FLAGSMITH_ADMIN_API_URL: https://api.flagsmith.com # Or your Flagsmith instance URL
80+
steps:
81+
- name: Checkout code
82+
uses: actions/checkout@v4
83+
84+
- name: Fetch feature names
85+
id: fetch-feature-names
86+
uses: Flagsmith/ci/.github/actions/fetch-feature-names@v1.0.0
87+
with:
88+
flagsmith_project_id: ${{ vars.FLAGSMITH_PROJECT_ID }}
89+
flagsmith_admin_api_url: ${{ env.FLAGSMITH_ADMIN_API_URL }}
90+
flagsmith_admin_api_key: ${{ secrets.FLAGSMITH_CODE_REFERENCES_API_KEY }}
91+
92+
- name: Scan code references
93+
id: scan-code-references
94+
uses: Flagsmith/ci/.github/actions/scan-code-references@v1.0.0
95+
with:
96+
feature_names: ${{ steps.fetch-feature-names.outputs.feature_names }}
97+
98+
- name: Upload code references
99+
uses: Flagsmith/ci/.github/actions/upload-code-references@v1.0.0
100+
with:
101+
code_references: ${{ steps.scan-code-references.outputs.code_references }}
102+
flagsmith_project_id: ${{ vars.FLAGSMITH_PROJECT_ID }}
103+
flagsmith_admin_api_url: ${{ env.FLAGSMITH_ADMIN_API_URL }}
104+
flagsmith_admin_api_key: ${{ secrets.FLAGSMITH_CODE_REFERENCES_API_KEY }}
105+
repository_url: ${{ github.server_url }}/${{ github.repository }}
106+
revision: ${{ github.sha }}
107+
```
108+
109+
This workflow needs the following added to [_Settings > Secrets and variables > Actions_](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) in GitHub:
110+
111+
- `FLAGSMITH_PROJECT_ID` (variable): obtain from the Flagsmith dashboard URL, e.g. `/project/<id>/...`
112+
- `FLAGSMITH_CODE_REFERENCES_API_KEY` (secret): obtain from _Organisation Settings > API Keys_ in Flagsmith
113+
114+
---
115+
116+
## How it works
117+
118+
Code References rely on CI scripts isolated to three steps:
119+
120+
1. Fetch feature names from Flagsmith (communicates with Flagsmith API)
121+
2. Scan code references for the project's features (**does not** communicate with Flagsmith API)
122+
3. Upload code references to Flagsmith (communicates with Flagsmith API)
123+
124+
:::important
125+
126+
Integrating with Code References **does not** expose your source code to Flagsmith. Our API only collects file paths, and line numbers, of code locations likely containing a feature flag evaluation. Code scanning is performed locally on the CI runner.
127+
128+
:::
129+
130+
Feature details will expand on the _Code References_ tab, and list locations of each code reference:
131+
132+
![Code References listed for each repository within Feature details](./code-references/feature-details.png)
133+
134+
## Related
135+
136+
- [Admin API Authentication](/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication): Generate API keys for Code References
137+
- [Flag Lifecycle](/best-practices/flag-lifecycle): Learn when to remove short-lived flags from your code

‎docs/docs/managing-flags/code-references/feature-details.png‎

218 KB
Loading

‎docs/docs/managing-flags/code-references/feature-list.png‎

156 KB
Loading

0 commit comments

Comments
 (0)