search

swellaby / vsts-mirror-git-repository

A straightforward utility to mirror one Git repository to another location
MIT License
25 stars 15 forks source link
azure-devops azure-pipelines git-mirror mirror-git

readme

Mirror Git Repository

Mirror Git Repository Logo

Version Badge Installs Badge Rating Badge License Badge

Linux CI Badge Mac CI Badge Windows CI Badge

Test Results Badge Coverage Badge Sonar Quality GateBadge

Overview

The purpose of the Mirror Git Repository task is to facilitate the copying of changes of one Git Repository to another.

Task Configuration

The process of mirroring a Git repository consists of two basic steps:

  1. Clone a source repository
  2. Push that repository to another location

Both of these steps may require additional access in order to read or write to the relevant repositories. In order to provide that access, Personal Access Tokens (PATs) are used to grant the build agent the access it needs to perform these actions.

Source Git Repository The HTTPS endpoint of the Git Repository you want to copy from. This field is required. The default value of this field $(Build.Repository.Uri) will populate the field with the source repository the build is linked to.

Source Repository - Personal Access Token A Personal Access Token (PAT) that grants read access to the repository in the Source Git Repository field. This field is optional. If the Git repository in the Source Git Repository field is public, this field does not need to be populated. Check out the Best Practices section below for more details on managing PAT Tokens securely.

Source Repository - Clone Directory Name The name of the directory to clone the Source Repository into. This field is optional. This is the same argument used by git clone with the same default behavior.

Verify SSL Certificate on Source Repository Verifying SSL certificates is a default behavior of Git. Disabling this option will turn off SSL certificate validation as a part of the Source Repository cloning process. If you are using a Git server with a Self-Signing certificate, you may need to uncheck this option.

Destination Git Repository The HTTPS endpoint of the Git Repository you want to copy to. This field is required.

Destination Repository - Personal Access Token A Personal Access Token (PAT) that grants write access to the repository in the Destination Git Repository field. This field is required. Check out the Best Practices section below for more details on managing PAT Tokens securely.

Verify SSL Certificate on Destination Repository Verifiying SSL certificates is a default behavior of Git. Unchecking this option will turn off SSL certificate validation as a part of the Destination Repository push process. If you are using a Git server with a Self-Signing certificate, you will likely need to uncheck this option.

YAML Pipeline

When using the Mirror Git Repository task in a YAML-based pipeline, the task configuration uses the following input names:

You may omit the access token inputs (sourceGitRepositoryPersonalAccessToken and destinationGitRepositoryPersonalAccessToken) if you do not need to provide a token for the respective source/destination repo. You may omit the source repository clone directory name (sourceGitRepositoryCloneDirectoryName) if you do not need to override the default behavior of git clone. You may also omit the SSL verification inputs (sourceVerifySSLCertificate and destinationVerifySSLCertificate) if you want to include SSL verification (the only time you have to provide those inputs is if you need to set the value to false)

Here's an example snippet of what a YAML configuration would like like for the Mirror Git Repository Task (using a secure variable for the destination token)

- task: swellaby.mirror-git-repository.mirror-git-repository-vsts-task.mirror-git-repository-vsts-task@1
  displayName: 'Mirror Git Repository'
  inputs:
    sourceGitRepositoryUri: 'https://github.com/swellaby/vsts-mirror-git-repository.git'
    sourceVerifySSLCertificate: false
    destinationGitRepositoryUri: 'https://dev.azure.com/swellaby/OpenSource/_git/mirror2'
    destinationGitRepositoryPersonalAccessToken: '$(destVar)'


Best Practices

Generating Personal Access Tokens

In order to use this task, you will need to create Personal Access Tokens to the appropriate repositories. Below are some links on how to achieve this:

Securing Personal Access Tokens during the build

While you have the ability to enter the PAT tokens into the task in plain-text, it is best practice to mask these tokens so that your repositories remain secure. Azure Pipelines supports the ability to manage and inject secure variables at build time. There are currently two ways to achieve this in Azure Pipelines:

  1. Use a Secret Process Variable directly on the build definition
  2. Use a Secret variable from a Variable Group linked to the build definition

By using secret variables in your build task, your PAT tokens will be masked in any build output.


Frequently Asked Questions

Can I use this task to mirror to other Git Source Control Platforms?

    tl;dr Yes, it should work with any Git repository.

This task is built solely on top of Git commands. As long as the build agent has read access to the source repository and write access to the destination repository, the endpoints are not specific to any Git Source Control Platform.

Why should I choose this task over one of the other Git mirroring tasks available on the marketplace?

    tl;dr It is the only mirroring task that currently works without needing to modify the Azure Pipelines Build Agent Docker Image to include Powershell

As of this task being published, the other tasks on the Marketplace that perform similar actions are written with Powershell scripts and do not work out-of-the-box with the VSTS Build Agent Docker Image. To fill this gap, we decided to develop our own task that is written in NodeJS. Note that this task does require the build agent to have NodeJS installed.

Does the task create a Destination Git Repository if it doesnt exist?

    tl;dr No.

The Destination Git Repository must exist before it can be pushed to.

But what is the task really doing under the hood?

    tl;dr Check out our Github repo

The task is using basic git commands to mirror the repository. If you would like more details on what commands are being ran, you can find the details at this Github reference page: Mirror a Repository in Another Location

If you would like to see the code directly, feel free to browse our Github repo

Help! The task seems to hang and won't continue!

    tl;dr Check your variables, check your access.

It is highly likely that the cause of a hanging issue is that the build agent is not able to access the Git Repository URL you provided. If you were executing the Git commands manually, this would be seen by Git prompting for credentials. This prompt will not show within the build output.

Some things to check if you are experiencing this issue:

  1. Check that both of the Git Repository URLs you provided are correct.
  2. You may need to include a Personal Access Token to give the build agent access to the Git Repository.

    Note: The task does not give the build agent read or write access to your Azure DevOps repositories by default.

I have other questions and/or need to report an issue

Please report any issues to our Github Issues page, quick links below for reference:

Feel free to leave a question or a comment on our Github repo or on the Extension in the Marketplace.


Contributing

Contributions are welcomed and encouraged! More details can be found in the Contribution Guidelines.

Generator

Want to make your own Azure Pipelines Extension or Task? This task was initially created by this swell generator!


Icon Credits

The Git logo is the orginal property of Jason Long and is used/modified under the Creative Commons Attribution 3.0 Unported License. Thank you Jason for allowing us to modify your logo!


Back to top