Skip to content

Commit 3175825

Browse files
author
CI/CD Tester
committed
Update blog post: Rename tool and add AI workflow details
- Renamed tool from 'do-gh-sub-issues' to 'gh-sub-issues' - Added information about AI workflow and temporary workaround - Updated installation and customization instructions - Marked post as not a draft - Added hint about work in progress - Expanded script functionality details - Updated CI validation and workflow visualization sections - Improved overall content and structure
1 parent 6515551 commit 3175825

File tree

1 file changed

+49
-19
lines changed

1 file changed

+49
-19
lines changed

content/en/blog/version-controlling-github-issue-workflows-a-practical-approach.md

Lines changed: 49 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Version-Controlling GitHub Issue Workflows: A Practical Approach"
33
slug: version-controlling-github-issue-workflows-a-practical-approach
4-
description: "GitHub issues lack inherent structure. I built do-gh-sub-issues to bring hierarchy and better workflow control across multiple projects."
4+
description: "GitHub issues lack inherent structure. I built gh-sub-issues to bring hierarchy and better workflow control across multiple projects."
55
date: 2025-07-24
66
tags:
77
- GitHub
@@ -11,12 +11,13 @@ categories:
1111
- Software Development
1212
thumbnail:
1313
url: /img/blog/github-issues-overview.png
14-
draft: true
14+
draft: false
1515
---
16-
1716
## Building GitHub Issue Hierarchies: A Practical Approach
1817

19-
After struggling with GitHub's flat issue structure across multiple projects, I created a solution that brings hierarchical organization to issue tracking. Here's how I built do-gh-sub-issues as a simple yet powerful workflow tool.
18+
This repository serves as a template for use in my AI workflow. Additionally, it can be used manually without any LLM API provider. This serves as a temporary workaround until the GitHub CLI or GitHub MCP includes a proper workflow.
19+
20+
Hint: This is a work in progress, with updates applied to my workflow.
2021

2122
## The Core Problem
2223

@@ -34,18 +35,49 @@ This led to several incidents where completed features had unresolved dependenci
3435

3536
I chose Bash scripting for the initial implementation because:
3637

37-
**Universal Availability**: Every Unix-like system has a shell interpreter
38-
**Minimal Dependencies**: No package managers or runtime environments needed
39-
**Rapid Prototyping**: Immediate feedback during development
40-
**Educational Value**: Clear, readable code for learning purposes
41-
The script handles:
38+
**Universal Availability**: Every Unix-like system has a shell interpreter
39+
**Minimal Dependencies**: No package managers or runtime environments needed
40+
**Rapid Prototyping**: Immediate feedback during development
41+
**Educational Value**: Clear, readable code for learning purposes
42+
43+
The script handles these core functionalities through the GitHub CLI:
44+
45+
1. **Configuration Parsing**
46+
Reads `.github/issue-workflow.yml` to understand:
47+
- Parent/child issue prefixes (e.g., `Epic:`/`Task:`)
48+
- Status mapping rules (blocking vs non-blocking relationships)
49+
- Validation requirements
50+
51+
2. **Hierarchy Validation**
52+
For each issue:
53+
- Verifies required child issues exist
54+
- Checks parent/child status consistency
55+
- Validates cross-repository references
56+
57+
3. **Status Synchronization**
58+
Automatically cascades status changes:
59+
60+
```bash
61+
# Example: When parent status changes
62+
if [ "$parent_status" == "In Progress" ]; then
63+
gh issue edit $child_issue --add-label "Active"
64+
fi
65+
```
66+
67+
4. **CI/CD Integration**
68+
Runs validation during GitHub Actions workflows:
69+
- Blocks PRs with invalid issue dependencies
70+
- Generates visual issue graphs via Mermaid
71+
72+
5. **Audit Logging**
73+
Maintains timestamped records of:
74+
- Workflow configuration changes
75+
- Issue relationship modifications
76+
- Status transition histories
4277

43-
```bash
4478
- Issue relationship validation
4579
- Status cascade logic
4680
- Cross-reference checking
47-
- CI/CD integration
48-
```
4981

5082
## Technical Implementation
5183

@@ -75,7 +107,7 @@ workflows:
75107
status_cascade: true
76108
```
77109
78-
### CI Validation
110+
## CI Validation
79111
80112
The GitHub Action enforces these rules on every PR:
81113
@@ -102,7 +134,7 @@ Key validation features:
102134
- Verifies correct issue type prefixes
103135
- Generates visual dependency graphs
104136
105-
### Workflow Visualization
137+
## Workflow Visualization
106138
107139
```mermaid
108140
graph TD
@@ -128,13 +160,13 @@ Through regular use, I've observed:
128160
### Installation
129161

130162
```bash
131-
gh repo clone d-oit/do-gh-sub-issues
132-
cp -r do-gh-sub-issues/.github your-project/
163+
gh repo clone https://github.com/d-oit/gh-sub-issues
164+
cp -r gh-sub-issues/.github your-project/
133165
```
134166

135167
### Customization
136168

137-
Modify `issue-workflow.yml` using the [configuration reference](https://github.com/d-oit/do-gh-sub-issues/wiki/Configuration-Guide)
169+
Modify `issue-workflow.yml` using the [configuration documentation](https://github.com/d-oit/gh-sub-issues#configuration) in the README
138170

139171
### Integration
140172

@@ -162,8 +194,6 @@ For new adopters, I recommend:
162194
3. Use the `--dry-run` flag during initial setup
163195
4. Review validation reports before enabling strict mode
164196

165-
The template includes [example configurations](https://github.com/d-oit/do-gh-sub-issues/tree/main/examples) for different project scales.
166-
167197
## Future Considerations
168198

169199
While Bash works well for the reference implementation, production systems might benefit from:

0 commit comments

Comments
 (0)