Skip to content

Commit fbcd104

Browse files
vredchenkoclaude
vredchenko
and
claude
committed
feat: add GitHub labels sync script and CI/CD workflow
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent d096218 commit fbcd104

File tree

4 files changed

+466
-1
lines changed

4 files changed

+466
-1
lines changed

‎.github/workflows/gitflow.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Gitflow
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
mode:
7+
description: 'Label sync mode'
8+
required: true
9+
default: 'check'
10+
type: choice
11+
options:
12+
- check
13+
- sync
14+
push:
15+
branches: [main]
16+
paths:
17+
- 'core/github-tags-config.ts'
18+
- 'tools/github/**'
19+
20+
jobs:
21+
check-labels:
22+
name: Check Label Conformity
23+
runs-on: ubuntu-latest
24+
if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.mode == 'check')
25+
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
30+
- name: Setup Node.js
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: '22'
34+
35+
- name: Install dependencies
36+
run: npm install
37+
38+
- name: Check labels
39+
env:
40+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
41+
run: npx tsx tools/github/sync-labels.ts --check --verbose
42+
43+
sync-labels:
44+
name: Sync Labels
45+
runs-on: ubuntu-latest
46+
if: github.event_name == 'workflow_dispatch' && github.event.inputs.mode == 'sync'
47+
48+
steps:
49+
- name: Checkout
50+
uses: actions/checkout@v4
51+
52+
- name: Setup Node.js
53+
uses: actions/setup-node@v4
54+
with:
55+
node-version: '22'
56+
57+
- name: Install dependencies
58+
run: npm install
59+
60+
- name: Sync labels
61+
env:
62+
GH_TOKEN: ${{ secrets.LABEL_SYNC_TOKEN }}
63+
run: npx tsx tools/github/sync-labels.ts --sync --verbose

