Skip to content

Commit ec58661

Browse files
hacker-cbhacker-cb
committed
Refactor Docker image tagging strategy for consistency and clarity
Tag improvements: - Add 'v' prefix to PlatformIO version for consistency (pio-v6.1.18) - Remove ambiguous ESP-Matter convenience tag (matter-vX.X.X) - Remove date tags from all images (keep SHA tags for tracking) Rationale: - Consistent version format across all images (all use 'v' prefix) - ESP-Matter users must use full tag (idf-v5.4.1-matter-v1.4.2) for clarity - Date tags don't indicate version and clutter registry - SHA tags provide precise commit tracking for debugging Final tag structure: - ESP-IDF: latest, stable, idf-v5.4.1, sha-XXXXXXX - PlatformIO: latest, stable, pio-v6.1.18, sha-XXXXXXX - ESP-Matter: latest, stable, idf-v5.4.1-matter-v1.4.2, sha-XXXXXXX Documentation: - Update workflow templates to remove date tag generation - Add Tag Strategy section explaining rationale - Update Push Behavior table
1 parent 4a8df34 commit ec58661

File tree

3 files changed

+13
-20
lines changed

3 files changed

+13
-20
lines changed

‎.cursor/rules/github-actions-standards.mdc‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -165,20 +165,17 @@ jobs:
165165
username: ${{ github.actor }}
166166
password: ${{ secrets.GITHUB_TOKEN }}
167167

168-
- name: 🏷️ Generate version and date tags
168+
- name: 🏷️ Generate SHA tag
169169
id: tags
170170
run: |
171171
SHA_SHORT=$(echo "${{ github.sha }}" | cut -c1-7)
172-
DATE_TAG=$(date +%Y.%m.%d)
173172
echo "sha_short=${SHA_SHORT}" >> $GITHUB_OUTPUT
174-
echo "date_tag=${DATE_TAG}" >> $GITHUB_OUTPUT
175173

176174
- name: 🎯 Create multi-arch manifest
177175
run: |
178176
docker buildx imagetools create -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:latest \
179177
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:stable \
180178
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:<prefix>-${{ matrix.version }} \
181-
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:${{ steps.tags.outputs.date_tag }} \
182179
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:sha-${{ steps.tags.outputs.sha_short }} \
183180
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:<prefix>-${{ matrix.version }}-linux-amd64 \
184181
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.<IMAGE_NAME> }}:<prefix>-${{ matrix.version }}-linux-arm64
@@ -250,7 +247,7 @@ jobs:
250247

251248
| Branch/Event | Build | Push to GHCR | Tags Generated |
252249
|--------------|-------|--------------|----------------|
253-
| Main repo master push | Yes | Yes | `latest`, `stable`, `VERSION`, `sha-SHA`, `date` |
250+
| Main repo master push | Yes | Yes | `latest`, `stable`, `VERSION`, `sha-SHA` |
254251
| Main repo dev push | Yes | No | None |
255252
| Main repo PR | Yes | No | None |
256253
| Main repo workflow_dispatch | Yes | Only on master | Same as master if on master |
@@ -264,6 +261,12 @@ jobs:
264261
- Forks can test builds manually, but automatic builds are disabled
265262
- Secure: Only main repo on master can push to GHCR
266263

264+
**Tag Strategy:**
265+
- `latest` / `stable` - Floating tags for convenience
266+
- `<prefix>-v<version>` - Main version tag (e.g., `idf-v5.4.1`, `pio-v6.1.18`)
267+
- `sha-<commit>` - Git commit tracking for debugging/rollback
268+
- **No date tags** - Version tags are semantic and clear; SHA tags provide precise tracking
269+
267270
## Workflow Testing
268271

269272
### Local Testing with act

‎.github/workflows/esp-idf.yml‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -96,20 +96,17 @@ jobs:
9696
username: ${{ github.actor }}
9797
password: ${{ secrets.GITHUB_TOKEN }}
9898

