gem-ci 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.markdownlint.yml +39 -0
- data/.rspec +3 -0
- data/.rubocop.yml +8 -0
- data/CHANGELOG.md +61 -0
- data/LICENSE.txt +21 -0
- data/README.md +183 -0
- data/Rakefile +12 -0
- data/docs/MANUAL_WORKFLOW_TESTING.md +190 -0
- data/docs/SECRETS_SETUP_GUIDE.md +292 -0
- data/docs/diagrams/ci-workflow-overview.md +170 -0
- data/lib/gem_ci/version.rb +5 -0
- data/lib/gem_ci.rb +8 -0
- data/sig/gem/ci.rbs +6 -0
- metadata +62 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: d60a8e5881c096feb9244447da37d659b2780518c521dec4363a1cb0b094bb16
|
|
4
|
+
data.tar.gz: a4185a27c3d715cd66ca8c0f9bb0a6ec40e3bf5039496adf9ab9340e6bb09fbb
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 29196b3877391b1de2c18111886ab2936a197941a7b9e59cf303884b6f355b9b24b6b66d436bcd66e699f838533dd8ff0c75c194c242897202eff9009ed3fb76
|
|
7
|
+
data.tar.gz: ebff56acc918dbf3dc4908fa71497f3ea982098f09e339515687bcb2d607ed3956f3670305408ed82f2db69627728a5c3a734d042d93c4e4d47776b4cb5bae5f
|
data/.markdownlint.yml
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Markdownlint configuration for gem-ci
|
|
2
|
+
# Relaxed rules for better developer experience
|
|
3
|
+
|
|
4
|
+
# Line length
|
|
5
|
+
MD013:
|
|
6
|
+
line_length: 120
|
|
7
|
+
code_blocks: false
|
|
8
|
+
tables: false
|
|
9
|
+
headings: false
|
|
10
|
+
|
|
11
|
+
# Allow emphasis as headings (useful for styled documentation)
|
|
12
|
+
MD036: false
|
|
13
|
+
|
|
14
|
+
# Relax heading spacing requirements
|
|
15
|
+
MD022: false
|
|
16
|
+
|
|
17
|
+
# Allow trailing punctuation in headings
|
|
18
|
+
MD026: false
|
|
19
|
+
|
|
20
|
+
# Allow duplicate headings (common in multi-section docs)
|
|
21
|
+
MD024: false
|
|
22
|
+
|
|
23
|
+
# Allow HTML in markdown (useful for badges and formatting)
|
|
24
|
+
MD033: false
|
|
25
|
+
|
|
26
|
+
# Allow bare URLs (auto-linking is fine)
|
|
27
|
+
MD034: false
|
|
28
|
+
|
|
29
|
+
# Relax list spacing requirements
|
|
30
|
+
MD032: false
|
|
31
|
+
|
|
32
|
+
# Allow files without trailing newlines
|
|
33
|
+
MD047: false
|
|
34
|
+
|
|
35
|
+
# Relax fenced code block spacing
|
|
36
|
+
MD031: false
|
|
37
|
+
|
|
38
|
+
# Allow trailing spaces (sometimes needed for line breaks)
|
|
39
|
+
MD009: false
|
data/.rspec
ADDED
data/.rubocop.yml
ADDED
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.2.1](https://github.com/patrick204nqh/gem-ci/compare/gem-ci/v0.2.0...gem-ci/v0.2.1) (2025-07-26)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ๐ Bug Fixes
|
|
7
|
+
|
|
8
|
+
* Add missing checkout step in stale management job ([679a603](https://github.com/patrick204nqh/gem-ci/commit/679a60377930993c42745f6cc0c0b7f24781961c))
|
|
9
|
+
* Update gemspec metadata to include homepage URI and correct documentation URI ([02dfb2b](https://github.com/patrick204nqh/gem-ci/commit/02dfb2ba4c5c60a56123a4e00bbd56beef5e1b1e))
|
|
10
|
+
|
|
11
|
+
## [0.2.0](https://github.com/patrick204nqh/gem-ci/compare/gem-ci-v0.1.1...gem-ci/v0.2.0) (2025-07-26)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
### ๐ Features
|
|
15
|
+
|
|
16
|
+
* Add composite actions for performance monitoring, command retry, test execution, and environment setup ([a4ffac6](https://github.com/patrick204nqh/gem-ci/commit/a4ffac66b796e7a22ee857d20fc4aed6d4c6717a))
|
|
17
|
+
* Add Dependabot configuration for automated dependency updates ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
18
|
+
* Add release management configuration and update gem structure ([bd8ae0c](https://github.com/patrick204nqh/gem-ci/commit/bd8ae0c5774f7be38211b8aa14423d87ae72edbf))
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### ๐ Bug Fixes
|
|
22
|
+
|
|
23
|
+
* Correct description formatting for sponsored label in labels.yml ([a013d1c](https://github.com/patrick204nqh/gem-ci/commit/a013d1c1a4a6462eb53b13bc783095858ac9ad6f))
|
|
24
|
+
* Improve command execution readability in CI jobs ([c54b578](https://github.com/patrick204nqh/gem-ci/commit/c54b578385c3eabe2c1ee54c9c4ad731daa4ff09))
|
|
25
|
+
* Improve description formatting in gemspec for better readability ([447313f](https://github.com/patrick204nqh/gem-ci/commit/447313f12a96970181f5472a2b575ff2a6349b81))
|
|
26
|
+
* Simplify command execution in CI jobs for better readability ([aa9a8d2](https://github.com/patrick204nqh/gem-ci/commit/aa9a8d2135852ff7639fa1cbc46667ea3d90949e))
|
|
27
|
+
* Update sponsored label description and adjust workflow triggers for label synchronization ([533ef4a](https://github.com/patrick204nqh/gem-ci/commit/533ef4aba474b5262596e1c34ad57c200987f1bd))
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
### ๐ Documentation
|
|
31
|
+
|
|
32
|
+
* Add README for validation workflows and their purposes ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
33
|
+
* Create GitHub App setup guide for branded automation ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
34
|
+
* Create repository secrets setup guide for automation workflows ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
35
|
+
* Revise main README to enhance clarity and detail on automation features ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
### โป๏ธ Refactoring
|
|
39
|
+
|
|
40
|
+
* **ci-cd:** Remove legacy Ruby workflow and add validation workflows for GitHub App, labels synchronization, repository rulesets, and Slack integration. Update Gemfile with new dependencies for testing and coverage reporting. Enhance spec helper for coverage metrics and clean up existing tests. ([6365ae2](https://github.com/patrick204nqh/gem-ci/commit/6365ae2ef85b92673bd75399ac2adf0d65e82aff))
|
|
41
|
+
* Rename community management workflow for clarity ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
42
|
+
* Rename ecosystem integration workflow for clarity ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
43
|
+
* Rename monitoring workflow for clarity ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
44
|
+
* Rename quality workflow for clarity ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
45
|
+
* Rename release management workflow for clarity ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
46
|
+
* Rename security workflow for clarity ([14e2b9b](https://github.com/patrick204nqh/gem-ci/commit/14e2b9b0b09bc4fc308ecb9eb594cdcc41650aaf))
|
|
47
|
+
* Replace GitHub App token action with local implementation for consistency across workflows ([715ba16](https://github.com/patrick204nqh/gem-ci/commit/715ba1642dece92a85534b671c85bba362976766))
|
|
48
|
+
* Replace performance-monitor action with inline command execution in CI jobs ([d8d9ff6](https://github.com/patrick204nqh/gem-ci/commit/d8d9ff6d8b609eb99d57e4a5cf337a08612382f3))
|
|
49
|
+
* Simplify CI workflows and enhance monitoring with basic health checks and summaries ([ad0c84a](https://github.com/patrick204nqh/gem-ci/commit/ad0c84ae798c8474b53b2be13d476fc90f3fbb7c))
|
|
50
|
+
* Standardize labeler.yml structure for file change types ([b34df93](https://github.com/patrick204nqh/gem-ci/commit/b34df9383345ac7c76ff4c3586fc5bec83933956))
|
|
51
|
+
* Standardize workflow names and update branch references to main and master ([017b4cf](https://github.com/patrick204nqh/gem-ci/commit/017b4cf1b284d62bdb676728df0cc97912dd9a43))
|
|
52
|
+
* Update CI/CD workflows to use default branch variable and adjust README for Ruby versions ([c0abddc](https://github.com/patrick204nqh/gem-ci/commit/c0abddcb159ef12a7c2e401864e46a3cb828771f))
|
|
53
|
+
* Update GitHub Actions workflows for improved error handling and metrics output ([0d07488](https://github.com/patrick204nqh/gem-ci/commit/0d07488e7f1d14f4fcc6b944e0abc18205fb2ea9))
|
|
54
|
+
* Update labeler configuration and enhance CI workflows with repository checkout steps ([d13d065](https://github.com/patrick204nqh/gem-ci/commit/d13d065eb48d106e0791811421966a9c07cabae5))
|
|
55
|
+
* Update security and ecosystem workflows for improved pull request handling and reduce matrix size ([caacb33](https://github.com/patrick204nqh/gem-ci/commit/caacb3354718edd7a76b0b247b265beea06e7eaa))
|
|
56
|
+
* Update workflow names and improve branch protection rules; enhance label configurations ([79c58d2](https://github.com/patrick204nqh/gem-ci/commit/79c58d258fc83aa690843c166a68fac1e0a97e5c))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
### ๐ค CI/CD
|
|
60
|
+
|
|
61
|
+
* **workflows:** Refactor GitHub Actions and Documentation ([bf9bca1](https://github.com/patrick204nqh/gem-ci/commit/bf9bca1d0dfe6e3ac7c508231a0e8afea4a9d633))
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 TODO: Write your name
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# ๐ค Ruby Gem Automation Template
|
|
2
|
+
|
|
3
|
+
> **The ultimate automation template for Ruby gem projects** - Battle-tested workflows for seamless development, security, and releases.
|
|
4
|
+
|
|
5
|
+
## โจ What This Provides
|
|
6
|
+
|
|
7
|
+
This repository serves as the **perfect template** for Ruby gem automation. It includes 8 comprehensive workflows that handle every aspect of your gem's lifecycle:
|
|
8
|
+
|
|
9
|
+
- ๐ **Automated CI/CD** across Ruby versions and platforms
|
|
10
|
+
- ๐ **Security scanning** and vulnerability detection
|
|
11
|
+
- ๐ **Code quality** enforcement and coverage reporting
|
|
12
|
+
- ๐ **Automated releases** with semantic versioning
|
|
13
|
+
- ๐ฅ **Community management** and contributor engagement
|
|
14
|
+
- ๐ **Performance monitoring** and health checks
|
|
15
|
+
|
|
16
|
+
## ๐ Quick Start
|
|
17
|
+
|
|
18
|
+
1. **Use this template** to create your new repository
|
|
19
|
+
2. **Set up secrets** following the [Secrets Setup Guide](docs/SECRETS_SETUP_GUIDE.md)
|
|
20
|
+
3. **Configure labels** by running the label sync workflow
|
|
21
|
+
4. **Import rulesets** from `.github/config/rulesets/`
|
|
22
|
+
5. **Start developing** - automation handles the rest!
|
|
23
|
+
|
|
24
|
+
## ๐ Complete Automation Tasks
|
|
25
|
+
|
|
26
|
+
| **Category** | **Task** | **Workflow** | **Action Used** | **Configuration** |
|
|
27
|
+
| ------------------- | ----------------------- | ---------------------------------------- | ----------------------------------------- | --------------------------- |
|
|
28
|
+
| **๐ CI/CD** | Multi-Ruby testing | `02-ci.yml` | `ruby/setup-ruby@v1` | Ruby 3.2, 3.3, 3.4 |
|
|
29
|
+
| | Cross-platform testing | `02-ci.yml` | `actions/checkout@v4` | Ubuntu, macOS |
|
|
30
|
+
| | Dependency caching | `02-ci.yml` | `actions/cache@v3` | Bundler cache |
|
|
31
|
+
| | Test execution | `02-ci.yml` | Custom scripts | RSpec, Minitest |
|
|
32
|
+
| | Coverage reporting | `04-quality.yml` | `simplecov` gem | 90% threshold |
|
|
33
|
+
| **๐ Security** | CodeQL analysis | `03-security.yml` | `github/codeql-action@v3` | `.github/config/codeql.yml` |
|
|
34
|
+
| | Dependency scanning | `03-security.yml` | `actions/dependency-review-action@v4` | Vulnerability detection |
|
|
35
|
+
| | Secret scanning | `03-security.yml` | `trufflesecurity/trufflehog@main` | Git history scan |
|
|
36
|
+
| | Container scanning | `03-security.yml` | `aquasecurity/trivy-action@master` | Dockerfile security |
|
|
37
|
+
| | Bundle audit | `03-security.yml` | `bundler-audit` gem | Gem vulnerabilities |
|
|
38
|
+
| **๐ Quality** | Code linting | `04-quality.yml` | `rubocop/rubocop-github-action@v0.1.0` | RuboCop standards |
|
|
39
|
+
| | Documentation | `04-quality.yml` | `yard` gem | API documentation |
|
|
40
|
+
| | Markdown linting | `04-quality.yml` | `DavidAnson/markdownlint-cli2-action@v16` | Markdown standards |
|
|
41
|
+
| | Super linting | `04-quality.yml` | `super-linter/super-linter@v5` | Multi-language linting |
|
|
42
|
+
| **๐ท๏ธ Labels** | Label sync | `01-intake.yml` | `crazy-max/ghaction-github-labeler@v5` | `.github/labels.yml` |
|
|
43
|
+
| | Auto-labeling | `01-intake.yml` | `actions/labeler@v5` | `.github/labeler.yml` |
|
|
44
|
+
| | Size labeling | `01-intake.yml` | Custom script | PR size detection |
|
|
45
|
+
| **๐ฅ Community** | Welcome messages | `01-intake.yml` | `actions/first-interaction@v1` | First-time contributors |
|
|
46
|
+
| | Stale management | `05-community.yml` | `actions/stale@v9` | 60-day stale policy |
|
|
47
|
+
| | Contributor recognition | `05-community.yml` | Custom script | Achievement badges |
|
|
48
|
+
| | Health monitoring | `08-monitoring.yml` | Custom script | Community metrics |
|
|
49
|
+
| **๐ Release** | Semantic versioning | `06-release.yml` | Custom script | Version bumping |
|
|
50
|
+
| | Changelog generation | `06-release.yml` | Custom script | Auto-generated changelogs |
|
|
51
|
+
| | RubyGems publishing | `06-release.yml` | `ruby/setup-ruby@v1` | Automated gem push |
|
|
52
|
+
| | GitHub releases | `06-release.yml` | `actions/create-release@v1` | Release notes |
|
|
53
|
+
| | Release notifications | `06-release.yml` | `slackapi/slack-github-action@v1.27.0` | Slack integration |
|
|
54
|
+
| **๐ฆ Dependencies** | Dependency updates | Dependabot | GitHub native | `.github/dependabot.yml` |
|
|
55
|
+
| | Security updates | Dependabot | GitHub native | Auto-merge safe updates |
|
|
56
|
+
| | Version grouping | Dependabot | GitHub native | Development/testing groups |
|
|
57
|
+
| **๐ก๏ธ Protection** | Branch protection | Rulesets | GitHub native | `.github/config/rulesets/` |
|
|
58
|
+
| | Tag protection | Rulesets | GitHub native | Release tag protection |
|
|
59
|
+
| | Push restrictions | Rulesets | GitHub native | Development branch rules |
|
|
60
|
+
| **๐ข Notifications** | Slack integration | Multiple | `slackapi/slack-github-action@v1.27.0` | `SLACK_BOT_TOKEN` |
|
|
61
|
+
| | Email notifications | GitHub native | Repository settings | Configurable recipients |
|
|
62
|
+
| **๐งช Validation** | GitHub App setup | `tests/validate-github-app.yml` | `actions/create-github-app-token@v1` | Token validation |
|
|
63
|
+
| | Slack integration | `tests/validate-slack-integration.yml` | `slackapi/slack-github-action@v1.27.0` | Message testing |
|
|
64
|
+
| | Label sync | `tests/validate-labels-sync.yml` | `crazy-max/ghaction-github-labeler@v5` | Configuration validation |
|
|
65
|
+
| | Repository rulesets | `tests/validate-repository-rulesets.yml` | Custom scripts | Ruleset validation |
|
|
66
|
+
|
|
67
|
+
## ๐ Required Setup
|
|
68
|
+
|
|
69
|
+
### **Secrets** (Required)
|
|
70
|
+
| Secret | Purpose | Required |
|
|
71
|
+
|--------|---------|----------|
|
|
72
|
+
| `APP_ID` | GitHub App ID for branded automation | โ
Yes |
|
|
73
|
+
| `PRIVATE_KEY` | GitHub App private key | โ
Yes |
|
|
74
|
+
| `SLACK_BOT_TOKEN` | Slack bot token for notifications | โ Optional |
|
|
75
|
+
| `SLACK_CHANNEL_ID` | Slack channel ID | โ Optional |
|
|
76
|
+
| `RUBYGEMS_API_KEY` | RubyGems publishing key | โ Optional |
|
|
77
|
+
|
|
78
|
+
### **Configuration Files**
|
|
79
|
+
| File | Purpose | Required |
|
|
80
|
+
|------|---------|----------|
|
|
81
|
+
| `.github/labels.yml` | Label definitions and colors | โ
Yes |
|
|
82
|
+
| `.github/labeler.yml` | Auto-labeling rules | โ
Yes |
|
|
83
|
+
| `.github/dependabot.yml` | Dependency update configuration | โ
Yes |
|
|
84
|
+
| `.github/CODEOWNERS` | Code ownership and review assignments | โ
Yes |
|
|
85
|
+
| `.github/config/codeql.yml` | CodeQL analysis configuration | โ
Yes |
|
|
86
|
+
| `.github/config/rulesets/*.json` | Repository protection rules | โ Optional |
|
|
87
|
+
|
|
88
|
+
## ๐ Ruby Gem Repository Lifecycle
|
|
89
|
+
|
|
90
|
+
This template provides a complete automation solution that follows the natural lifecycle of a Ruby gem repository:
|
|
91
|
+
|
|
92
|
+
### ๐ **Phase 1: Repository Setup** (One-time)
|
|
93
|
+
- **๐ท๏ธ Label Management**: Sync professional labels with `01-intake.yml`
|
|
94
|
+
- **๐ Secret Configuration**: Setup GitHub App authentication and integrations
|
|
95
|
+
- **๐ก๏ธ Branch Protection**: Configure repository rulesets and security policies
|
|
96
|
+
- **โ๏ธ Initial Configuration**: Dependabot, CodeQL, and workflow settings
|
|
97
|
+
|
|
98
|
+
### ๐ป **Phase 2: Development Cycle** (Daily)
|
|
99
|
+
- **๐งช Continuous Testing**: Multi-Ruby version testing with `02-ci.yml`
|
|
100
|
+
- **๐ Security Scanning**: Vulnerability detection with `03-security.yml`
|
|
101
|
+
- **๐ Code Quality**: RuboCop linting and documentation with `04-quality.yml`
|
|
102
|
+
- **๐ท๏ธ Auto-labeling**: Smart PR/issue labeling with `01-intake.yml`
|
|
103
|
+
- **๐ Contributor Welcome**: First-time contributor guidance with `01-intake.yml`
|
|
104
|
+
|
|
105
|
+
### ๐ฆ **Phase 3: Dependency Management** (Automated)
|
|
106
|
+
- **๐ค Dependabot Updates**: Weekly dependency update PRs
|
|
107
|
+
- **๐งช Update Testing**: Automated testing of dependency changes
|
|
108
|
+
- **โ
Safe Auto-merge**: Automatic merging of low-risk updates
|
|
109
|
+
|
|
110
|
+
### ๐ **Phase 4: Release Process** (On-demand)
|
|
111
|
+
- **๐๏ธ Gem Building**: Automated gem packaging with `06-release.yml`
|
|
112
|
+
- **๐ RubyGems Publishing**: Direct publishing to RubyGems registry
|
|
113
|
+
- **๐ Changelog Generation**: Automatic changelog and release notes
|
|
114
|
+
- **๐ข Release Notifications**: Slack and GitHub release announcements
|
|
115
|
+
|
|
116
|
+
### ๐ **Phase 5: Ongoing Maintenance** (Background)
|
|
117
|
+
- **๐งน Stale Management**: Automated stale issue cleanup with `05-community.yml`
|
|
118
|
+
- **๐ Ecosystem Monitoring**: Compatibility checks with `07-ecosystem.yml`
|
|
119
|
+
- **๐ Health Monitoring**: Performance tracking with `08-monitoring.yml`
|
|
120
|
+
- **๐ฅ Community Engagement**: Contributor recognition and community health
|
|
121
|
+
|
|
122
|
+
## ๐ Documentation
|
|
123
|
+
|
|
124
|
+
- **[๐ Lifecycle Diagram](docs/diagrams/ci-workflow-overview.md)** - Visual repository lifecycle and workflow mapping
|
|
125
|
+
- **[๐ Secrets Setup Guide](docs/SECRETS_SETUP_GUIDE.md)** - Complete secrets configuration
|
|
126
|
+
- **[๐งช Manual Testing Guide](docs/MANUAL_WORKFLOW_TESTING.md)** - How to test and trigger workflows manually
|
|
127
|
+
- **[๐ท๏ธ Labels Color Guide](docs/LABELS_COLOR_GUIDE.md)** - Label design and accessibility
|
|
128
|
+
- **[โ
Validation Workflows](.github/workflows/tests/README.md)** - Testing your setup
|
|
129
|
+
|
|
130
|
+
## ๐ฏ Key Features
|
|
131
|
+
|
|
132
|
+
### **๐ Multi-Ruby Testing**
|
|
133
|
+
- Tests across Ruby 3.2, 3.3 and 3.4
|
|
134
|
+
- Cross-platform support (Ubuntu, macOS)
|
|
135
|
+
- Parallel test execution for speed
|
|
136
|
+
|
|
137
|
+
### **๐ Comprehensive Security**
|
|
138
|
+
- CodeQL static analysis
|
|
139
|
+
- Dependency vulnerability scanning
|
|
140
|
+
- Secret detection in git history
|
|
141
|
+
- Container security scanning
|
|
142
|
+
- Automated security updates
|
|
143
|
+
|
|
144
|
+
### **๐ Quality Enforcement**
|
|
145
|
+
- RuboCop code style enforcement
|
|
146
|
+
- Test coverage reporting (90% threshold)
|
|
147
|
+
- Documentation coverage checking
|
|
148
|
+
- Markdown and YAML linting
|
|
149
|
+
|
|
150
|
+
### **๐ Automated Releases**
|
|
151
|
+
- Semantic version bumping
|
|
152
|
+
- Automated changelog generation
|
|
153
|
+
- RubyGems publishing
|
|
154
|
+
- GitHub release creation
|
|
155
|
+
- Slack release notifications
|
|
156
|
+
|
|
157
|
+
### **๐ฅ Community Management**
|
|
158
|
+
- Welcome messages for new contributors
|
|
159
|
+
- Stale issue/PR management
|
|
160
|
+
- Contributor achievement recognition
|
|
161
|
+
- Community health monitoring
|
|
162
|
+
|
|
163
|
+
### **๐ท๏ธ Smart Labeling**
|
|
164
|
+
- 33 professionally designed labels
|
|
165
|
+
- Automatic labeling based on file changes
|
|
166
|
+
- PR size detection and labeling
|
|
167
|
+
- Accessible color scheme (WCAG AA compliant)
|
|
168
|
+
|
|
169
|
+
## ๐ค Contributing
|
|
170
|
+
|
|
171
|
+
1. Fork this repository
|
|
172
|
+
2. Create a feature branch
|
|
173
|
+
3. Make your changes
|
|
174
|
+
4. Run validation workflows
|
|
175
|
+
5. Submit a pull request
|
|
176
|
+
|
|
177
|
+
## ๐ License
|
|
178
|
+
|
|
179
|
+
This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
**Note:** This template is designed for Ruby gem projects and may require adjustments for other languages or frameworks. It is battle-tested and ready to use, but always review and customize workflows to fit your specific needs.
|
data/Rakefile
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# ๐งช Manual Workflow Testing Guide
|
|
2
|
+
|
|
3
|
+
This guide explains how to manually test and trigger gem-ci workflows for validation and troubleshooting.
|
|
4
|
+
|
|
5
|
+
## ๐ Manual Workflow Triggers
|
|
6
|
+
|
|
7
|
+
### Main Workflows (01-08)
|
|
8
|
+
|
|
9
|
+
Most main workflows trigger automatically on events, but some can be triggered manually:
|
|
10
|
+
|
|
11
|
+
| Workflow | File | Manual Trigger | Purpose |
|
|
12
|
+
|----------|------|----------------|---------|
|
|
13
|
+
| 01 - Intake | `01-intake.yml` | โ
Yes | Sync labels and configurations |
|
|
14
|
+
| 02 - CI | `02-ci.yml` | โ Auto only | Push/PR testing |
|
|
15
|
+
| 03 - Security | `03-security.yml` | โ Auto only | Security scans |
|
|
16
|
+
| 04 - Quality | `04-quality.yml` | โ Auto only | Code quality checks |
|
|
17
|
+
| 05 - Community | `05-community.yml` | โ Auto only | Stale management |
|
|
18
|
+
| 06 - Release | `06-release.yml` | โ Auto only | Tag-based releases |
|
|
19
|
+
| 07 - Ecosystem | `07-ecosystem.yml` | โ Auto only | Ecosystem checks |
|
|
20
|
+
| 08 - Monitoring | `08-monitoring.yml` | โ Auto only | Scheduled monitoring |
|
|
21
|
+
|
|
22
|
+
### Test Workflows
|
|
23
|
+
|
|
24
|
+
All validation workflows support manual triggering:
|
|
25
|
+
|
|
26
|
+
| Validation Workflow | Purpose | Required Secrets |
|
|
27
|
+
|-------------------|---------|------------------|
|
|
28
|
+
| `validate-github-app.yml` | Test GitHub App setup | `APP_ID`, `PRIVATE_KEY` |
|
|
29
|
+
| `validate-slack-integration.yml` | Test Slack notifications | `APP_ID`, `PRIVATE_KEY`, `SLACK_BOT_TOKEN`, `SLACK_CHANNEL_ID` |
|
|
30
|
+
| `validate-labels-sync.yml` | Test label synchronization | `APP_ID`, `PRIVATE_KEY` |
|
|
31
|
+
| `validate-repository-rulesets.yml` | Test repository rulesets | `APP_ID`, `PRIVATE_KEY` |
|
|
32
|
+
|
|
33
|
+
## ๐ How to Manually Trigger Workflows
|
|
34
|
+
|
|
35
|
+
### Method 1: GitHub Web Interface
|
|
36
|
+
|
|
37
|
+
1. **Navigate to Actions Tab**
|
|
38
|
+
- Go to your repository on GitHub
|
|
39
|
+
- Click the **"Actions"** tab
|
|
40
|
+
|
|
41
|
+
2. **Select Workflow**
|
|
42
|
+
- Find the workflow you want to trigger
|
|
43
|
+
- Click on the workflow name
|
|
44
|
+
|
|
45
|
+
3. **Run Workflow**
|
|
46
|
+
- Click **"Run workflow"** button
|
|
47
|
+
- Select branch (usually `main`)
|
|
48
|
+
- Click **"Run workflow"** to confirm
|
|
49
|
+
|
|
50
|
+
### Method 2: GitHub CLI
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
# Install GitHub CLI if not already installed
|
|
54
|
+
# https://cli.github.com/
|
|
55
|
+
|
|
56
|
+
# Trigger a workflow manually
|
|
57
|
+
gh workflow run "workflow-name.yml"
|
|
58
|
+
|
|
59
|
+
# Examples:
|
|
60
|
+
gh workflow run "01-intake.yml"
|
|
61
|
+
gh workflow run "validate-github-app.yml"
|
|
62
|
+
|
|
63
|
+
# Check workflow status
|
|
64
|
+
gh run list --workflow="workflow-name.yml"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Method 3: REST API
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Trigger workflow via API
|
|
71
|
+
curl -X POST \
|
|
72
|
+
-H "Accept: application/vnd.github.v3+json" \
|
|
73
|
+
-H "Authorization: token YOUR_GITHUB_TOKEN" \
|
|
74
|
+
https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \
|
|
75
|
+
-d '{"ref":"main"}'
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## ๐ Testing Checklist
|
|
79
|
+
|
|
80
|
+
### Before Running Tests
|
|
81
|
+
|
|
82
|
+
- [ ] All required secrets are configured
|
|
83
|
+
- [ ] Repository has proper permissions
|
|
84
|
+
- [ ] Configuration files exist (`.github/labels.yml`, etc.)
|
|
85
|
+
- [ ] Branch protection rules are properly set
|
|
86
|
+
|
|
87
|
+
### GitHub App Validation
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
# Run GitHub App validation
|
|
91
|
+
gh workflow run "validate-github-app.yml"
|
|
92
|
+
|
|
93
|
+
# Expected results:
|
|
94
|
+
# โ
Token generation successful
|
|
95
|
+
# โ
API access working
|
|
96
|
+
# โ
Branded bot identity confirmed
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Slack Integration Testing
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Run Slack integration test
|
|
103
|
+
gh workflow run "validate-slack-integration.yml"
|
|
104
|
+
|
|
105
|
+
# Expected results:
|
|
106
|
+
# โ
Basic message sent to Slack
|
|
107
|
+
# โ
Rich message blocks working
|
|
108
|
+
# โ
Bot appears with correct identity
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Labels Synchronization
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# Run label sync validation
|
|
115
|
+
gh workflow run "validate-labels-sync.yml"
|
|
116
|
+
|
|
117
|
+
# Expected results:
|
|
118
|
+
# โ
Label configuration valid
|
|
119
|
+
# โ
All required labels present
|
|
120
|
+
# โ
Color scheme accessibility confirmed
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## ๐ Monitoring Workflow Results
|
|
124
|
+
|
|
125
|
+
### Check Workflow Status
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# List recent workflow runs
|
|
129
|
+
gh run list --limit 10
|
|
130
|
+
|
|
131
|
+
# Get details of specific run
|
|
132
|
+
gh run view RUN_ID
|
|
133
|
+
|
|
134
|
+
# Download workflow logs
|
|
135
|
+
gh run download RUN_ID
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Common Issues & Solutions
|
|
139
|
+
|
|
140
|
+
| Issue | Solution |
|
|
141
|
+
|-------|----------|
|
|
142
|
+
| **Token generation failed** | Verify `APP_ID` and `PRIVATE_KEY` secrets |
|
|
143
|
+
| **Slack message not sent** | Check `SLACK_BOT_TOKEN` and `SLACK_CHANNEL_ID` |
|
|
144
|
+
| **Label sync failed** | Validate `.github/labels.yml` syntax |
|
|
145
|
+
| **API rate limit exceeded** | Wait and retry, or use GitHub App token |
|
|
146
|
+
| **Permission denied** | Verify GitHub App permissions and installation |
|
|
147
|
+
|
|
148
|
+
## ๐ ๏ธ Troubleshooting
|
|
149
|
+
|
|
150
|
+
### Debug Mode
|
|
151
|
+
|
|
152
|
+
Enable debug logging by setting repository variables:
|
|
153
|
+
- `ACTIONS_STEP_DEBUG`: `true`
|
|
154
|
+
- `ACTIONS_RUNNER_DEBUG`: `true`
|
|
155
|
+
|
|
156
|
+
### Secrets Validation
|
|
157
|
+
|
|
158
|
+
Use the validation workflows to test each component:
|
|
159
|
+
|
|
160
|
+
1. **Start with GitHub App validation** - This tests the foundation
|
|
161
|
+
2. **Run Slack validation** - If notifications are needed
|
|
162
|
+
3. **Test label sync** - For repository organization
|
|
163
|
+
4. **Validate rulesets** - For branch protection
|
|
164
|
+
|
|
165
|
+
### Common Workflow Patterns
|
|
166
|
+
|
|
167
|
+
- **On Push**: Triggers CI, security, and quality workflows
|
|
168
|
+
- **On PR**: Triggers testing and validation workflows
|
|
169
|
+
- **On Release**: Triggers release and notification workflows
|
|
170
|
+
- **On Schedule**: Triggers monitoring and maintenance workflows
|
|
171
|
+
- **Manual**: Triggers setup and validation workflows
|
|
172
|
+
|
|
173
|
+
## ๐ Getting Help
|
|
174
|
+
|
|
175
|
+
If workflows fail after following this guide:
|
|
176
|
+
|
|
177
|
+
1. Check workflow logs in the Actions tab
|
|
178
|
+
2. Verify all required secrets are set
|
|
179
|
+
3. Review configuration files for syntax errors
|
|
180
|
+
4. Test individual components using validation workflows
|
|
181
|
+
5. Check GitHub App permissions and installation
|
|
182
|
+
|
|
183
|
+
## ๐ Regular Testing Schedule
|
|
184
|
+
|
|
185
|
+
Recommended testing schedule:
|
|
186
|
+
|
|
187
|
+
- **Weekly**: Run GitHub App validation
|
|
188
|
+
- **Monthly**: Test Slack integration (if used)
|
|
189
|
+
- **Before releases**: Run all validation workflows
|
|
190
|
+
- **After configuration changes**: Test affected workflows
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
# ๐ Secrets Setup Guide
|
|
2
|
+
*Complete guide for configuring all required secrets for gem-ci workflows*
|
|
3
|
+
|
|
4
|
+
## ๐ฏ Overview
|
|
5
|
+
|
|
6
|
+
This guide walks you through setting up all required secrets for gem-ci workflows, including GitHub App authentication, Slack integration, and RubyGems publishing.
|
|
7
|
+
|
|
8
|
+
## ๐ Required Secrets Overview
|
|
9
|
+
|
|
10
|
+
The gem-ci workflows require the following secrets:
|
|
11
|
+
|
|
12
|
+
| Secret | Purpose | Required | Setup Section |
|
|
13
|
+
|--------|---------|----------|---------------|
|
|
14
|
+
| `APP_ID` | GitHub App ID for branded automation | โ
Yes | Step 1-2 |
|
|
15
|
+
| `PRIVATE_KEY` | GitHub App private key | โ
Yes | Step 1-2 |
|
|
16
|
+
| `SLACK_BOT_TOKEN` | Slack bot token for notifications | โ Optional | Step 3 |
|
|
17
|
+
| `SLACK_CHANNEL_ID` | Slack channel ID | โ Optional | Step 3 |
|
|
18
|
+
| `RUBYGEMS_API_KEY` | RubyGems publishing key | โ Optional | Step 4 |
|
|
19
|
+
|
|
20
|
+
## ๐ Prerequisites
|
|
21
|
+
|
|
22
|
+
- GitHub repository with admin access
|
|
23
|
+
- GitHub account with developer settings access
|
|
24
|
+
- Basic understanding of GitHub secrets
|
|
25
|
+
|
|
26
|
+
## ๐ Step-by-Step Setup
|
|
27
|
+
|
|
28
|
+
### **Step 1: Create GitHub App**
|
|
29
|
+
|
|
30
|
+
1. **Navigate to GitHub Developer Settings**
|
|
31
|
+
- Go to [GitHub Developer Settings](https://github.com/settings/developers)
|
|
32
|
+
- Click **"New GitHub App"**
|
|
33
|
+
|
|
34
|
+
2. **Configure Basic App Settings**
|
|
35
|
+
```yaml
|
|
36
|
+
GitHub App name: gem-ci-automation
|
|
37
|
+
Description: Professional automation for Ruby gem projects
|
|
38
|
+
Homepage URL: https://github.com/YOUR_USERNAME/YOUR_REPO
|
|
39
|
+
Webhook URL: https://api.github.com/repos/YOUR_USERNAME/YOUR_REPO/dispatches
|
|
40
|
+
Webhook secret: (leave empty for now)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
3. **Set Repository Permissions**
|
|
44
|
+
```yaml
|
|
45
|
+
Repository permissions:
|
|
46
|
+
Actions: Read and write
|
|
47
|
+
Checks: Write
|
|
48
|
+
Contents: Write
|
|
49
|
+
Issues: Write
|
|
50
|
+
Metadata: Read
|
|
51
|
+
Pull requests: Write
|
|
52
|
+
Commit statuses: Write
|
|
53
|
+
|
|
54
|
+
Account permissions:
|
|
55
|
+
Email addresses: Read
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
4. **Configure App Settings**
|
|
59
|
+
- โ
**Webhook**: Active
|
|
60
|
+
- โ
**Where can this GitHub App be installed?**: Only on this account
|
|
61
|
+
- โ **Request user authorization (OAuth) during installation**: Unchecked
|
|
62
|
+
|
|
63
|
+
5. **Create the App**
|
|
64
|
+
- Click **"Create GitHub App"**
|
|
65
|
+
- Note down the **App ID** (you'll need this)
|
|
66
|
+
|
|
67
|
+
### **Step 2: Generate Private Key**
|
|
68
|
+
|
|
69
|
+
1. **In your newly created app settings:**
|
|
70
|
+
- Scroll to **"Private keys"** section
|
|
71
|
+
- Click **"Generate a private key"**
|
|
72
|
+
- Download the `.pem` file securely
|
|
73
|
+
|
|
74
|
+
2. **Convert PEM for GitHub Secrets:**
|
|
75
|
+
```bash
|
|
76
|
+
# The downloaded file content should look like:
|
|
77
|
+
-----BEGIN RSA PRIVATE KEY-----
|
|
78
|
+
[Your private key content]
|
|
79
|
+
-----END RSA PRIVATE KEY-----
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### **Step 3: Install App on Repository**
|
|
83
|
+
|
|
84
|
+
1. **Install the App:**
|
|
85
|
+
- In app settings, click **"Install App"** in left sidebar
|
|
86
|
+
- Click **"Install"** next to your account
|
|
87
|
+
- Select **"Only select repositories"**
|
|
88
|
+
- Choose your gem project repository
|
|
89
|
+
- Click **"Install"**
|
|
90
|
+
|
|
91
|
+
### **Step 4: Configure Repository Secrets**
|
|
92
|
+
|
|
93
|
+
1. **Navigate to Repository Settings:**
|
|
94
|
+
- Go to your repository
|
|
95
|
+
- Click **Settings** โ **Secrets and variables** โ **Actions**
|
|
96
|
+
|
|
97
|
+
2. **Add Required Secrets:**
|
|
98
|
+
|
|
99
|
+
**Secret 1: `APP_ID`**
|
|
100
|
+
```
|
|
101
|
+
Name: APP_ID
|
|
102
|
+
Value: [Your App ID from Step 1]
|
|
103
|
+
Example: 123456
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**Secret 2: `PRIVATE_KEY`**
|
|
107
|
+
```
|
|
108
|
+
Name: PRIVATE_KEY
|
|
109
|
+
Value: [Complete contents of your .pem file]
|
|
110
|
+
Example:
|
|
111
|
+
-----BEGIN RSA PRIVATE KEY-----
|
|
112
|
+
MIIEpAIBAAKCAQEA1234567890abcdef...
|
|
113
|
+
[Full private key content]
|
|
114
|
+
...xyz789
|
|
115
|
+
-----END RSA PRIVATE KEY-----
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### **Step 5: Customize App Appearance**
|
|
119
|
+
|
|
120
|
+
1. **Upload Custom Avatar:**
|
|
121
|
+
- In app settings, scroll to **"Display information"**
|
|
122
|
+
- Upload a custom logo (๐ + โ๏ธ design recommended)
|
|
123
|
+
- Add description: "Professional automation for Ruby gem projects"
|
|
124
|
+
|
|
125
|
+
2. **Set App Colors:**
|
|
126
|
+
- Choose brand colors that match your project
|
|
127
|
+
- Ensure good contrast for readability
|
|
128
|
+
|
|
129
|
+
## ๐งช Test Your Setup
|
|
130
|
+
|
|
131
|
+
### **Test 1: Validate GitHub App**
|
|
132
|
+
|
|
133
|
+
1. **Trigger the validation workflow** from `.github/workflows/tests/validate-github-app.yml`
|
|
134
|
+
2. **Check the activity log** - you should see your custom bot name
|
|
135
|
+
3. **Verify avatar** appears correctly in GitHub interface
|
|
136
|
+
|
|
137
|
+
### **Test 2: Validate Slack Integration** (Optional)
|
|
138
|
+
|
|
139
|
+
1. **Set up Slack bot** (see `.github/workflows/tests/README.md` for detailed instructions)
|
|
140
|
+
2. **Add Slack secrets** to repository settings
|
|
141
|
+
3. **Trigger the Slack validation workflow** from `.github/workflows/tests/validate-slack-integration.yml`
|
|
142
|
+
4. **Check your Slack channel** for test messages from your branded bot
|
|
143
|
+
|
|
144
|
+
> **๐ Note**: Test workflows are organized in `.github/workflows/tests/` to keep them separate from production workflows.
|
|
145
|
+
|
|
146
|
+
## ๐ Security Best Practices
|
|
147
|
+
|
|
148
|
+
### **Private Key Security**
|
|
149
|
+
- โ
**Never commit** the `.pem` file to version control
|
|
150
|
+
- โ
**Store securely** in GitHub repository secrets only
|
|
151
|
+
- โ
**Limit access** to repository admins only
|
|
152
|
+
- โ
**Rotate regularly** (recommended every 6 months)
|
|
153
|
+
|
|
154
|
+
### **App Permissions**
|
|
155
|
+
- โ
**Minimal permissions** - only what's needed
|
|
156
|
+
- โ
**Repository-specific** installation
|
|
157
|
+
- โ
**Regular audits** of app permissions
|
|
158
|
+
- โ
**Monitor usage** in app settings
|
|
159
|
+
|
|
160
|
+
### **Secret Management**
|
|
161
|
+
- โ
**Use GitHub secrets** (never environment variables in code)
|
|
162
|
+
- โ
**Descriptive names** (`APP_ID`, `PRIVATE_KEY` for clarity)
|
|
163
|
+
- โ
**Document requirements** for team members
|
|
164
|
+
- โ
**Backup strategy** for private keys
|
|
165
|
+
|
|
166
|
+
## ๐จ Customization for Your Project
|
|
167
|
+
|
|
168
|
+
### **For gem-ci Template Users**
|
|
169
|
+
|
|
170
|
+
When copying the gem-ci template, update these values:
|
|
171
|
+
|
|
172
|
+
```yaml
|
|
173
|
+
# Replace in your GitHub App settings:
|
|
174
|
+
App name: YOUR_PROJECT-automation
|
|
175
|
+
Description: Professional automation for YOUR_PROJECT
|
|
176
|
+
Homepage URL: https://github.com/YOUR_USERNAME/YOUR_PROJECT
|
|
177
|
+
|
|
178
|
+
# Replace in repository secrets:
|
|
179
|
+
APP_ID โ Your GitHub App ID
|
|
180
|
+
PRIVATE_KEY โ Your GitHub App private key
|
|
181
|
+
|
|
182
|
+
# Update in workflow files:
|
|
183
|
+
gem-ci[bot] โ YOUR_PROJECT[bot]
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### **Branding Variables**
|
|
187
|
+
|
|
188
|
+
The gem-ci CLI tool will help replace these automatically:
|
|
189
|
+
|
|
190
|
+
```yaml
|
|
191
|
+
Template Variables:
|
|
192
|
+
{{GEM_NAME}} โ your-gem-name
|
|
193
|
+
{{AUTHOR_NAME}} โ Your Name
|
|
194
|
+
{{AUTHOR_EMAIL}} โ your@email.com
|
|
195
|
+
{{REPO_URL}} โ https://github.com/you/your-repo
|
|
196
|
+
|
|
197
|
+
Branding Variables:
|
|
198
|
+
{{APP_ID}} โ Your GitHub App ID
|
|
199
|
+
{{APP_PRIVATE_KEY}} โ Your private key
|
|
200
|
+
{{BOT_NAME}} โ your-gem-name[bot]
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## ๐จ Troubleshooting
|
|
204
|
+
|
|
205
|
+
### **Common Issues**
|
|
206
|
+
|
|
207
|
+
**Issue: "Bad credentials" error**
|
|
208
|
+
```
|
|
209
|
+
Solution:
|
|
210
|
+
1. Verify APP_ID secret is correct (numeric value)
|
|
211
|
+
2. Check PRIVATE_KEY format (includes BEGIN/END lines)
|
|
212
|
+
3. Ensure app is installed on the repository
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
**Issue: "Resource not accessible by integration"**
|
|
216
|
+
```
|
|
217
|
+
Solution:
|
|
218
|
+
1. Check app permissions in GitHub App settings
|
|
219
|
+
2. Verify app is installed with correct repository access
|
|
220
|
+
3. Ensure workflow uses app token, not GITHUB_TOKEN
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
**Issue: "App not found" error**
|
|
224
|
+
```
|
|
225
|
+
Solution:
|
|
226
|
+
1. Verify APP_ID secret matches your created app
|
|
227
|
+
2. Check app is active (not suspended)
|
|
228
|
+
3. Confirm secrets are set in correct repository
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### **Debug Steps**
|
|
232
|
+
|
|
233
|
+
1. **Verify App Creation:**
|
|
234
|
+
- Check app exists in [Developer Settings](https://github.com/settings/developers)
|
|
235
|
+
- Confirm app ID matches secret value
|
|
236
|
+
|
|
237
|
+
2. **Check Installation:**
|
|
238
|
+
- Go to app settings โ Install App
|
|
239
|
+
- Verify installation on correct repository
|
|
240
|
+
|
|
241
|
+
3. **Test Token Generation:**
|
|
242
|
+
- Run test workflow above
|
|
243
|
+
- Check workflow logs for errors
|
|
244
|
+
|
|
245
|
+
4. **Validate Permissions:**
|
|
246
|
+
- Review app permissions in settings
|
|
247
|
+
- Ensure all required permissions are granted
|
|
248
|
+
|
|
249
|
+
## ๐ Additional Resources
|
|
250
|
+
|
|
251
|
+
### **GitHub Documentation**
|
|
252
|
+
- [Creating a GitHub App](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app)
|
|
253
|
+
- [Authenticating with GitHub Apps](https://docs.github.com/en/developers/apps/building-github-apps/authenticating-with-github-apps)
|
|
254
|
+
- [Installing GitHub Apps](https://docs.github.com/en/developers/apps/managing-github-apps/installing-github-apps)
|
|
255
|
+
|
|
256
|
+
### **Security References**
|
|
257
|
+
- [Securing your GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#security)
|
|
258
|
+
- [Best practices for GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/best-practices-for-creating-a-github-app)
|
|
259
|
+
|
|
260
|
+
### **Action Documentation**
|
|
261
|
+
- [actions/create-github-app-token](https://github.com/actions/create-github-app-token) - Official GitHub action for app token generation
|
|
262
|
+
- [slackapi/slack-github-action](https://github.com/slackapi/slack-github-action) - Official Slack action for notifications
|
|
263
|
+
|
|
264
|
+
## ๐ Required Secrets
|
|
265
|
+
|
|
266
|
+
Add these secrets to your repository settings (`Settings > Secrets and variables > Actions`):
|
|
267
|
+
|
|
268
|
+
### **GitHub App Secrets**
|
|
269
|
+
- **`APP_ID`**: Your GitHub App ID (numeric)
|
|
270
|
+
- **`PRIVATE_KEY`**: Your GitHub App private key (PEM format)
|
|
271
|
+
|
|
272
|
+
### **Slack Integration Secrets** (Optional)
|
|
273
|
+
- **`SLACK_BOT_TOKEN`**: Your Slack bot token (starts with `xoxb-`)
|
|
274
|
+
- **`SLACK_CHANNEL_ID`**: Target Slack channel ID (e.g., `C1234567890`)
|
|
275
|
+
|
|
276
|
+
> ๐ก **Note**: Slack integration now uses bot tokens instead of webhook URLs for better control and branded messaging.
|
|
277
|
+
|
|
278
|
+
## โ
Setup Checklist
|
|
279
|
+
|
|
280
|
+
- [ ] GitHub App created with correct permissions
|
|
281
|
+
- [ ] Private key generated and downloaded securely
|
|
282
|
+
- [ ] App installed on target repository
|
|
283
|
+
- [ ] `APP_ID` secret configured
|
|
284
|
+
- [ ] `PRIVATE_KEY` secret configured
|
|
285
|
+
- [ ] Custom avatar uploaded
|
|
286
|
+
- [ ] Test workflow runs successfully
|
|
287
|
+
- [ ] Branded bot appears in activity logs
|
|
288
|
+
- [ ] All automation workflows updated to use app token
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
๐ **Congratulations!** Your gem-ci automation now has professional branding. Every interaction will appear as your custom bot, building recognition and trust for your project.
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# ๐ Ruby Gem Repository Lifecycle
|
|
2
|
+
|
|
3
|
+
## Diagram 1: Repository Lifecycle & Tasks
|
|
4
|
+
|
|
5
|
+
```mermaid
|
|
6
|
+
graph TD
|
|
7
|
+
subgraph "๐ Phase 1: Repository Setup"
|
|
8
|
+
A1[๐ Create Repository]
|
|
9
|
+
A2[โ๏ธ Configure Secrets & Settings]
|
|
10
|
+
A3[๐ท๏ธ Setup Labels & Rules]
|
|
11
|
+
A4[๐ก๏ธ Configure Branch Protection]
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
subgraph "๐ป Phase 2: Development Cycle"
|
|
15
|
+
B1[๐ Write Code & Tests]
|
|
16
|
+
B2[๐ค Push to Branch]
|
|
17
|
+
B3[๐งช Run Tests & Checks]
|
|
18
|
+
B4[๐ง Create Pull Request]
|
|
19
|
+
B5[๐ Welcome Contributors]
|
|
20
|
+
B6[๐ท๏ธ Auto-label Issues/PRs]
|
|
21
|
+
B7[๐ฅ Code Review Process]
|
|
22
|
+
B8[๐ Merge to Main]
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
subgraph "๐ฆ Phase 3: Dependency Management"
|
|
26
|
+
C1[๐ Check for Updates]
|
|
27
|
+
C2[๐ Create Update PRs]
|
|
28
|
+
C3[๐งช Test Dependency Changes]
|
|
29
|
+
C4[โ
Auto-merge Safe Updates]
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
subgraph "๐ Phase 4: Release Process"
|
|
33
|
+
D1[๐ท๏ธ Create Release Tag]
|
|
34
|
+
D2[๐๏ธ Build Gem Package]
|
|
35
|
+
D3[๐งช Test Built Gem]
|
|
36
|
+
D4[๐ Publish to RubyGems]
|
|
37
|
+
D5[๐ Generate Changelog]
|
|
38
|
+
D6[๐ข Send Notifications]
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
subgraph "๐ Phase 5: Ongoing Maintenance"
|
|
42
|
+
E1[๐งน Manage Stale Issues]
|
|
43
|
+
E2[๐ Check Ecosystem Health]
|
|
44
|
+
E3[๐ Monitor Performance]
|
|
45
|
+
E4[๐ฅ Engage Community]
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
%% Phase flows
|
|
49
|
+
A1 --> A2 --> A3 --> A4 --> B1
|
|
50
|
+
B1 --> B2 --> B3 --> B4 --> B5
|
|
51
|
+
B5 --> B6 --> B7 --> B8 --> B1
|
|
52
|
+
|
|
53
|
+
C1 --> C2 --> C3 --> C4 --> C1
|
|
54
|
+
|
|
55
|
+
B8 --> D1 --> D2 --> D3 --> D4 --> D5 --> D6 --> B1
|
|
56
|
+
|
|
57
|
+
E1 --> E2 --> E3 --> E4 --> E1
|
|
58
|
+
|
|
59
|
+
%% Styling
|
|
60
|
+
classDef setup fill:#e3f2fd
|
|
61
|
+
classDef dev fill:#f3e5f5
|
|
62
|
+
classDef deps fill:#fff3e0
|
|
63
|
+
classDef release fill:#e8f5e8
|
|
64
|
+
classDef maintain fill:#fce4ec
|
|
65
|
+
|
|
66
|
+
class A1,A2,A3,A4 setup
|
|
67
|
+
class B1,B2,B3,B4,B5,B6,B7,B8 dev
|
|
68
|
+
class C1,C2,C3,C4 deps
|
|
69
|
+
class D1,D2,D3,D4,D5,D6 release
|
|
70
|
+
class E1,E2,E3,E4 maintain
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Diagram 2: Lifecycle Tasks โ CI/CD Workflows Mapping
|
|
74
|
+
|
|
75
|
+
```mermaid
|
|
76
|
+
graph LR
|
|
77
|
+
subgraph "๐ Repository Tasks"
|
|
78
|
+
T1[โ๏ธ Configure Secrets & Settings]
|
|
79
|
+
T2[๐ท๏ธ Setup Labels & Rules]
|
|
80
|
+
T3[๐งช Run Tests & Checks]
|
|
81
|
+
T4[๐ Welcome Contributors]
|
|
82
|
+
T5[๐ท๏ธ Auto-label Issues/PRs]
|
|
83
|
+
T6[๐ Check for Updates]
|
|
84
|
+
T7[๐ Create Update PRs]
|
|
85
|
+
T8[๐๏ธ Build Gem Package]
|
|
86
|
+
T9[๐ Publish to RubyGems]
|
|
87
|
+
T10[๐ Generate Changelog]
|
|
88
|
+
T11[๐ข Send Notifications]
|
|
89
|
+
T12[๐งน Manage Stale Issues]
|
|
90
|
+
T13[๐ Check Ecosystem Health]
|
|
91
|
+
T14[๐ Monitor Performance]
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
subgraph "๐ค Our CI/CD Workflows"
|
|
95
|
+
W1[01-intake.yml<br/>๐ท๏ธ Intake & Labels]
|
|
96
|
+
W2[02-ci.yml<br/>๐งช Continuous Integration]
|
|
97
|
+
W3[03-security.yml<br/>๐ Security Scanning]
|
|
98
|
+
W4[04-quality.yml<br/>๐ Code Quality]
|
|
99
|
+
W5[05-community.yml<br/>๐ฅ Community Management]
|
|
100
|
+
W6[06-release.yml<br/>๐ Release & Publishing]
|
|
101
|
+
W7[07-ecosystem.yml<br/>๐ Ecosystem Integration]
|
|
102
|
+
W8[08-monitoring.yml<br/>๐ Health Monitoring]
|
|
103
|
+
W9[Dependabot<br/>๐ฆ Dependency Updates]
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
%% Task to Workflow Mappings
|
|
107
|
+
T1 -.-> W1
|
|
108
|
+
T2 --> W1
|
|
109
|
+
T3 --> W2
|
|
110
|
+
T3 --> W3
|
|
111
|
+
T3 --> W4
|
|
112
|
+
T4 --> W1
|
|
113
|
+
T5 --> W1
|
|
114
|
+
T6 --> W9
|
|
115
|
+
T7 --> W9
|
|
116
|
+
T8 --> W6
|
|
117
|
+
T9 --> W6
|
|
118
|
+
T10 --> W6
|
|
119
|
+
T11 --> W6
|
|
120
|
+
T12 --> W5
|
|
121
|
+
T13 --> W7
|
|
122
|
+
T14 --> W8
|
|
123
|
+
|
|
124
|
+
%% Styling
|
|
125
|
+
classDef task fill:#e8f5e8
|
|
126
|
+
classDef workflow fill:#f3e5f5
|
|
127
|
+
|
|
128
|
+
class T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14 task
|
|
129
|
+
class W1,W2,W3,W4,W5,W6,W7,W8,W9 workflow
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## ๐ Repository Lifecycle Timeline
|
|
133
|
+
|
|
134
|
+
| Phase | Duration | Key Activities | Frequency |
|
|
135
|
+
|-------|----------|----------------|-----------|
|
|
136
|
+
| **๐ Setup** | 1-2 days | Initial configuration, secrets, labels | Once |
|
|
137
|
+
| **๐ป Development** | Ongoing | Code, test, review, merge | Daily |
|
|
138
|
+
| **๐ฆ Dependencies** | Background | Automated dependency updates | Weekly |
|
|
139
|
+
| **๐ Release** | 30 minutes | Tag, build, publish, notify | As needed |
|
|
140
|
+
| **๐ Maintenance** | Background | Community management, monitoring | Daily/Weekly |
|
|
141
|
+
|
|
142
|
+
## ๐ฏ Task โ Workflow Mapping Table
|
|
143
|
+
|
|
144
|
+
| Repository Task | Our CI/CD Solution | Trigger | Frequency |
|
|
145
|
+
|----------------|-------------------|---------|-----------|
|
|
146
|
+
| **โ๏ธ Configure Settings** | Manual setup | One-time | Once |
|
|
147
|
+
| **๐ท๏ธ Setup Labels** | `01-intake.yml` | Manual/Push | Once + updates |
|
|
148
|
+
| **๐งช Run Tests** | `02-ci.yml`, `03-security.yml`, `04-quality.yml` | Push/PR | Every change |
|
|
149
|
+
| **๐ Welcome Contributors** | `01-intake.yml` | First PR/Issue | Per new contributor |
|
|
150
|
+
| **๐ท๏ธ Auto-label** | `01-intake.yml` | PR/Issue created | Every PR/Issue |
|
|
151
|
+
| **๐ฆ Update Dependencies** | Dependabot + CI workflows | Schedule | Weekly + testing |
|
|
152
|
+
| **๐ Build & Publish** | `06-release.yml` | Tag created | Per release |
|
|
153
|
+
| **๐งน Manage Community** | `05-community.yml` | Schedule | Daily |
|
|
154
|
+
| **๐ Check Ecosystem** | `07-ecosystem.yml` | Schedule | Weekly |
|
|
155
|
+
| **๐ Monitor Health** | `08-monitoring.yml` | Schedule | Daily |
|
|
156
|
+
|
|
157
|
+
## ๐ Complete Development Flow
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
Repository Lifecycle:
|
|
161
|
+
Setup โ Development โท Dependencies โ Release โ Maintenance
|
|
162
|
+
โ โ โ โ โ
|
|
163
|
+
Our Workflows:
|
|
164
|
+
Manual โ 01,02,03,04 โ Dependabot+CI โ 06 โ 05,07,08
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
This separation makes it much clearer:
|
|
168
|
+
1. **First diagram**: Shows the natural lifecycle and tasks
|
|
169
|
+
2. **Second diagram**: Shows how our specific workflows handle those tasks
|
|
170
|
+
3. **Tables**: Provide detailed mapping and timing information
|
data/lib/gem_ci.rb
ADDED
data/sig/gem/ci.rbs
ADDED
metadata
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: gem-ci
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.2.1
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Huy Nguyen
|
|
8
|
+
autorequire:
|
|
9
|
+
bindir: exe
|
|
10
|
+
cert_chain: []
|
|
11
|
+
date: 2025-07-26 00:00:00.000000000 Z
|
|
12
|
+
dependencies: []
|
|
13
|
+
description: A showcase repository demonstrating advanced CI/CD workflows, automated
|
|
14
|
+
testing, security scanning, community management, and comprehensive automation for
|
|
15
|
+
Ruby gems.
|
|
16
|
+
email:
|
|
17
|
+
- patrick204nqh@gmail.com
|
|
18
|
+
executables: []
|
|
19
|
+
extensions: []
|
|
20
|
+
extra_rdoc_files: []
|
|
21
|
+
files:
|
|
22
|
+
- ".markdownlint.yml"
|
|
23
|
+
- ".rspec"
|
|
24
|
+
- ".rubocop.yml"
|
|
25
|
+
- CHANGELOG.md
|
|
26
|
+
- LICENSE.txt
|
|
27
|
+
- README.md
|
|
28
|
+
- Rakefile
|
|
29
|
+
- docs/MANUAL_WORKFLOW_TESTING.md
|
|
30
|
+
- docs/SECRETS_SETUP_GUIDE.md
|
|
31
|
+
- docs/diagrams/ci-workflow-overview.md
|
|
32
|
+
- lib/gem_ci.rb
|
|
33
|
+
- lib/gem_ci/version.rb
|
|
34
|
+
- sig/gem/ci.rbs
|
|
35
|
+
homepage: https://github.com/patrick204nqh/gem-ci
|
|
36
|
+
licenses:
|
|
37
|
+
- MIT
|
|
38
|
+
metadata:
|
|
39
|
+
allowed_push_host: https://rubygems.org
|
|
40
|
+
source_code_uri: https://github.com/patrick204nqh/gem-ci
|
|
41
|
+
changelog_uri: https://github.com/patrick204nqh/gem-ci/blob/main/CHANGELOG.md
|
|
42
|
+
documentation_uri: https://github.com/patrick204nqh/gem-ci/blob/main/README.md
|
|
43
|
+
post_install_message:
|
|
44
|
+
rdoc_options: []
|
|
45
|
+
require_paths:
|
|
46
|
+
- lib
|
|
47
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
48
|
+
requirements:
|
|
49
|
+
- - ">="
|
|
50
|
+
- !ruby/object:Gem::Version
|
|
51
|
+
version: 3.1.0
|
|
52
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
53
|
+
requirements:
|
|
54
|
+
- - ">="
|
|
55
|
+
- !ruby/object:Gem::Version
|
|
56
|
+
version: '0'
|
|
57
|
+
requirements: []
|
|
58
|
+
rubygems_version: 3.5.22
|
|
59
|
+
signing_key:
|
|
60
|
+
specification_version: 4
|
|
61
|
+
summary: Comprehensive OSS automation showcase with battle-tested GitHub Actions
|
|
62
|
+
test_files: []
|