Skip to content

Commit 0c005f3

Browse files
kujovkujov
authored
Merge pull request #2 from kujov/lfs
Add Git LFS support
2 parents b79a5a3 + 0331860 commit 0c005f3

3 files changed

Lines changed: 126 additions & 45 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 kujov
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 all
13+
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 THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 97 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,133 @@
11
<div align="center">
2-
<img src="assets/gitlab-sync.png" width="40%" alt="GitLab Sync">
2+
<img src="assets/gitlab-sync.png" width="35%" alt="GitLab Sync">
3+
<h1>GitLab Sync</h1>
4+
<p>A GitHub Action for automatically mirroring your GitHub repository to GitLab.</p>
5+
6+
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-GitLab%20Sync-blue?logo=github)](https://github.com/marketplace/actions/sync-to-gitlab)
7+
[![Latest Release](https://img.shields.io/github/v/release/kujov/gitlab-sync)](https://github.com/kujov/gitlab-sync/releases)
8+
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
39
</div>
410

5-
<div align="center">
6-
<h1>GitLab Sync - GitHub Action</h1>
11+
---
712

8-
<p><strong>GitLab Sync</strong> is a GitHub Action designed for seamless and automated synchronization of code from a GitHub repository to a GitLab repository.</p>
9-
</div>
13+
## Overview
1014

11-
## Motivation
15+
GitLab Sync pushes your repository to GitLab on every push. It handles the full checkout, validation, and push — including full git history and optional Git LFS objects.
1216

13-
This GitHub Action provides a free, simple, and reliable method for mirroring repositories from GitHub to GitLab. It's designed to be straightforward to implement and operate effectively.
17+
**Features:**
18+
- Full history sync (`fetch-depth: 0`)
19+
- Optional Git LFS support
20+
- Optional force push
21+
- Clear error messages for misconfigured secrets
1422

15-
## How to Use
23+
---
1624

17-
Integrate GitLab Sync into your workflow by following these steps:
25+
## Quick Start
1826

19-
### 1. Configure GitHub Secrets
27+
### 1. Add Secrets
2028

21-
Before using the action, you must add the following secrets to your GitHub repository (`Settings > Secrets and variables > Actions`):
29+
In your GitHub repository go to `Settings > Secrets and variables > Actions` and add:
2230

23-
- `GITLAB_URL`: The HTTPS URL of your target GitLab repository (e.g., `https://gitlab.com/yourusername/yourrepo.git`).
24-
- `USERNAME`: Your GitLab username.
25-
- `GITLAB_PAT`: Your GitLab Personal Access Token. Ensure this token has `write_repository` scope to push to the repository.
31+
| Secret | Description |
32+
|--------|-------------|
33+
| `GITLAB_URL` | Full HTTPS URL of your GitLab repo — e.g. `https://gitlab.com/user/repo.git` |
34+
| `USERNAME` | Your GitLab username |
35+
| `GITLAB_PAT` | A GitLab Personal Access Token with `write_repository` scope |
2636

27-
### 2. Create a Workflow File
37+
> **Tip:** Generate a GitLab PAT at `User Settings > Access Tokens`. Minimum required scope is `write_repository`.
2838
29-
Add a workflow file to your GitHub repository (e.g., `.github/workflows/sync-to-gitlab.yml`):
39+
### 2. Add a Workflow
40+
41+
Create `.github/workflows/sync-to-gitlab.yml` in your repository:
3042

3143
```yaml
32-
name: Sync Repository to GitLab
44+
name: Sync to GitLab
3345

3446
on:
35-
push
47+
push:
48+
branches: [main]
3649

3750
jobs:
3851
sync:
3952
runs-on: ubuntu-latest
4053
steps:
41-
- name: Sync to GitLab
42-
uses: keninkujovic/gitlab-sync@2.1.3
43-
with:
44-
gitlab_url: ${{ secrets.GITLAB_URL }}
45-
username: ${{ secrets.USERNAME }}
46-
gitlab_pat: ${{ secrets.GITLAB_PAT }}
54+
- name: Sync to GitLab
55+
uses: kujov/gitlab-sync@main
56+
with:
57+
gitlab_url: ${{ secrets.GITLAB_URL }}
58+
username: ${{ secrets.USERNAME }}
59+
gitlab_pat: ${{ secrets.GITLAB_PAT }}
4760
```
4861
49-
**Important Considerations:**
62+
That's it, every push to `main` will mirror to your GitLab repository.
63+
64+
---
5065

51-
- **Branch Specificity**: It's highly recommended to specify which branches trigger the sync (e.g., `main`, `master`) in the `on: push: branches:` section of your workflow to avoid unintended syncs.
52-
- **`actions/checkout`**: Always include `actions/checkout@vX` (preferably the latest version) before this action to ensure your repository's code is available.
53-
- **`fetch-depth: 0`**: Using `fetch-depth: 0` with `actions/checkout` is crucial for ensuring the entire Git history is fetched. This is often necessary for a clean and successful synchronization, especially if you need to sync tags or ensure branch histories are complete.
66+
## Configuration
5467

55-
### 3. Push Changes to GitHub
68+
### Inputs
5669

57-
Once the workflow is configured, any push to the specified branches in your GitHub repository will automatically trigger the synchronization process to your GitLab repository.
70+
| Input | Description | Required | Default |
71+
|-------|-------------|----------|---------|
72+
| `gitlab_url` | HTTPS URL of the target GitLab repository | Yes | — |
73+
| `username` | Your GitLab username | Yes | — |
74+
| `gitlab_pat` | GitLab PAT with `write_repository` scope | Yes | — |
75+
| `force_push` | Force push to GitLab, overwriting remote history | No | `false` |
76+
| `git_lfs` | Also push Git LFS objects to GitLab | No | `false` |
77+
78+
### Sync all branches
79+
80+
Change the trigger to sync on pushes to any branch:
81+
82+
```yaml
83+
on:
84+
push
85+
```
86+
87+
### Force push
88+
89+
Use with caution — this overwrites the GitLab repository history:
90+
91+
```yaml
92+
- uses: kujov/gitlab-sync@main
93+
with:
94+
gitlab_url: ${{ secrets.GITLAB_URL }}
95+
username: ${{ secrets.USERNAME }}
96+
gitlab_pat: ${{ secrets.GITLAB_PAT }}
97+
force_push: true
98+
```
99+
100+
### Git LFS
101+
102+
To also sync LFS objects, enable `git_lfs`. Make sure LFS is enabled on your GitLab repository before using this.
103+
104+
```yaml
105+
- uses: kujov/gitlab-sync@main
106+
with:
107+
gitlab_url: ${{ secrets.GITLAB_URL }}
108+
username: ${{ secrets.USERNAME }}
109+
gitlab_pat: ${{ secrets.GITLAB_PAT }}
110+
git_lfs: true
111+
```
58112

59-
## Action Inputs
113+
---
60114

61-
The action supports the following input parameters:
115+
## Troubleshooting
62116

63-
| Parameter | Description | Required | Default |
64-
|--------------|------------------------------------------------------------------------------------------------------------|----------|---------|
65-
| `gitlab_url` | The HTTPS URL of the target GitLab repository (e.g., `https://gitlab.com/yourusername/yourrepo.git`). | Yes | N/A |
66-
| `username` | Your GitLab username. | Yes | N/A |
67-
| `gitlab_pat` | Your GitLab Personal Access Token. Must have permissions to write (`write_repository` scope) to the target repository. | Yes | N/A |
68-
| `force_push` | Whether to force push to GitLab. If `true`, overwrites the destination branch. Use with caution. | No | `false` |
117+
**Authentication failed**
118+
Verify `GITLAB_PAT` is valid and has `write_repository` scope. Tokens expire — check `User Settings > Access Tokens` on GitLab.
69119

70-
## Feedback and Contributions
120+
**Push rejected (non-fast-forward)**
121+
The GitLab repository has commits not in GitHub. Use `force_push: true` to overwrite, or manually reconcile histories.
71122

72-
Feedback, bug reports, and contributions are highly valued and welcome! Please feel free to:
123+
**LFS objects not syncing**
124+
Ensure Git LFS is enabled on the GitLab repository (`Settings > General > Visibility > Git LFS`) and that `git_lfs: true` is set.
73125

74-
- Open an issue for any bugs or feature requests.
75-
- Submit a pull request with improvements.
126+
**Invalid `gitlab_url` format**
127+
The URL must be a full HTTPS URL ending in `.git`, e.g. `https://gitlab.com/user/repo.git`.
76128

77-
If you find this action useful, please consider starring the repository!
129+
---
78130

79-
## Disclaimer
131+
## Contributing
80132

81-
This GitHub Action was developed to fulfill a specific synchronization need. While it has been tested, users should thoroughly verify its functionality and implications in their own environments before deployment to critical repositories. Use this action at your own discretion. The maintainers are not responsible for any data loss or unintended consequences.
133+
Issues and pull requests are welcome. If this action is useful to you, consider starring the repository.

‎action.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ inputs:
1717
description: 'Whether to force push to GitLab. Defaults to false.'
1818
required: false
1919
default: 'false'
20+
git_lfs:
21+
description: 'Whether to sync Git LFS objects to GitLab. Defaults to false.'
22+
required: false
23+
default: 'false'
2024
runs:
2125
using: 'composite'
2226
steps:
@@ -25,6 +29,7 @@ runs:
2529
with:
2630
fetch-depth: 0
2731
persist-credentials: false
32+
lfs: ${{ inputs.git_lfs }}
2833
- name: Validate inputs
2934
run: |
3035
errors=()
@@ -62,6 +67,9 @@ runs:
6267
gitlab_repo_url_with_credentials="https://${{ inputs.username }}:${{ inputs.gitlab_pat }}@${gitlab_repo_url}"
6368
git remote add gitlab "$gitlab_repo_url_with_credentials"
6469
branch_name=$(echo $GITHUB_REF | sed 's/refs\/heads\///')
70+
if [[ "${{ inputs.git_lfs }}" == "true" ]]; then
71+
git lfs push --all gitlab
72+
fi
6573
push_command="git push gitlab $branch_name"
6674
if [[ "${{ inputs.force_push }}" == "true" ]]; then
6775
push_command="$push_command --force"

0 commit comments

Comments
 (0)