@opensaucedhub/git-sync-action v1.1.4

GitHub GitLab Sync Action

A powerful GitHub Action that provides bi-directional synchronization between GitHub and GitLab repositories. This action helps maintain consistency across platforms by syncing branches, pull requests, issues, releases, and tags.

Features

• 🔄 Bi-directional Synchronization: Sync from GitHub to GitLab and vice versa
• 🌳 Branch Synchronization: Keep branches in sync across platforms
• 🔀 Pull Request/Merge Request Sync: Synchronize pull requests with corresponding merge requests
• 📝 Issue Tracking: Keep issues and their comments in sync
• 🏷️ Release Management: Sync releases and tags across platforms
• ⚙️ Configurable: Extensive configuration options for fine-grained control
• 🔒 Protected Resources: Support for protected branches and resources
• 🏷️ Label Management: Automatic labeling of synced resources

Setup

1. Create a .github/workflows/sync.yml file in your repository:

name: Sync to GitLab
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, closed, reopened]
  issues:
    types: [opened, closed, reopened]
  release:
    types: [published]
  schedule:
    - cron: '0 */6 * * *'
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Sync with GitLab
        uses: OpenSaucedHub/git-sync-action@v1.1.4
        with:
          CONFIG_PATH: .github/sync-config.yml # optional, defaults to .github/sync-config.yml
          GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }} # optional, unless you want to sync to GitLab
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} # Optional, defaults to GITHUB_TOKEN

2. Create a .github/sync-config.yml file with your sync configuration:

#sync-config.yml
# When you have gitlab.sync.[entity].enabled: true, it means those entities will be synced FROM GitHub TO GitLab
gitlab:
  enabled: true
  username: # Optional, defaults to GitHub repo owner

# When you have github.sync.[entity].enabled: true, it means those entities will be synced FROM GitLab TO GitHub
github:
  enabled: true

!WARNING

• If no config is provided, everything defaults to true, autoMerge is false, Labels are set as specified in the default config and repo name and username default to GitHub repository owner/repo. See Accepted Configuration
• In case of a partial config (missing fields), the defaults are used. (you MUST strictly set elements to false if you don't want them to sync). See Accepted Configuration

3. Set up required secrets in your GitHub repository:

• GITLAB_TOKEN: A GitLab personal access token with API access
• GH_TOKEN: A GitHub personal access token (optional, defaults to GITHUB_TOKEN)

Accepted Configuration

#sync-config.yml
# When you have gitlab.sync.[entity].enabled: true, it means those entities will be synced FROM GitHub TO GitLab
gitlab:
  enabled: true
  url: 'gitlab.com' # Optional, defaults to gitlab.com
  username: # Optional, defaults to GitHub repo owner
  repo: # Optional, defaults to GitHub repo name
  sync:
    branches:
      enabled: true
      protected: true
      pattern: '*'

    pullRequests:
      enabled: true
      autoMerge: false
      labels: ['synced-from-github']

    issues:
      enabled: true
      syncComments: true
      labels: ['synced-from-github']

    releases:
      enabled: true

    tags:
      enabled: true # automatically enabled if releases = true

# When you have github.sync.[entity].enabled: true, it means those entities will be synced FROM GitLab TO GitHub
github:
  enabled: true
  username: # Optional, defaults to GitHub username
  repo: # Optional, defaults to GitHub repo name
  sync:
    branches:
      enabled: true
      protected: true
      pattern: '*'

    pullRequests:
      enabled: true
      autoMerge: false
      labels: ['synced-from-gitlab']

    issues:
      enabled: true
      syncComments: true
      labels: ['synced-from-gitlab']

    releases:
      enabled: true

    tags:
      enabled: true # automatically enabled if releases = true

Configuration Options

GitLab Configuration (gitlab)

GitHub Configuration (github)

Sync Configuration

Branches

Pull Requests

Issues

Releases and Tags

Token Permissions

GitLab Token

The GitLab token needs the following permissions:

• api - Full API access
• read_repository - Read repository
• write_repository - Write repository

GitHub Token

The GitHub token needs the following permissions:

• repo - Full repository access
• workflow - Workflow access

Contributing 🤝

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Security 🔐

• The action uses token-based authentication for secure operations
• Tokens are never exposed in logs or outputs
• Protected branch settings are respected
• All API calls use HTTPS

Support 💬

For support, please:

1. Check the Issues page
2. Create a new issue if your problem isn't already listed
3. Provide as much context as possible

Acknowledgments 🙏

• Inspired by Sync to GitLab action, just felt awful having to sync PRs/MRs, branches, releases and issues manually.
• Built with TypeScript and Bun
• Uses the official GitLab API and GitHub Actions toolkit