Introduction
This article addresses how to configure a Remote VCS Repository in Artifactory to proxy a public GitLab repository and how to resolve various VCS packages (Branches, Tags, and Files).
It specifically focuses on overcoming common HTTP 404 errors encountered when downloading branches or tags from GitLab subgroups. Due to GitLab's API structure, standard Artifactory VCS requests often fail for nested repositories unless a specific URL path (archive/refs) is injected into the request.
This article will guide you through:
- Configuring a Remote VCS repository for GitLab
- The correct syntax for listing tags and branches
- The specific URL structure required to download branches and tags from GitLab, including the workaround for subgroups
- Examples of curl commands for common VCS operations
Resolution
1. Configure the Remote VCS Repository
Ensure the repository is configured to point to the correct GitLab instance.
- Navigate to Administration > Repositories > Repositories
- Click New Remote Repository of type VCS
- Basic Tab Settings:
- Repository Key: Enter a name (e.g., gitlab-vcs).
- Git Provider: Select GitLab.
- URL: Enter https://gitlab.com/.
- Click Create Remote Repository
Note: If you are using a version lower than 7.127.x. You would need to configure the URL to include the <USER_ORG>/<Sub_folders> until the one before the <REPO>.
For example, resolving: https://gitlab.com/gitlab-org/security-products/gemnasium-db, the URL will be configured: https://gitlab.com/gitlab-org.
2. Understanding the GitLab URL Structure.
When using Artifactory's downloadBranch or downloadTag API for GitLab—especially for repositories inside subgroups—the standard URL often fails.
You must append archive/refs between the repository name and the branch/tag name.
- Standard VCS Format: .../downloadBranch/<repo-key>/<org>/<repo>/<branch>
- Required GitLab Format: .../downloadBranch/<repo-key>/<org>/<repo>/archive/refs/<branch>
3. API Command Reference
Below are the commands to perform VCS operations. Replace the placeholders with your specific details:
- <JFROG_URL>: Your Artifactory URL (e.g., https://mycompany.jfrog.io)
- <REPO_KEY>: The Artifactory VCS repository key (e.g., gitlab-vcs)
- <USER_ORG>: The GitLab User or Group/Subgroup path (e.g., gitlab-org/security-products)
- <REPO>: The GitLab project name (e.g., gemnasium-db)
A. List All Tags
Retrieves a JSON list of all tags available in the remote repository.
Command:
curl -L -u <USERNAME>:<PASSWORD> -XGET "https://<JFROG_URL>/artifactory/api/vcs/tags/<REPO_KEY>/<USER_ORG>/<REPO>"
Example (above 7.127):
curl -L -u admin:password -XGET "https://<JFROG_RL>/artifactory/api/vcs/tags/gitlab-vcs/gitlab-org/security-products/gemnasium-db"
Example (below 7.127.x):
curl -L -u admin:password -XGET "https://<JFROG_RL>/artifactory/api/vcs/tags/gitlab-vcs/security-products/gemnasium-db"
B. List All Branches
Retrieves a JSON list of all branches.
Command:
curl -L -u <USERNAME>:<PASSWORD> -XGET "https://<JFROG_URL>/artifactory/api/vcs/branches/<REPO_KEY>/<USER_ORG>/<REPO>"
C. Download a Branch (GitLab Specific for Version above 7.127.x)
Downloads the specific branch as an archive (.zip or .tar.gz). Note: This includes the archive/refs fix required for GitLab. You cannot download a branch below Artifactory version 7.127.X.
Command:
# Syntax: .../<REPO_KEY>/<USER_ORG>/<REPO>/archive/refs/<BRANCH_NAME>
curl -L -u <USERNAME>:<PASSWORD> "https://<JFROG_URL>/artifactory/api/vcs/downloadBranch/<REPO_KEY>/<USER_ORG>/<REPO>/archive/refs/<BRANCH_NAME>?ext=zip" -o branch.zip
Real-world Example (Subgroup): Downloading the master branch from the gemnasium-db repo inside the gitlab-org/security-products subgroup.
curl -L -u admin:password \
"https://<JFROG_URL>/artifactory/api/vcs/downloadBranch/gitlab-vcs/gitlab-org/security-products/gemnasium-db/archive/refs/master?ext=zip" \
-o master-branch.zip
D. Download a Tag
Downloads a specific tag. Similar to branches, you may need the archive/refs path if standard resolution fails. Note: You cannot download a tag below Artifactory version 7.127.X.
Command:
curl -L -u <USERNAME>:<PASSWORD> "https://<JFROG_URL>/artifactory/api/vcs/downloadTag/<REPO_KEY>/<USER_ORG>/<REPO>/archive/refs/<TAG_NAME>?ext=tar.gz" -o tag.tar.gz
Example:
curl -L -u admin:password "https://<JFROG_URL>/artifactory/api/vcs/downloadTag/gitlab-vcs/gitlab-org/security-products/gemnasium-db/archive/refs/v2.6.0?ext=tar.gz" -o v2.6.0.tar.gz
Conclusion
When using GitLab VCS repositories in Artifactory, standard API calls for listing tags and branches generally function as intended.
For download operations, especially with subgroups, it is essential to check whether archive/refs path injection is required to successfully retrieve the artifact in Artifactory versions above 7.127.X.
Additional Resources:
JFrog Artifactory: Remote VCS Repositories
JFrog Artifactory: Resolve VCS Packages