Artifactory 4.x

Using Artifactory 5.x ?
JFrog Artifactory 5.x User Guide

Expand all   Collapse all

Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

Artifactory fully supports VCS repositories on top of Artifactory's existing support for advanced artifact management.

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.

Artifactory support for VCS provides:

  1. The ability to list all the tags and branches of any VCS repository.
  2. Access to remote VCS repositories (such as https://github.com) through Remote Repositories which provide the usual proxy and caching functionality.
  3. On-demand local caching of tags and branches for later use in case of network instability or hosted VCS service downtime.
  4. The ability to assign access privileges according to projects or development teams.

 

 

Page Contents

Configuration

Repository Layout

Before you start creating remote repositories, you need to create a custom layout to support a more hierarchical layout of the cached items.

To use a hierarchical layout for your repository, you should define a Custom Layout. This will ensure that different maintenance features like Version Cleanup will work correctly.

Repository layout is optional

Defining a Custom Layout for your repository is an optional step, however it is recommended to do so since it allows Artifactory to perform different maintenance tasks such as Version Cleanup automatically.

Once a remote repository is created you cannot change it's layout so we recommend that you define it beforehand.

 

Below is an example of a Custom Layout named vcs-default:
VCS Repository Layout

You can configure this Custom Layout as displayed in the image above, or simply copy the below code snippet into the relevant section in your Artifactory Central Configuration (in the Admin module, under Advanced | Config Descriptor):

<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.
Version Cleanup

 

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:

  1. In the Admin module, under Repositories | Remote,  click "New" and set VCS to be the Package Type. 
  2. Set the Repository Key, and specify the URL to be https://github.com (or your GitHub Enterprise URL endpoint) as displayed below:
    Create a remote VCS repository

  3. 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:

PlaceholderDescription
{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 SaaS, the URL would be:

https://<server name>.jfrog.io/<server name>/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.

Set Me Up for VCS Repositories

Get VCS Tags

Description: Lists all VCS tags.
Since: 3.6.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/vcs/tags/{repoKey}/{userOrg}/{repo}
Produces: application/json
Sample Output:

GET /api/vcs/tags/github/jquery/jquery
[ {
  "name" : "1.0",
  "commitId" : "bcc8a837055fe720579628d758b7034d6b520f2e",
  "isBranch" : false
}, {
  "name" : "1.0.1",
  "commitId" : "bcc8a837055fe720579628d758b7034d6b520f2e",
  "isBranch" : false
}
...]

Get VCS Branches

Description: Lists all VCS branches.
Since: 3.6.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/vcs/branches/{repoKey}/{userOrg}/{repo}
Produces: application/json
Sample Output:

GET /api/vcs/branches/github/jquery/jquery
[ {
  "name" : "1.11-stable",
  "commitId" : "852529c9f148de6df205be01659a79731ce8ebef",
  "isBranch" : true
}, {
  "name" : "1.x-master",
  "commitId" : "73c1ceaf4280bd0318679c1ad832181f3f449814",
  "isBranch" : true
}
...]

Download Tag

Description: Download a complete tarball (tar.gz/zip, default tar.gz) of a tag.
Downloading can be executed conditionally according to properties by specifying the properties query param. In this case only cached artifacts are searched.
Since: 3.6.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/vcs/downloadTag/{repoKey}/{userOrg}/{repo}/{tag-name}?ext=tar.gz/zip (default tar.gz)
Produces: application/octet-stream
Sample Output: 

GET /api/vcs/downloadTag/github/jquery/jquery/2.0.1
<Tag binary content>

Download File within a Tag

Description: Download a specific file from within a tag.
Since: 3.6.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/vcs/downloadTagFile/{repoKey}/{userOrg}/{repo}/{tag-name}!{file-path}
Produces: application/octet-stream
Sample Output:

GET /api/vcs/downloadTagFile/github/jquery/jquery/2.0.1!AUTHORS.txt
<AUTHORS.txt content>

Download Branch 

Description: Downloads a tarball (tar.gz/zip, default tar.gz) of a complete branch.
Downloading can be executed conditionally according to properties by specifying the properties query param. In this case only cached artifacts are searched.
Since: 3.6.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/vcs/downloadBranch/{repoKey}/{userOrg}/{repo}/{branch-name}?ext=tar.gz/zip[&properties=qa=approved]
Produces: application/octet-stream
Sample Output: 

GET /api/vcs/downloadBranch/github/jquery/jquery/master
<Branch binary content>

Download File within a Branch 

Description: Downloads a specific file from within a branch.
Since: 3.6.0
Security: Requires a privileged user (can be anonymous)
Usage: GET /api/vcs/downloadBranchFile/{repoKey}/{userOrg}/{repo}/{branch-name}!{file-path}
Produces: application/octet-stream
Sample Output:  

GET /api/vcs/downloadBranchFile/github/jquery/jquery/master!README.md
<AUTHORS.txt content>

Download Release 

Description: Downloads a complete release tarball (tar.gz/zip, default tar.gz) of a tag from GitHub.
Since: 4.3.0
Security: Requires a privileged user (can be anonymous)
VCS Usage: GitHub only
Usage: GET /api/vcs/downloadRelease/{repoKey}/{userOrg}/{repo}/{release-name}?ext=tar.gz/zip (default tar.gz)
Produces: application/octet-stream
Sample Output:  

GET /api/vcs/downloadRelease/git-remote/google/protobuf/v3.0.0-beta-1?ext=tar.gz/zip
<Tag binary content>

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.

 

 

  • No labels