‎docs/how-to/sync-github-labels.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# How to Sync GitHub Labels
2+
3+
This guide explains how to manage GitHub labels across SmartEM repositories using the label sync tool.
4+
5+
## Overview
6+
7+
The SmartEM ecosystem uses a standardised set of GitHub labels across four repositories:
8+
9+
- `DiamondLightSource/smartem-decisions`
10+
- `DiamondLightSource/smartem-frontend`
11+
- `DiamondLightSource/smartem-devtools`
12+
- `DiamondLightSource/fandanGO-cryoem-dls`
13+
14+
Labels are defined in `core/github-tags-config.ts` and synced using `tools/github/sync-labels.ts`.
15+
16+
## Prerequisites
17+
18+
- Node.js 18+
19+
- GitHub CLI (`gh`) installed and authenticated
20+
- For sync operations: write access to target repositories
21+
22+
## Label Categories
23+
24+
### Types of Work
25+
26+
Labels that categorise the nature of work being done:
27+
28+
| Label | Colour | Purpose |
29+
|-------|--------|---------|
30+
| documentation | teal | Improvements or additions to project documentation |
31+
| testing | green | Writing, updating, or fixing automated tests |
32+
| bugfixing | red | Fixing defects or unexpected behavior |
33+
| development | purple | New features or functionality implementation |
34+
| refactoring | orange | Code restructuring without changing behavior |
35+
| research | cyan | Investigation, spikes, or proof-of-concept work |
36+
| devops | slate | CI/CD, deployment, infrastructure, or tooling |
37+
| security | maroon | Security fixes, audits, or vulnerability remediation |
38+
| admin | brown | Project maintenance, dependency updates |
39+
| enhancement | dark cyan | Minor improvements to existing functionality |
40+
41+
### System Components
42+
43+
Labels that identify which part of the system is affected:
44+
45+
| Label | Colour Family | Purpose |
46+
|-------|---------------|---------|
47+
| smartem-backend | Blue (dark) | Core backend services |
48+
| smartem-backend:db | Blue (mid) | Database and data layer |
49+
| smartem-backend:api | Blue (light) | REST API endpoints |
50+
| smartem-agent | Gold | EPU workstation agent |
51+
| smartem-frontend | Green | User-facing web UI |
52+
| smartem-aria-connector | Purple | ARIA/FandanGO integration |
53+
| smartem-devtools | Pink (dark) | Developer tooling |
54+
| smartem-devtools:webui | Pink (mid) | Developer dashboard |
55+
| smartem-devtools:claude | Pink (light) | Claude Code configuration |
56+
| smartem-devtools:e2e-test | Pink (lightest) | E2E testing infrastructure |
57+
58+
## Usage
59+
60+
### Check Label Conformity
61+
62+
To check if all repositories have the correct labels without making changes:
63+
64+
```bash
65+
npm run labels:check
66+
```
67+
68+
Or directly:
69+
70+
```bash
71+
npx tsx tools/github/sync-labels.ts --check
72+
```
73+
74+
This will:
75+
1. Fetch existing labels from each repository
76+
2. Compare against the defined labels in `core/github-tags-config.ts`
77+
3. Report any discrepancies (missing, extra, or outdated labels)
78+
4. Exit with code 1 if any repository is non-conforming
79+
80+
### Sync Labels
81+
82+
To synchronise labels across all repositories:
83+
84+
```bash
85+
npm run labels:sync
86+
```
87+
88+
Or directly:
89+
90+
```bash
91+
npx tsx tools/github/sync-labels.ts --sync
92+
```
93+
94+
This will:
95+
1. Delete labels not in the definition (extra labels)
96+
2. Create labels that are missing
97+
3. Update labels where description or colour has changed
98+
99+
### Target Specific Repositories
100+
101+
To sync only specific repositories:
102+
103+
```bash
104+
npx tsx tools/github/sync-labels.ts --sync --repo smartem-decisions
105+
npx tsx tools/github/sync-labels.ts --sync --repo smartem-frontend --repo smartem-devtools
106+
```
107+
108+
### Verbose Output
109+
110+
For detailed output including conforming labels:
111+
112+
```bash
113+
npx tsx tools/github/sync-labels.ts --check --verbose
114+
```
115+
116+
## CI/CD Integration
117+
118+
The `gitflow.yml` workflow automates label management:
119+
120+
- **On push to main**: Runs `--check` mode when `core/github-tags-config.ts` or `tools/github/**` changes
121+
- **Manual dispatch**: Can trigger `--sync` mode via GitHub Actions UI
122+
123+
### Running Sync via CI/CD
124+
125+
1. Go to Actions tab in smartem-devtools repository
126+
2. Select "Gitflow" workflow
127+
3. Click "Run workflow"
128+
4. Select `sync` mode
129+
5. Click "Run workflow"
130+
131+
## Modifying Labels
132+
133+
To add, remove, or modify labels:
134+
135+
1. Edit `core/github-tags-config.ts`
136+
2. Run `npm run labels:check` to verify changes
137+
3. Run `npm run labels:sync` to apply changes
138+
4. Commit and push changes
139+
140+
The CI/CD workflow will verify conformity on push.
141+
142+
## Troubleshooting
143+
144+
### Authentication Errors
145+
146+
Ensure `gh` CLI is authenticated:
147+
148+
```bash
149+
gh auth status
150+
gh auth login # if not authenticated
151+
```
152+
153+
### Permission Denied
154+
155+
For sync operations, you need write access to all target repositories. The CI/CD workflow uses a PAT stored as `LABEL_SYNC_TOKEN` secret.
156+
157+
### Label Already Exists
158+
159+
If a label creation fails because it already exists, the script will continue. Run with `--verbose` to see details.

‎package.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
11
{
2-
"private": true
2+
"private": true,
3+
"scripts": {
4+
"labels:check": "npx tsx tools/github/sync-labels.ts --check",
5+
"labels:sync": "npx tsx tools/github/sync-labels.ts --sync"
6+
},
7+
"devDependencies": {
8+
"tsx": "^4.19.2"
9+
}
310
}

0 commit comments

Comments
 (0)