Skip to content

Commit ec1c6d6

Browse files
Alec CunninghamAlec Cunningham
Alec Cunningham
authored and
Alec Cunningham
committed
chore: update README
1 parent c738d70 commit ec1c6d6

File tree

2 files changed

+248
-4
lines changed

2 files changed

+248
-4
lines changed

‎README.md‎

Lines changed: 244 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,244 @@
1-
# github-actions-aggregator
1+
# GitHub Actions Aggregator Service
2+
3+
A Go-based service to aggregate and analyze data from GitHub Actions workflows across multiple repositories. This application provides insights into workflow runs, success rates, failure rates, and other statistics over customizable time ranges.
4+
5+
## Table of Contents
6+
7+
- [Features](#features)
8+
- [Prerequisites](#prerequisites)
9+
- [Installation](#installation)
10+
- [Configuration](#configuration)
11+
- [Usage](#usage)
12+
- [API Endpoints](#api-endpoints)
13+
- [Authentication](#authentication)
14+
- [Testing](#testing)
15+
- [Contributing](#contributing)
16+
- [License](#license)
17+
18+
## Features
19+
20+
- **OAuth 2.0 Authentication**: Securely authenticate users via GitHub OAuth.
21+
- **Data Collection**:
22+
- **Webhooks**: Receive real-time updates on workflow events.
23+
- **Polling**: Periodically poll GitHub API to ensure data completeness.
24+
- **Data Aggregation**: Compute statistics like success rates, failure rates, and more.
25+
- **API Endpoints**: Expose RESTful APIs for accessing aggregated data.
26+
- **Background Processing**: Use worker pools to handle asynchronous tasks.
27+
- **Configurable**: Easily adjust settings like polling intervals and webhook secrets.
28+
- **Secure**: Validate webhook payloads and protect routes with authentication middleware.
29+
30+
## Prerequisites
31+
32+
- **Go**: Version 1.18 or higher.
33+
- **GitHub Account**: For OAuth authentication and API access.
34+
- **PostgreSQL**: For storing data.
35+
- **Redis** (optional): For caching (if implemented).
36+
- **Docker** (optional): For containerization and deployment.
37+
38+
## Installation
39+
40+
1. **Clone the Repository**
41+
42+
```bash
43+
git clone https://github.com/yourusername/github-actions-aggregator.git
44+
cd github-actions-aggregator
45+
```
46+
47+
2. **Install Dependencies**
48+
49+
```bash
50+
go mod download
51+
```
52+
53+
3. **Set Up Environment Variables**
54+
55+
Create a `.env` file or export the required environment variables:
56+
57+
```bash
58+
export GITHUB_CLIENT_ID="your_github_client_id"
59+
export GITHUB_CLIENT_SECRET="your_github_client_secret"
60+
export GITHUB_ACCESS_TOKEN="your_github_access_token"
61+
export GITHUB_WEBHOOK_SECRET="your_webhook_secret"
62+
export DATABASE_URL="postgres://username:password@localhost:5432/yourdbname?sslmode=disable"
63+
export SERVER_PORT="8080"
64+
```
65+
66+
## Configuration
67+
68+
Configuration can be managed via a `config.yaml` file in the `configs/` directory or through environment variables.
69+
70+
**Example `config.yaml`:**
71+
72+
```yaml
73+
server:
74+
port: "8080"
75+
76+
log:
77+
level: "info"
78+
79+
github:
80+
client_id: "your_github_client_id"
81+
client_secret: "your_github_client_secret"
82+
access_token: "your_github_access_token"
83+
webhook_secret: "your_webhook_secret"
84+
```
85+
86+
**Note:** Environment variables override values in the configuration file.
87+
88+
## Usage
89+
90+
### Running the Application
91+
92+
1. **Run Database Migrations**
93+
94+
```bash
95+
./scripts/migrate.sh
96+
```
97+
98+
2. **Start the Application**
99+
100+
```bash
101+
go run cmd/server/main.go
102+
```
103+
104+
### Accessing the Application
105+
106+
- **Login with GitHub**: Navigate to `http://localhost:8080/login` to authenticate via GitHub.
107+
- **API Requests**: Use tools like `curl` or Postman to interact with the API endpoints.
108+
109+
## API Endpoints
110+
111+
### Authentication
112+
113+
- `GET /login`: Redirects the user to GitHub for OAuth authentication.
114+
- `GET /callback`: Handles the OAuth callback from GitHub.
115+
116+
### Workflow Statistics
117+
118+
- `GET /workflows/:id/stats`: Retrieves statistics for a specific workflow.
119+
120+
**Query Parameters:**
121+
122+
- `start_time` (optional): Start of the time range (ISO 8601 format).
123+
- `end_time` (optional): End of the time range (ISO 8601 format).
124+
125+
**Example Request:**
126+
127+
```http
128+
GET /workflows/123/stats?start_time=2023-09-01T00:00:00Z&end_time=2023-09-30T23:59:59Z
129+
```
130+
131+
**Example Response:**
132+
133+
```json
134+
{
135+
"workflow_id": 123,
136+
"workflow_name": "CI Build and Test",
137+
"total_runs": 200,
138+
"success_count": 150,
139+
"failure_count": 30,
140+
"cancelled_count": 10,
141+
"timed_out_count": 5,
142+
"action_required_count": 5,
143+
"success_rate": 75.0,
144+
"failure_rate": 15.0,
145+
"cancelled_rate": 5.0,
146+
"timed_out_rate": 2.5,
147+
"action_required_rate": 2.5,
148+
"start_time": "2023-09-01T00:00:00Z",
149+
"end_time": "2023-09-30T23:59:59Z"
150+
}
151+
```
152+
153+
## Authentication
154+
155+
### Setting Up OAuth with GitHub
156+
157+
1. **Register a New OAuth Application**
158+
159+
- Go to [GitHub Developer Settings](https://github.com/settings/developers).
160+
- Click on **"New OAuth App"**.
161+
- Fill in the application details:
162+
- **Application Name**
163+
- **Homepage URL**: `http://localhost:8080`
164+
- **Authorization Callback URL**: `http://localhost:8080/callback`
165+
- Obtain your **Client ID** and **Client Secret**.
166+
167+
2. **Configure Application Credentials**
168+
169+
Set your `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` in your environment variables or `config.yaml`.
170+
171+
### Permissions and Scopes
172+
173+
Ensure that your GitHub OAuth application has the necessary scopes:
174+
175+
- `read:user`
176+
- `repo`
177+
- `workflow`
178+
179+
## Testing
180+
181+
### Running Unit Tests
182+
183+
```bash
184+
go test ./tests/unit/...
185+
```
186+
187+
### Running Integration Tests
188+
189+
```bash
190+
go test ./tests/integration/...
191+
```
192+
193+
### Test Coverage
194+
195+
You can generate a test coverage report using:
196+
197+
```bash
198+
go test -coverprofile=coverage.out ./...
199+
go tool cover -html=coverage.out
200+
```
201+
202+
## Contributing
203+
204+
Contributions are welcome! Please follow these steps:
205+
206+
1. **Fork the Repository**
207+
208+
Click on the "Fork" button at the top right of the repository page.
209+
210+
2. **Clone Your Fork**
211+
212+
```bash
213+
git clone https://github.com/yourusername/github-actions-aggregator.git
214+
```
215+
216+
3. **Create a Feature Branch**
217+
218+
```bash
219+
git checkout -b feature/your-feature-name
220+
```
221+
222+
4. **Commit Your Changes**
223+
224+
```bash
225+
git commit -am "Add new feature"
226+
```
227+
228+
5. **Push to Your Fork**
229+
230+
```bash
231+
git push origin feature/your-feature-name
232+
```
233+
234+
6. **Create a Pull Request**
235+
236+
Go to the original repository and open a pull request.
237+
238+
## License
239+
240+
This project is licensed under the [MIT License](LICENSE).
241+
242+
---
243+
244+
**Disclaimer:** This project is not affiliated with GitHub. Ensure compliance with GitHub's [Terms of Service](https://docs.github.com/en/github/site-policy/github-terms-of-service) when using their APIs.

‎pkg/db/models/statistics.go‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@ package models
33
import "time"
44

55
type Statistics struct {
6-
ID uint `gorm:"primaryKey"`
7-
TotalRuns int64
8-
SuccessRate float64
6+
ID uint `gorm:"primaryKey"`
7+
TotalRuns int64
8+
SuccessRate float64
9+
AverageDuration time.Duration
910
// Add fields for additional statistics
1011
UpdatedAt time.Time
1112
}

0 commit comments

Comments
 (0)