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 on-prem 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:
- List all tags
- List all branches
- Download a specific tag
- Download a file within a tag
- Download a specific branch
- Download a file within a branch
- Download a release
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:
curl -i "http://localhost:8080/artifactory/api/vcs/downloadBranch/github/jquery/jquery/master"
curl -i "http://localhost:8080/artifactory/api/vcs/downloadTag/bitbucket/lsystems/angular-extended-notifications/1.0.0"
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:
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.