git-annex/ tips/ centralized git repository tutorial/ on GitLab

Update: GitLab removed support for git-annex in 2017 with the 9.0 release.

This tutorial shows how to set up a centralized repository hosted on GitLab.

Since GitLab has added support for git-annex on their servers, you can store your large files on GitLab, quite easily.

Note that as I'm writing this, GitLab is providing this service for free, and will store up to 10 gb per project.

## create the repository

Go to https://gitlab.com/ and sign up for an account, and create the repository there. Take note of the SSH clone url for the repository, which will be something like `git@gitlab.com:yourlogin/annex.git`.

We want to clone this locally, on your laptop. (If the clone fails, you need to generate a ssh key and add it to GitLab.)

    # git clone git@gitlab.com:yourlogin/annex.git
    # cd annex

Tell git-annex to use the repository, and describe where this clone is located:

    # git annex init 'my laptop'
    init my laptop ok

Add some files, obtained however.

    # git annex add *.mp4
    add Haskell_Amuse_Bouche-b9OVqxmI.mp4 (checksum) ok
    (Recording state in git...)
    # git commit -m "added a video. I have not watched it yet but it sounds interesting"

Feel free to rename the files, etc, using normal git commands:

    # git mv Haskell_Amuse_Bouche-b9OVqxmI.mp4 Haskell_Amuse_Bouche.mp4
    # git commit -m 'better filenames'

## push to GitLab

Now make a first push to the GitLab repository. As well as pushing the master branch, remember to push the git-annex branch, which is used to track the file contents.

    # git push origin master git-annex
    To git@gitlab.com:yourlogin/annex.git
     * [new branch]      master -> master
     * [new branch]      git-annex -> git-annex

That push went fast, because it didn't upload the large file contents yet.

So, to finish up, tell git-annex to sync all the data in the repository to GitLab:

    # git annex sync --content
    ...

## make more checkouts

So far you have a central repository on GitLab, and a checkout on a laptop. Let's make another checkout elsewhere. Clone the central repository as before. (If the clone fails, you need to generate a ssh key and add it to GitLab.)

    elsewhere# git clone git@gitlab.com:yourlogin/annex.git
    elsewhere# cd annex

Notice that your clone does not have the contents of any of the files yet. If you run `ls`, you'll see broken symlinks. It's easy to download them from GitLab either by running `git annex sync --content`, or by asking git-annex to download individual files:

    # git annex get Haskell_Amuse_Bouche.mp4
    get Haskell_Amuse_Bouche.mp4 (from origin...)
    12877824   2%  255.11kB/s    00:00
    ok

comment 4

@ovidiu, this tutorial is about setting up GitLab as a remote using git-annex at the command line. The steps given here should work.

You're trying to use GitLab from the git-annex assistant. The first version that supported that was version 5.20150731. I guess you might have been trying to use an older version. Or encountered some other problem which is offtopic to this page. If you have a problem, file a bug report with full details about the version of git-annex you used and what you did.

Comment by joey — Tue Jul 22 18:11:47 2025
comment 3
oh, and btw. there's no button in the assistant to delete this useless gitlab repo, I can only edit it and try and upgrade it which doesn't work :-(
Comment by ovidiu — Tue Jul 22 18:11:47 2025
comment 2
I managed to overcome that hurdle but now gitlab shows as "just a git repository" and I don't seem to be able to do the conversion "Upgrade Repository" - nothing in the logs, any ideas?
Comment by ovidiu — Tue Jul 22 18:11:47 2025
Need advice on using gitlab with the assistant

There is a GUI and I followed it but when upgrading it to a full git-annex repository I get:

remote: GitLab: You are not allowed to force push code to a protected branch on this project.
To git@git-annex-gitlab.com-git_22_pacuraru.2Fgitannex.2Egit:pacuraru/gitannex.git ! [remote rejected] refs/gcrypt/gitception+ -> master (pre-receive hook declined) error: failed to push some refs to 'git@git-annex-gitlab.com-git_22_pacuraru.2Fgitannex.2Egit:pacuraru/gitannex.git' error: failed to push some refs to 'gcrypt::git@git-annex-gitlab.com-git_22_pacuraru.2Fgitannex.2Egit:pacuraru/gitannex.git' [2015-10-03 23:01:30.409376] main: Syncing with gitlab.com_pacuraru_gitannex.git

Comment by ovidiu — Tue Jul 22 18:11:47 2025
Comments on this page are closed.