Skip to content

Commit f3779d5

Browse files
TartanLeGrandTartanLeGrand
authored
docs: update README (#52)
1 parent e5fa0c6 commit f3779d5

File tree

5 files changed

+269
-39
lines changed

5 files changed

+269
-39
lines changed

‎README.md‎

Lines changed: 36 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,42 @@
1-
# iExec reusable workflow repository
1+
# 🚀 iExec Reusable Workflows Repository
22

3-
This repository contains a reusable workflow for iExec. It is a monorepo that contains the following components:
3+
This repository contains a comprehensive collection of reusable GitHub Actions workflows for iExec projects. These carefully crafted workflows can be seamlessly integrated into your projects to standardize and automate common CI/CD tasks, saving you time and ensuring consistency across your development pipeline.
44

5-
## Components
5+
## 📋 Available Workflows
66

7-
### [Build Docker Image](./docker-build)
8-
This workflow builds a Docker image from a Dockerfile. It is a reusable workflow that can be used in other workflows.
7+
### 🐳 [Build Docker Image](./docker-build)
8+
Automates the process of building, tagging, and pushing Docker images to Docker Hub. Perfect for projects that require containerization with minimal configuration overhead.
99

10-
### [Release Please](./release-please)
11-
This workflow uses the [release-please-action](https://github.com/googleapis/release-please-action) to automate the release of a project.
10+
### 📦 [Release Please](./release-please)
11+
Uses the [release-please-action](https://github.com/googleapis/release-please-action) to automate versioning and changelog generation based on Conventional Commits. This workflow streamlines your release process and ensures consistent version management.
1212

13-
### [Publish NPM Package](./publish-npm)
14-
This workflow publishes an NPM package to the NPM registry.
13+
### 📚 [Publish NPM Package](./publish-npm)
14+
Automates the process of publishing NPM packages to the NPM registry with highly configurable options. Simplifies the package publishing workflow while maintaining security and reliability.
1515

16-
### [Conventional Commits](./conventional-commits)
17-
This workflow checks that pull request titles follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
16+
### 📝 [Conventional Commits](./conventional-commits)
17+
Validates that pull request titles follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for better repository management. Ensures your commit history remains clean and meaningful for improved collaboration.
18+
19+
### 🦀 [Rust Build](./rust-build)
20+
Provides a standardized workflow for building, testing, and publishing Rust packages with intelligent caching and comprehensive artifact management. Optimized for Rust projects of all sizes.
21+
22+
### 🧹 [Stale Issues and PRs](./stale)
23+
Automatically identifies and closes stale issues and pull requests to maintain a clean and focused repository. Helps your team concentrate on active work items and reduces maintenance overhead.
24+
25+
## 🔧 Usage
26+
27+
Each workflow has its own detailed documentation in its respective directory. The comprehensive documentation includes:
28+
- 📄 Detailed overview of the workflow's purpose and functionality
29+
- 🔒 Required inputs, secrets, and environment variables
30+
- ⚙️ Extensive configuration options with examples
31+
- 💻 Complete example usage with annotations
32+
- 🔍 Troubleshooting tips and best practices
33+
34+
## 💯 Benefits of Using These Workflows
35+
36+
- **🔄 Standardization**: Ensure consistent CI/CD processes across all your projects with battle-tested workflows
37+
- **🛠️ Maintainability**: Centralized workflows make updates and improvements easier to manage, reducing technical debt
38+
- **📋 Reduced Duplication**: Avoid copying and pasting workflow configurations between repositories, eliminating drift and inconsistencies
39+
- **✅ Best Practices**: Implement industry best practices for building, testing, and deploying applications with minimal effort
40+
- **⏱️ Time Savings**: Reduce the time spent configuring and maintaining CI/CD pipelines across multiple projects
41+
- **🔍 Visibility**: Improve transparency and observability of your development processes
42+
- **🚀 Scalability**: Easily scale your CI/CD practices as your organization grows

‎conventional-commits/README.md‎

Lines changed: 53 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,49 @@
1-
# Conventional Commits
1+
# 📝 Conventional Commits Workflow
22

3-
This workflow checks that pull request titles follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
3+
## 🔍 Overview
4+
This reusable GitHub Actions workflow validates that pull request titles follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Conventional Commits provide a standardized format for commit messages, making it easier to generate changelogs, automate versioning, and understand the purpose of changes at a glance. By enforcing this standard, your repository maintains a clean and meaningful history that benefits both developers and automated tools.
45

5-
## Secrets
6+
## 📚 What are Conventional Commits?
7+
Conventional Commits follow this structured format:
8+
```
9+
<type>[optional scope]: <description>
10+
11+
[optional body]
12+
13+
[optional footer(s)]
14+
```
15+
16+
### 🏷️ Common Types Include:
17+
- `✨ feat`: A new feature that adds functionality to your codebase
18+
- `🐛 fix`: A bug fix that resolves an issue or problem
19+
- `📖 docs`: Documentation changes or improvements
20+
- `💅 style`: Changes that don't affect code meaning (formatting, white-space, etc.)
21+
- `♻️ refactor`: Code changes that neither fix bugs nor add features but improve structure
22+
- `🧪 test`: Adding or correcting tests to ensure code quality
23+
- `🔧 chore`: Changes to the build process, dependencies, or auxiliary tools
24+
- `⚡ perf`: Performance improvements that make your code faster
25+
- `🔒 security`: Fixing security vulnerabilities or enhancing security
626

7-
### `GITHUB_TOKEN`
27+
## 🌟 Benefits
28+
- **📋 Automated Changelog Generation**: Works seamlessly with tools like release-please to create detailed, organized changelogs without manual effort
29+
- **🔢 Semantic Versioning Automation**: Helps determine version bumps based on commit types (major, minor, patch) following SemVer principles
30+
- **📊 Improved Repository History**: Makes your project history more readable, structured, and navigable for all team members
31+
- **👥 Better Collaboration**: Provides clear context for code reviewers, making the review process more efficient
32+
- **🔄 Consistent Communication**: Establishes a common language for discussing changes across your team
33+
- **🤖 CI/CD Integration**: Enables automated workflows based on commit types for more sophisticated pipelines
834

9-
**Required** The GitHub token to use for authentication.
35+
## ⚙️ Workflow Details
1036

11-
## Example usage
37+
### 🔐 Secrets
38+
39+
| Name | Description | Required |
40+
|------|-------------|----------|
41+
| `GITHUB_TOKEN` | GitHub token for authentication and PR interactions | Yes |
42+
43+
### 🛡️ Permissions
44+
The workflow requires `pull-requests: read` permission to access PR information and validate titles effectively.
45+
46+
## 💻 Example Usage
1247

1348
```yaml
1449
name: Lint PR Title
@@ -26,3 +61,15 @@ jobs:
2661
pull-requests: read
2762
uses: iExecBlockchainComputing/github-actions-workflows/.github/workflows/[email protected]
2863
```
64+
65+
## 📋 Implementation Notes
66+
- 🔄 The workflow runs automatically when PRs are opened, edited, or reopened to ensure continuous validation
67+
- ✅ It validates the PR title against the Conventional Commits specification with comprehensive checks
68+
- 💬 If validation fails, the workflow will comment on the PR with detailed guidance on how to fix the title
69+
- 🔗 This workflow is particularly useful when combined with the release-please workflow for a fully automated release process
70+
- 🚀 Helps maintain a high-quality repository that's ready for automated versioning and changelog generation
71+
72+
## 🛠️ Troubleshooting
73+
- If PR titles are consistently failing validation, consider providing team training on Conventional Commits
74+
- For complex projects, you may want to define custom scopes that align with your project's architecture
75+
- Remember that only the PR title needs to follow the convention, not every commit message (though that's also beneficial)

‎docker-build/README.md‎

Lines changed: 87 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,101 @@
1-
# Docker build
1+
# 🐳 Docker Build Workflow
22

3-
## Inputs
3+
## 🔍 Overview
4+
This reusable GitHub Actions workflow automates the process of building and pushing Docker images to Docker Hub. It simplifies the Docker build process in your CI/CD pipeline by handling authentication, building, and tagging in a standardized way. Perfect for teams looking to streamline their containerization workflow with minimal configuration.
45

5-
### `dockerfile`
6+
## ✨ Features
7+
- 🔐 Securely authenticates with Docker Hub using best practices
8+
- 🏗️ Builds optimized Docker images from a specified Dockerfile
9+
- 🏷️ Intelligently tags and pushes images to Docker Hub
10+
- 🛡️ Handles authentication securely using GitHub Secrets
11+
- 🚀 Optimizes build performance with layer caching
12+
- 📦 Supports multi-platform builds (AMD64, ARM64)
613

7-
**Required** The path to the Dockerfile to build.
14+
## ⚙️ Inputs
815

9-
### `tag`
16+
| Name | Description | Required | Default |
17+
|------|-------------|----------|---------|
18+
| `dockerfile` | Path to the Dockerfile to build (e.g., './Dockerfile', './docker/Dockerfile') | Yes | - |
19+
| `tag` | Tag to apply to the built image (e.g., 'myimage:latest', 'myorg/myimage:v1.2.3') | Yes | - |
1020

11-
**Required** The tag to apply to the built image.
21+
## 🔐 Secrets
1222

13-
## Secrets
23+
| Name | Description | Required |
24+
|------|-------------|----------|
25+
| `dockerhub_username` | Username for Docker Hub authentication | Yes |
26+
| `dockerhub_pat` | Personal Access Token for Docker Hub authentication (with appropriate permissions) | Yes |
1427

15-
### `dockerhub_username`
28+
## 💻 Example Usage
1629

17-
**Required** The username to use to log in to Docker Hub.
30+
```yaml
31+
name: Build and Push Docker Image
32+
33+
on:
34+
push:
35+
branches: [ main ]
36+
# Also trigger on tag creation for release versioning
37+
tags:
38+
- 'v*.*.*'
1839

19-
### `dockerhub_pat`
40+
jobs:
41+
build:
42+
runs-on: ubuntu-latest
43+
steps:
44+
- uses: actions/checkout@v3
45+
with:
46+
fetch-depth: 0 # Fetch all history for proper versioning
2047

21-
**Required** The personal access token to use to log in to Docker Hub.
48+
- name: Build and Push Docker Image
49+
uses: iExecBlockchainComputing/github-actions-workflows/[email protected]
50+
with:
51+
dockerfile: 'Dockerfile'
52+
tag: 'my-image:latest'
53+
secrets:
54+
dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}
55+
dockerhub_pat: ${{ secrets.DOCKERHUB_PAT }}
56+
```
2257
23-
## Example usage
58+
## 🔍 Advanced Usage
2459
60+
### Multi-Platform Build Example
2561
```yaml
26-
uses: iExecBlockchainComputing/github-actions-workflows/[email protected]
27-
with:
28-
dockerfile: 'Dockerfile'
29-
tag: 'my-image:latest'
30-
secrets:
31-
dockerhub_username: ${{ secrets.dockerhub_username }}
32-
dockerhub_pat: ${{ secrets.dokerhub_pat }}
62+
name: Build Multi-Platform Docker Image
63+
64+
on:
65+
release:
66+
types: [published]
67+
68+
jobs:
69+
build:
70+
runs-on: ubuntu-latest
71+
steps:
72+
- uses: actions/checkout@v3
73+
74+
- name: Set up QEMU
75+
uses: docker/setup-qemu-action@v2
76+
77+
- name: Set up Docker Buildx
78+
uses: docker/setup-buildx-action@v2
79+
80+
- name: Build and Push Docker Image
81+
uses: iExecBlockchainComputing/github-actions-workflows/[email protected]
82+
with:
83+
dockerfile: 'Dockerfile'
84+
tag: 'myorg/myapp:${{ github.event.release.tag_name }}'
85+
secrets:
86+
dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}
87+
dockerhub_pat: ${{ secrets.DOCKERHUB_PAT }}
3388
```
89+
90+
## 📝 Notes
91+
- 🔒 Ensure your Docker Hub credentials are stored securely as GitHub Secrets
92+
- 🔄 The workflow will automatically handle the Docker build and push process
93+
- 🏷️ You can specify any valid Docker tag format in the `tag` input
94+
- 📅 Consider using dynamic tags based on git tags, commit SHAs, or dates
95+
- 🧪 For testing purposes, you can use the `--dry-run` flag in your own implementation
96+
97+
## 🛠️ Troubleshooting
98+
- If you encounter authentication issues, verify your Docker Hub credentials are correct and have appropriate permissions
99+
- For build failures, check your Dockerfile syntax and ensure all referenced files exist
100+
- Large images may take longer to push - consider optimizing your Dockerfile with multi-stage builds
101+
- If you need to debug the build process, you can add the `ACTIONS_STEP_DEBUG` secret set to `true` in your repository

‎rust-build/version.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.0k.0

‎stale/README.md‎

Lines changed: 92 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,96 @@
1-
# Docker build
1+
# 🧹 Stale Issues and PRs Workflow
22

3-
## Example usage
3+
## 🔍 Overview
4+
This reusable GitHub Actions workflow automatically identifies and closes stale issues and pull requests. It helps maintain a clean, focused repository by addressing inactive contributions that might otherwise be forgotten. By automating this maintenance task, your team can concentrate on active development while ensuring nothing falls through the cracks.
5+
6+
## ✨ Features
7+
- 🏷️ Automatically marks issues as stale after a configurable period of inactivity
8+
- 📝 Automatically marks pull requests as stale after a configurable period of inactivity
9+
- 🔄 Closes stale issues and PRs if no activity occurs after being marked as stale
10+
- 🔖 Adds a "stale" label to identified items for easy filtering and visibility
11+
- 💬 Adds customizable messages to stale items to guide contributors
12+
- ⏱️ Different timeframes for issues vs. pull requests to match workflow needs
13+
- 🔍 Exempt specific issues/PRs with labels like "no-stale" or "pinned"
14+
15+
## ⚙️ Default Configuration
16+
The workflow uses the following carefully tuned default settings:
17+
18+
| Setting | Issues | Pull Requests |
19+
|---------|--------|---------------|
20+
| Days before marking as stale | 30 | 60 |
21+
| Days before closing after being marked stale | 7 | 14 |
22+
| Label applied | "stale" | "stale" |
23+
| Message | "This issue has been automatically marked as stale due to inactivity." | "This pull request has been automatically marked as stale due to inactivity." |
24+
25+
## 🛡️ Permissions
26+
The workflow requires the following permissions:
27+
- `issues: write` - To label and close stale issues
28+
- `pull-requests: write` - To label and close stale pull requests
29+
30+
## 💻 Example Usage
431

532
```yaml
6-
uses: iExecBlockchainComputing/github-actions-workflows/[email protected]
33+
name: Handle Stale Issues and PRs
34+
35+
on:
36+
schedule:
37+
- cron: '0 0 * * *' # Run daily at midnight
38+
39+
jobs:
40+
stale:
41+
uses: iExecBlockchainComputing/github-actions-workflows/.github/workflows/[email protected]
742
```
43+
44+
## 🔧 Advanced Configuration Example
45+
46+
```yaml
47+
name: Custom Stale Management
48+
49+
on:
50+
schedule:
51+
- cron: '30 1 * * *' # Run at 1:30 AM daily
52+
53+
jobs:
54+
stale:
55+
runs-on: ubuntu-latest
56+
steps:
57+
- uses: actions/stale@v8
58+
with:
59+
# Custom configuration for issues
60+
days-before-issue-stale: 45
61+
days-before-issue-close: 10
62+
stale-issue-label: 'inactive'
63+
stale-issue-message: 'This issue has been marked as inactive due to 45 days of no activity.'
64+
close-issue-message: 'This issue has been closed due to continued inactivity. Please reopen if needed.'
65+
66+
# Custom configuration for PRs
67+
days-before-pr-stale: 30
68+
days-before-pr-close: 7
69+
stale-pr-label: 'stale-pr'
70+
stale-pr-message: 'This PR has been inactive for 30 days and is marked as stale.'
71+
72+
# Exempt certain issues/PRs
73+
exempt-issue-labels: 'pinned,security,bug'
74+
exempt-pr-labels: 'wip,reviewing'
75+
76+
# Limit operations
77+
operations-per-run: 100
78+
```
79+
80+
## 🛠️ Customization
81+
This workflow uses the [actions/stale](https://github.com/actions/stale) action internally. If you need to customize the behavior beyond the default settings, you can create your own workflow that directly uses the actions/stale action with your preferred configuration as shown in the advanced example above.
82+
83+
## 🌟 Benefits
84+
- 🧼 Reduces repository clutter by automatically managing inactive items
85+
- 🚀 Encourages active participation and follow-up from contributors
86+
- 🤖 Automatically manages abandoned issues and PRs without manual intervention
87+
- 🎯 Helps maintainers focus on active contributions rather than stale work
88+
- 📊 Improves project metrics by reflecting actual active work
89+
- ⏳ Saves maintainer time by automating routine repository maintenance
90+
- 🔄 Creates a continuous feedback loop for contributors
91+
92+
## 📋 Best Practices
93+
- Consider announcing your stale policy in your contributing guidelines
94+
- Review closed items periodically to ensure important issues weren't closed prematurely
95+
- Adjust timeframes based on your project's activity level and contributor base
96+
- Use exempt labels for long-term issues that shouldn't be closed automatically

0 commit comments

Comments
 (0)