Skip to main content

Repository Mirror

It is often desirable to mirror repositories between OneDev and other hosting services. For instance you may want to push changes to a copy at GitHub for public access, or want to pull back any changes contributed by others at GitHub.

OneDev 7.1 made this task trivial with the new repository sync steps. Let’s see how to achieve this.

Preparation​

First of all, start OneDev by running below command:

$ docker run -t --rm -v /var/run/docker.sock:/var/run/docker.sock -v $(pwd)/onedev:/opt/onedev -p 6610:6610 -p 6611:6611 1dev/server

Point your browser to localhost:6610 to setup OneDev, and create a test project.

Then create an empty repository at GitHub side to be used as mirror of our test repository, assume the url is: https://github.com/youraccount/test

Push Changes to Mirror​

Now we configure OneDev to push changes to GitHub mirror as long as there is a change in branch or tag:

  1. Login to your GitHub account and generate a personal access token able to push to the mirror repository

  2. At OneDev side, create a job secret in the test project and use access token above as its value:

  3. Define a build spec job named Push to GitHub and add a step of type Repository Sync / Push to Remote. Set Remote URL to the HTTPS clone URL of your GitHub repository and User Name to your GitHub account name. For Password or Access Token for Remote Repository, choose the job secret defined above. Leave Force disabled for normal fast-forward updates:

    Push to Remote settings

  4. Add triggers to run job automatically when branch is updated or tag is created:

Now save the build spec and the job will run automatically to push changes to GitHub mirror. Check at GitHub side, and you will see it contains newly created file .onedev-buildspec.yml. Experiment with other changes such as creating new branch/tag to see the result.

The push step sends the build's commit to the same branch or tag on GitHub; it does not copy every existing ref in a single run. Restrict the trigger and the secret's authorization to the branches you intend to mirror. For example, begin with a Branch update trigger for main and secret authorization on branch "main", then verify the resulting commit on GitHub before expanding the configuration.

Pull Changes from Mirror​

Our GitHub mirror may accept pull requests from contributors, so let’s set up OneDev to pull changes from it:

  1. Continue to edit build spec above, add a job say Pull from GitHub, and add a step of type Repository Sync / Pull from Remote like below:

    Use the same Remote URL, User Name, and Password or Access Token for Remote Repository as the push step. Leave Target Project empty to pull into the current OneDev project. Access Token for Target Project is a separate OneDev credential; it can be left empty when pulling into the current project from a build commit reachable from its default branch.

    Set Refs to refs/heads/main to test a single branch, or refs/heads/* refs/tags/* to pull all branches and tags. Leave Force disabled unless you intend to overwrite diverging refs.

    Pull from Remote destination and refs

    The remote password/access token can be left empty if the GitHub repository is publicly readable. A private repository requires authentication.

    Before adding a schedule, commit a test file on GitHub and click the run button beside Pull from GitHub in the build spec. Confirm that the job succeeds and the file appears on the corresponding branch in OneDev:

    Successful pull job

  2. Add a job trigger of cron type to run job on scheduled time, for instance, on 1:00AM every night:

  3. If your OneDev instance can be accessed publicly, you can configure GitHub to trigger this pull job upon mirror changes. This can be done by creating a webhook at GitHub side like below:

    The payload url is defined as:

    https://onedev.example.com/~api/trigger-job?project=test&job=Pull%20from%20GitHub&branch=main&access-token=<OneDev access token>

    Here onedev.example.com is dns name accessing your OneDev instance. Param job is url encoded as it contains space. <OneDev access token> should be replaced by an access token with permission to run the job. Param branch tells OneDev where to load the build spec to find specified job.

    For production use, it is important to use https protocol for payload url to avoid leaking of access token.

    Save the webhook and OneDev should be pulling from GitHub mirror whenever it is changed.

Conclusion​

We’ve completed setup of a two-way sync of OneDev repository and its GitHub mirror. Since it is just an ordinary CI job, we can subscribe certain build query to be notified of sync failures, check build log to investigate sync failures, or even configure job resource setting to control resource usage of multiple sync jobs, etc.

Thanks for reading!