Overview
Today, many technologies that are consumed as pure source files are deployed as binaries (for example, PHP, Rails, Node.js, Ruby etc.). As a Binary Repository Manager, Artifactory completes the picture by providing you an easy, safe and secure way to consume those binaries through support for VCS repositories.
Artifactory support for VCS provides:
The ability to list all the tags and branches of any VCS repository.
Access to remote VCS repositories such as GitHub (
https://github.com
) and Bitbucket (https://bitbucket.org
) through Remote Repositories which provide the usual proxy and caching functionality.On-demand local caching of tags and branches for later use in case of network instability or hosted VCS service downtime.
The ability to assign access privileges according to projects or development teams.
Configuration
Repository Layout
VCS repositories require an appropriate repository layout to support a more hierarchical layout of the cached items.
To use a hierarchical layout for your repository, you can either use the built-in vcs-default layout that comes with Artifactory out-of-the-box, or define a Custom Layout. This will ensure that different maintenance features like Version Cleanup will work correctly.
Integration Benefits JFrog Artifactory and Git
Repository layout is final
Once a remote repository is created you cannot change it's layout so we recommend that you define it beforehand.
Built-in Custom Layout: vcs-default
Artifactory's built-in default layout for VCS repositories (vcs-default) can work with both GitHub and BitBucket.
Below is an example of a Custom Layout named vcs-default:
You can configure the Custom Layout, or simply copy the below code snippet into the relevant section in the Administration module, under Repository Management | Layouts.
<repoLayout> <name>vcs-default</name> <artifactPathPattern>[orgPath]/[module]/[refs<tags|branches>]/[baseRev]/[module]-[baseRev](-[fileItegRev])(-[classifier]).[ext]</artifactPathPattern> <distinctiveDescriptorPathPattern>false</distinctiveDescriptorPathPattern> <folderIntegrationRevisionRegExp>.*</folderIntegrationRevisionRegExp> <fileIntegrationRevisionRegExp>[a-zA-Z0-9]{40}</fileIntegrationRevisionRegExp> </repoLayout>
If a repository package layout is in a corresponding folder hierarchy, the Artifactory Version Cleanup tool correctly detects previously installed versions.
Searching for artifact versions using the REST API also works properly:
$ curl "http://localhost:8081/artifactory/api/search/versions?g=jquery&a=jquery&repos=github-cache" { "results" : [ { "version" : "2.0.3", "integration" : false }, { "version" : "master-062b5267d0a3538f1f6dee3df16da536b73061ea", "integration" : true } ] }
Remote Repositories
You need to create a Remote Repository which serves as a caching proxy for github.com. If necessary, you can do the same for bitbucket.org or any other remote git repository that you need.
Artifacts (such as tar.gz
files) requested from a remote repository are cached on demand. You can remove downloaded artifacts from the remote repository cache, however, you can not manually deploy artifacts to a remote repository.
To create a remote repository to proxy github.com
or an self-hosted GitHub Enterprise repository, follow the steps below:
In the Administration module, under Repositories | Repositories | Remote, click New Remote Repository and set VCS to be the Package Type.
Set the Repository Key, and specify the URL to be
https://github.com
(or your GitHub Enterprise URL endpoint) as displayed below:Under VCS Settings, select the GitHub provider in the Git Provider field and click Save & Finish.
Git Providers
Artifactory supports proxying the following Git providers out-of-the-box: GitHub, Bitbucket, Stash, a remote Artifactory instance or a custom Git repository as displayed below:
Use the custom provider if you have a Git repository which does not exist in the pre-defined list. In this case, you need to provide Artifactory with the download paths for your Git tarballs.
You do so by providing 4 placeholders:
Placeholder | Description |
---|---|
{0} | Identifies the username or organization name. |
{1} | Identifies the repository name. |
{2} | Identifies the branch or tag name. |
{3} | Identifies the file extension to download. |
For example, GitHub exposes tarball downloads at: https://github.com/<user>/<repo>/archive/<tag/branch>.<extension>
Therefore, the custom download path configured for Artifactory should be {0}/{1}/archive/{2}.{3}
Using Stash or Bitbucket
If you are using Stash or BitBucket, you need to download and install the BitBucket Server Archive Plugin.
Once the JAR is downloaded, select it in your Stash UI, under Administration | Manage add-ons | Upload add-on.
Once you have installed the add-on you need to restart Stash.
Using the API
VCS repositories must be prefixed with api/vcs in the path
When accessing a VCS repository through Artifactory, the repository URL must be prefixed with api/vcs in the path.
For example, if you are using Artifactory standalone or as a local service, you would access your VCS repositories using the following URL:
http://localhost:8081/artifactory/api/vcs/<repository key>
Or, if you are using Artifactory Cloud, the URL would be:
https://<server name>.jfrog.io/artifactory/api/vcs/<repository key>
Artifactory exposes REST APIs that let you do the following with VCS repositories:
To help you build the API call correctly, you can select the VCS repository you want to interact with and click Set Me Up.
Examples
Below are some examples of working with the API using cURL:
Download jquery master branch from GitHub
curl -i "http://localhost:8080/artifactory/api/vcs/downloadBranch/github/jquery/jquery/master"
Download a specific tag from Bitbucket
curl -i "http://localhost:8080/artifactory/api/vcs/downloadTag/bitbucket/lsystems/angular-extended-notifications/1.0.0"
Download a file within the tag 2.0.1 of jquery, '!' is escaped as '%21'
curl -i "http://localhost:8080/artifactory/api/vcs/downloadTagFile/github/jquery/jquery/2.0.1%21AUTHORS.txt"
When files are already cached, you can conditionally request them using a properties query param:
Download a file within the tag 2.0.1 of jquery, '!' is escaped as '%21'
curl -i "http://localhost:8080/artifactory/api/vcs/downloadBranch/github/jquery/jquery/2.0.1?properties=qa=approved"
Accessing Private VCS Repositories
Artifactory also supports accessing private VCS repositories such as a private GitHub or any self-hosted authenticated one.
To do so, simply add your credentials under Advanced Settings of the remote repository configuration panel.
Credentials when redirected
Some git providers (GitHub included) redirects download requests to a CDN provider.
You will need your credentials to pass along with the redirected request, simply check the Lenient Host Authentication and the credentials will pass transparently on each redirected request.