Utilities for managing GitLab-to-GitHub push mirror configurations.

https://gitlab.com/brlin/gitlab2github-push-mirror-utils

1. Download the product's release archive from the Releases page.
2. Extract the downloaded archive.

Batch rotate credentials of GitLab push mirroring settings for all repositories in a namespace that is configured to push to GitHub.

The following prerequisites must be met in order to use this utility:

• The host running the utility must have Internet access.
• The host running the utility must have the following software installed and its commands to be available in your command search PATHs:
  • curl
    For interacting with GitLab and GitHub's API.
  • grep
    sed
    For parsing the curl command's output.
  • jq
    For parsing the JSON response of GitLab and GitHub's API.

1. Set the environment variables documented in the Environment variables that can change the utility's behaviors section.
2. Run the rotate-gitlab2github-push-mirror-credentials.sh script.
3. Provide the prompted values documented in the Prompted variables that can change the utility's behaviors section.

The following environment variables can be used to change the utility's behaviors according to your needs:

GitLab namespace to replace push mirroring settings, currently namespaces including subgroup is not supported.

Default value: Value of the USER environment variable(e.g. Your username).

GitHub namespace to configure push mirroring to.

Default value: Value of the GITLAB_NAMESPACE environment variable.

The GitLab REST API v4-compatible endpoint to use.

Default value: https://gitlab.com/api/v4

The GitHub API v2022-11-28-compatible endpoint to use.

Default value: https://api.github.com

The number of entries per page to request when pagination is required.

Default value: 100

The following variables can be used to change the utility's behaviors, they are prompted when running the utility due to their sensitive nature:

The personal access token with access to the GitLab namespace. REQUIRED.

Required fine-grained personal access token resource permissions:

• User:
  • Groups:
    • Namespace
      • Read: For querying available projects in the namespace.
• Group and project:
  • Project Features:
    • Remote Mirror:
      • Create: For creating a new repository push mirroring configuration.
      • Delete: For removing the existing repository push mirroring configuration.
      • Read: For checking the existing repository push mirroring configuration.

Default value: (none)

The personal access token with access to the GitHub namespace. This is used to:

• Mitigate GitHub rate limiting.
• Authenticate the user during the GitLab push mirroring process.

REQUIRED.

It should have the following GitHub fine-grained permissions:

• Repository permissions > Read access to metadata
• Repository permissions > Read and write access to:
  • Contents: To allow GitLab to push non-GitHub Actions workflow related content to the mirrored repository.
  • Workflows: To allow GitLab to push GitHub Actions workflow related content to the mirrored repository.

Default value: (none)

The following documents the logic of this utility in operation:

1. A list of all GitLab projects in a namespace is queried via GitLab's REST API.
2. For each GitLab project:
   1. Determine the URL of the corresponding GitHub project(repository).
   2. Check whether the GitHub project actually exists.
   3. If the project exists in the specified GitHub namespace, check whether the GitLab project has an repository mirroring configuration against it.
   4. If the repository mirroring configuration does not exist, skipping this project as we aren't sure the GitLab project has all the commits from GitHub yet.
   5. If the repository mirroring configuration exists, remove the configuration.
   6. Create a new repository mirroring configuration with the updated GitHub PAT.

The product does not support GitLab subgroups, they will be skipped.

The following materials are referenced during the development of this project:

• REST API | GitLab
  Explains:
  • The basic usage of the GitLab REST API.
  • How to do pagination.
• REST API authentication | GitLab
  Explains how to authenticate the user when using the GitLab REST API.
• Store and reuse values using variables | Postman Learning Center
  Explains how to define secret
• curl(1) manpage
  Explains the usage of the --header option.
• Escape sequences - IBM Documentation
  Explains the escape sequence of the backspace control character.
• List projects | Groups API | GitLab
  Explains how to query all projects in a user-specified group.
• List a user’s projects | Projects API | GitLab
  Explains how to query all projects in a user-specified user.
• Getting started with the REST API - GitHub Docs
  Explains the basic usage of the GitHub REST API.
• Authenticating to the REST API - GitHub Docs
  Explains how to do authentication using the GitHub REST API.
• Get a repository - REST API endpoints for repositories - GitHub Docs
  Explains how to query the information of a certain repository using the GitHub REST API.
• Tutorial | jq
  Explains the basic usage of jq.
• Personal access token scopes | Personal access tokens | GitLab Docs
  Explains possible scopes(permissions) a GitLab PAT may have.
• Here Strings | Redirections (Bash Reference Manual)
  Explains why loading the content of a empty here string using mapfile will not result in an empty array.

Unless otherwise noted(individual file's header/REUSE.toml), this product is licensed under the 3.0 version of the GNU Affero General Public License license, or any of its recent versions you would prefer.

This work complies to the REUSE Specification, refer to the REUSE - Make licensing easy for everyone website for info regarding the licensing of this product.