Skip to content

Commit 9a1969d

Browse files
paulgessingerpaulgessinger
authored
Trigger GitHub job on GitLab completion (#1)
1 parent 2ea04e6 commit 9a1969d

12 files changed

Lines changed: 1187 additions & 2 deletions

‎README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
11
# CI Bridge
22

3-
This piece of software acts as a relay between GitHub and the GitLab CI service. It receives webhooks from GitHub repos that it is installed on, and triggers GitLab jobs based on job configuration that is stored in the GitHub repo. It then waits and listens for webhook events from GitLab when the triggered jobs have state transitions, and relays this information back to the GitHub side, also creating commit statuses that can be used in PR reviews, among other things.V
3+
This piece of software acts as a relay between GitHub and the GitLab CI service. It receives webhooks from GitHub repos that it is installed on, and triggers GitLab jobs based on job configuration that is stored in the GitHub repo. It then waits and listens for webhook events from GitLab when the triggered jobs have state transitions, and relays this information back to the GitHub side, also creating commit statuses that can be used in PR reviews, among other things.
4+
5+
## Features
6+
7+
### GitHub → GitLab Integration
8+
- Triggers GitLab CI pipelines when GitHub events occur (push, PR, etc.)
9+
- Creates GitHub check runs with GitLab job status and logs
10+
- Supports team-based access control and job filtering
11+
12+
### GitLab → GitHub Integration
13+
- **NEW**: Triggers GitHub Actions workflows when GitLab jobs finish
14+
- Auto-detects target repository and compatible workflows
15+
- Configurable job status filters
16+
- Always runs workflows on the main branch
17+
- Provides detailed GitLab job information to GitHub workflows
18+
19+
For detailed setup and configuration of the GitLab to GitHub triggering feature, see [docs/GITLAB_TO_GITHUB_TRIGGERING.md](docs/GITLAB_TO_GITHUB_TRIGGERING.md).

‎docs/GITLAB_TO_GITHUB_TRIGGERING.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# GitLab to GitHub Workflow Triggering
2+
3+
This feature allows the CI Bridge to trigger GitHub Actions workflows when GitLab CI jobs finish. When a GitLab job completes (success, failure, or other configured statuses), the system automatically checks the target repository for compatible workflows and triggers them on the main branch.
4+
5+
## Overview
6+
7+
The GitLab to GitHub triggering functionality extends the existing CI Bridge capabilities by:
8+
9+
1. **Monitoring GitLab job completions** - Listening for GitLab job hook events
10+
2. **Filtering by job status** - Only triggering on configured job statuses (e.g., success, failed)
11+
3. **Auto-detecting target repositories** - Uses the repository where GitLab status is posted
12+
4. **Workflow detection** - Automatically checks if repository has compatible workflows
13+
5. **Using repository dispatch** - Sending GitHub repository dispatch events to trigger workflows
14+
6. **Running on main branch** - Always triggering workflows on the main branch as requested
15+
16+
## Configuration
17+
18+
Add the following environment variables to enable GitLab to GitHub triggering:
19+
20+
### Required Configuration
21+
22+
```bash
23+
# Enable the feature
24+
ENABLE_GITLAB_TO_GITHUB_TRIGGERING=true
25+
```
26+
27+
### Optional Configuration
28+
29+
```bash
30+
# Job statuses that trigger workflows (default: ["success", "failed"])
31+
GITLAB_TO_GITHUB_TRIGGER_ON_STATUS=["success", "failed", "canceled"]
32+
```
33+
34+
### Example Configuration
35+
36+
```bash
37+
# .env file or environment variables
38+
ENABLE_GITLAB_TO_GITHUB_TRIGGERING=true
39+
GITLAB_TO_GITHUB_TRIGGER_ON_STATUS=["success"]
40+
```
41+
42+
## How It Works
43+
44+
1. **GitLab job completes** - A GitLab CI job finishes with a configured status
45+
2. **Repository identification** - The system uses the repository URL from the GitLab bridge payload
46+
3. **Workflow detection** - Checks if the repository has workflows listening for `repository_dispatch` events with type `gitlab-job-finished`
47+
4. **Conditional triggering** - Only triggers if compatible workflows are found
48+
5. **Workflow execution** - GitHub workflow runs on the main branch with GitLab job data
49+
50+
## GitHub Actions Workflow
51+
52+
The system triggers GitHub workflows using the `repository_dispatch` event type `gitlab-job-finished`. You need to create a workflow in your target repository that listens for these events.
53+
54+
### Creating a Workflow
55+
56+
Create a file like `.github/workflows/gitlab-trigger.yml` in your target repository:
57+
58+
```yaml
59+
name: GitLab Job Triggered Workflow
60+
61+
on:
62+
repository_dispatch:
63+
types: [gitlab-job-finished]
64+
65+
jobs:
66+
gitlab-triggered-job:
67+
runs-on: ubuntu-latest
68+
69+
steps:
70+
- name: Checkout code
71+
uses: actions/checkout@v4
72+
with:
73+
ref: main # Always use main branch
74+
75+
- name: Display GitLab job information
76+
run: |
77+
echo "🚀 GitLab job has finished!"
78+
echo "📊 Job Status: ${{ github.event.client_payload.job_status }}"
79+
echo "🔧 Job Name: ${{ github.event.client_payload.job_name }}"
80+
echo "🆔 Job ID: ${{ github.event.client_payload.job_id }}"
81+
echo "🔗 Job URL: ${{ github.event.client_payload.job_url }}"
82+
echo "📁 Project: ${{ github.event.client_payload.project_name }}"
83+
echo "🌿 Branch: ${{ github.event.client_payload.ref }}"
84+
echo "📝 Commit SHA: ${{ github.event.client_payload.commit_sha }}"
85+
86+
- name: Custom actions based on GitLab job status
87+
run: |
88+
JOB_STATUS="${{ github.event.client_payload.job_status }}"
89+
JOB_NAME="${{ github.event.client_payload.job_name }}"
90+
ALLOW_FAILURE="${{ github.event.client_payload.allow_failure }}"
91+
92+
if [[ "$JOB_STATUS" == "success" ]]; then
93+
echo "✅ GitLab job succeeded - running success actions"
94+
# Add your success-specific commands here
95+
elif [[ "$JOB_STATUS" == "failed" ]]; then
96+
if [[ "$ALLOW_FAILURE" == "true" ]]; then
97+
echo "⚠️ GitLab job failed but failure is allowed"
98+
else
99+
echo "❌ GitLab job failed - running failure actions"
100+
# Add your failure-specific commands here
101+
fi
102+
fi
103+
```
104+
105+
### Workflow Event Structure
106+
107+
The triggered workflow receives detailed information about the GitLab job:
108+
109+
```yaml
110+
name: GitLab Job Triggered Workflow
111+
112+
on:
113+
repository_dispatch:
114+
types: [gitlab-job-finished]
115+
116+
jobs:
117+
my-job:
118+
runs-on: ubuntu-latest
119+
steps:
120+
- name: Checkout code
121+
uses: actions/checkout@v4
122+
with:
123+
ref: main # Always uses main branch
124+
125+
- name: Access GitLab job data
126+
run: |
127+
echo "Job Status: ${{ github.event.client_payload.job_status }}"
128+
echo "Job Name: ${{ github.event.client_payload.job_name }}"
129+
echo "Project: ${{ github.event.client_payload.project_name }}"
130+
echo "Commit SHA: ${{ github.event.client_payload.commit_sha }}"
131+
# ... and more fields
132+
```
133+
134+
### Available Data Fields
135+
136+
The `client_payload` contains the following GitLab job information:
137+
138+
| Field | Description | Example |
139+
|-------|-------------|---------|
140+
| `job_status` | Current job status | `"success"`, `"failed"`, `"canceled"` |
141+
| `job_name` | Name of the GitLab job | `"test"`, `"build"`, `"deploy"` |
142+
| `job_id` | GitLab job ID | `12345` |
143+
| `job_url` | Link to GitLab job | `"https://gitlab.com/project/-/jobs/12345"` |
144+
| `project_name` | GitLab project name | `"my-awesome-project"` |
145+
| `project_path` | Full project path | `"myorg/my-awesome-project"` |
146+
| `ref` | Git reference (branch/tag) | `"main"`, `"feature/new-feature"` |
147+
| `commit_sha` | Git commit SHA | `"abc123def456..."` |
148+
| `pipeline_id` | GitLab pipeline ID | `67890` |
149+
| `pipeline_url` | Link to GitLab pipeline | `"https://gitlab.com/project/-/pipelines/67890"` |
150+
| `created_at` | Job creation timestamp | `"2023-01-01T12:00:00Z"` |
151+
| `started_at` | Job start timestamp | `"2023-01-01T12:01:00Z"` |
152+
| `finished_at` | Job completion timestamp | `"2023-01-01T12:05:00Z"` |
153+
| `allow_failure` | Whether job failure is allowed | `true`, `false` |
154+
| `gitlab_project_id` | GitLab project ID | `42` |
155+
156+
## Use Cases
157+
158+
### 1. Documentation Updates
159+
Trigger documentation builds when GitLab tests pass:
160+
161+
```yaml
162+
- name: Update documentation
163+
if: github.event.client_payload.job_status == 'success'
164+
run: |
165+
# Build and deploy documentation
166+
npm run build:docs
167+
npm run deploy:docs
168+
```
169+
170+
### 2. Deployment Workflows
171+
Deploy applications when GitLab builds succeed:
172+
173+
```yaml
174+
- name: Deploy to production
175+
if: |
176+
github.event.client_payload.job_status == 'success' &&
177+
github.event.client_payload.job_name == 'build-production' &&
178+
github.event.client_payload.ref == 'main'
179+
run: |
180+
# Deploy to production environment
181+
./deploy.sh production
182+
```
183+
184+
### 3. Notifications and Alerts
185+
Send notifications based on GitLab job results:
186+
187+
```yaml
188+
- name: Send Slack notification
189+
if: github.event.client_payload.job_status == 'failed'
190+
uses: 8398a7/action-slack@v3
191+
with:
192+
status: failure
193+
text: |
194+
GitLab job failed: ${{ github.event.client_payload.job_name }}
195+
Project: ${{ github.event.client_payload.project_name }}
196+
Job URL: ${{ github.event.client_payload.job_url }}
197+
```
198+
199+
### 4. Cross-Repository Coordination
200+
Trigger related workflows in multiple repositories:
201+
202+
```yaml
203+
- name: Trigger dependent repository builds
204+
if: |
205+
github.event.client_payload.job_status == 'success' &&
206+
github.event.client_payload.job_name == 'integration-tests'
207+
run: |
208+
# Trigger builds in dependent repositories
209+
gh workflow run deploy.yml --repo myorg/frontend
210+
gh workflow run update.yml --repo myorg/mobile-app
211+
```
212+
213+
## Security Considerations
214+
215+
1. **GitHub App Permissions**: The CI Bridge GitHub App must have access to target repositories
216+
2. **Repository Access**: Target repositories must have the GitHub App installed
217+
3. **Workflow Permissions**: Ensure triggered workflows have appropriate permissions
218+
4. **Sensitive Data**: Avoid passing sensitive GitLab data to GitHub workflows
219+
220+
## Troubleshooting
221+
222+
### Common Issues
223+
224+
1. **Workflows not triggering**
225+
- Check that `ENABLE_GITLAB_TO_GITHUB_TRIGGERING=true`
226+
- Ensure the target repository has a workflow listening for `repository_dispatch` events with type `gitlab-job-finished`
227+
- Verify GitHub App has access to the repository
228+
- Check CI Bridge logs for error messages
229+
230+
2. **"No GitLab workflow triggers found" message**
231+
- Verify your workflow file contains both `repository_dispatch` and `gitlab-job-finished` in the content
232+
- Ensure the workflow file is committed to the repository
233+
- Check the workflow file is in `.github/workflows/` directory
234+
235+
3. **Workflow receives no data**
236+
- Verify workflow listens for `repository_dispatch` with type `gitlab-job-finished`
237+
- Check that GitLab job completed with a configured trigger status
238+
- Ensure the repository is where GitLab CI status is being posted
239+
240+
### Debug Logging
241+
242+
Enable debug logging to troubleshoot issues:
243+
244+
```bash
245+
OVERRIDE_LOGGING=DEBUG
246+
```
247+
248+
Look for log messages like:
249+
- `"GitLab to GitHub triggering is enabled, checking repository for workflows"`
250+
- `"Checking repository owner/repo for GitLab workflow triggers"`
251+
- `"Found GitLab workflow trigger in owner/repo: .github/workflows/example.yml"`
252+
- `"Repository owner/repo has GitLab workflow triggers, proceeding"`
253+
- `"Successfully triggered GitHub workflow (GitLab job: job-name, status: success)"`
254+
255+
### Testing
256+
257+
You can manually test the workflow triggering using the GitHub API:
258+
259+
```bash
260+
curl -X POST \
261+
-H "Authorization: token YOUR_GITHUB_TOKEN" \
262+
-H "Accept: application/vnd.github.v3+json" \
263+
https://api.github.com/repos/OWNER/REPO/dispatches \
264+
-d '{
265+
"event_type": "gitlab-job-finished",
266+
"client_payload": {
267+
"job_status": "success",
268+
"job_name": "test-job",
269+
"project_name": "test-project",
270+
"ref": "main",
271+
"commit_sha": "abc123",
272+
"pipeline_url": "https://gitlab.com/project/pipeline"
273+
}
274+
}'
275+
```
276+
277+
## Limitations
278+
279+
- **Main branch only**: Workflows always run on the main branch regardless of GitLab branch
280+
- **Repository dispatch limits**: GitHub has rate limits on repository dispatch events
281+
- **GitHub App scope**: Only repositories with the GitHub App installed can be triggered
282+
- **Workflow detection**: Uses simple text search for `repository_dispatch` and `gitlab-job-finished` in workflow files
283+
- **Configuration updates**: Require CI Bridge restart to take effect

‎src/ci_relay/config.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ class Config(BaseSettings):
3838

3939
GITLAB_IGNORED_JOB_PATTERNS: list[str] = []
4040

41+
# GitLab to GitHub workflow triggering configuration
42+
ENABLE_GITLAB_TO_GITHUB_TRIGGERING: bool = False
43+
GITLAB_TO_GITHUB_TRIGGER_ON_STATUS: list[str] = ["success", "failed"] # Which job statuses trigger workflows
44+
4145
def print_config(self):
4246
"""Print configuration values with sensitive attributes masked"""
4347
sensitive_attrs = {

0 commit comments

Comments
 (0)