99-
- name: 🏷️ Generate version and date tags
99+
- name: 🏷️ Generate SHA tag
100100
id: tags
101101
run: |
102102
SHA_SHORT=$(echo "${{ github.sha }}" | cut -c1-7)
103-
DATE_TAG=$(date +%Y.%m.%d)
104103
echo "sha_short=${SHA_SHORT}" >> $GITHUB_OUTPUT
105-
echo "date_tag=${DATE_TAG}" >> $GITHUB_OUTPUT
106104
107105
- name: 🎯 Create multi-arch manifest
108106
run: |
109107
docker buildx imagetools create -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:latest \
110108
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:stable \
111109
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }} \
112-
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:${{ steps.tags.outputs.date_tag }} \
113110
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:sha-${{ steps.tags.outputs.sha_short }} \
114111
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }}-linux-amd64 \
115112
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_IDF_IMAGE_NAME }}:idf-${{ matrix.idf_base_tag }}-linux-arm64
@@ -185,21 +182,17 @@ jobs:
185182
username: ${{ github.actor }}
186183
password: ${{ secrets.GITHUB_TOKEN }}
187184

188-
- name: 🏷️ Generate version and date tags
185+
- name: 🏷️ Generate SHA tag
189186
id: tags
190187
run: |
191188
SHA_SHORT=$(echo "${{ github.sha }}" | cut -c1-7)
192-
DATE_TAG=$(date +%Y.%m.%d)
193189
echo "sha_short=${SHA_SHORT}" >> $GITHUB_OUTPUT
194-
echo "date_tag=${DATE_TAG}" >> $GITHUB_OUTPUT
195190
196191
- name: 🎯 Create multi-arch manifest for ESP-Matter
197192
run: |
198193
docker buildx imagetools create -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:latest \
199194
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:stable \
200195
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }} \
201-
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:matter-${{ matrix.esp_matter_version }} \
202-
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:${{ steps.tags.outputs.date_tag }} \
203196
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:sha-${{ steps.tags.outputs.sha_short }} \
204197
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }}-linux-amd64 \
205198
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.ESP_MATTER_IMAGE_NAME }}:idf-${{ matrix.jethome_idf_base_tag }}-matter-${{ matrix.esp_matter_version }}-linux-arm64

‎.github/workflows/platformio.yml‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jobs:
3636
fail-fast: false
3737
matrix:
3838
platform: [linux/amd64, linux/arm64]
39-
pio_version: ['6.1.18']
39+
pio_version: ['v6.1.18']
4040
steps:
4141
- name: 📥 Checkout repository
4242
uses: actions/checkout@v4
@@ -83,7 +83,7 @@ jobs:
8383
strategy:
8484
fail-fast: false
8585
matrix:
86-
pio_version: ['6.1.18']
86+
pio_version: ['v6.1.18']
8787
steps:
8888
- name: 🔐 Log in to GitHub Container Registry
8989
uses: docker/login-action@v3
@@ -92,20 +92,17 @@ jobs:
9292
username: ${{ github.actor }}
9393
password: ${{ secrets.GITHUB_TOKEN }}
9494

95-
- name: 🏷️ Generate version and date tags
95+
- name: 🏷️ Generate SHA tag
9696
id: tags
9797
run: |
9898
SHA_SHORT=$(echo "${{ github.sha }}" | cut -c1-7)
99-
DATE_TAG=$(date +%Y.%m.%d)
10099
echo "sha_short=${SHA_SHORT}" >> $GITHUB_OUTPUT
101-
echo "date_tag=${DATE_TAG}" >> $GITHUB_OUTPUT
102100
103101
- name: 🎯 Create multi-arch manifest
104102
run: |
105103
docker buildx imagetools create -t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:latest \
106104
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:stable \
107105
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:pio-${{ matrix.pio_version }} \
108-
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:${{ steps.tags.outputs.date_tag }} \
109106
-t ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:sha-${{ steps.tags.outputs.sha_short }} \
110107
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:pio-${{ matrix.pio_version }}-linux-amd64 \
111108
${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.PLATFORMIO_IMAGE_NAME }}:pio-${{ matrix.pio_version }}-linux-arm64

0 commit comments

Comments
 (0)