SVN Mirror Add-On for Bitbucker Server provides a number of REST API end points that could be used to control configured mirrors.
1. How to use REST API to invoke SVN/Git sync
Major REST API use-case is explicit sync invocation for a particular mirror. By default, Git/SVN mirror polls SVN repository every 60 seconds to fetch new changes if there are any. This works fine for most of the users of the add-on, but may lead to performance issues when there are a lot of configured mirrors.
One of the ways to workaround this issue and significantly reduce server load is only to perform sync when there are new revisions available in SVN repository. Periodic polling might be then disabled (by setting poll interval to 0) or configured to use much longer interval, e.g. one of 3600 seconds (1 hour). When sync is explicitly invoked it is also has a benefit of SVN changes being available in Git mostly immediately after SVN commit is completed.
The requirement for the explicit sync configuration is shell access to SVN repository - one will have to install special post-commit hook script into SVN repository that will notify add-on of the new changes via REST API.
$ edit SVN_REPOS/hooks/post-commit
For add-on version 3.0.4 or newer or 3.2.4 or newer:
#!/bin/sh
REPOS="$1"
REV="$2"
BITBUCKET_HOST=192.168.9.10
BITBUCKET_PATH=stash
BITBUCKET_PORT=7990
SVN_REPOS_UUID=$(svnlook uuid "$REPOS")
SVN_CHANGED_PATHS=$(svnlook changed -r "$REV" "$REPOS" | awk 1 ORS='\\n')
curl -s -u username:password -H "Content-Type: application/json" -H "X-Atlassian-Token:no-check" -X POST -d "{ \"uuid\" : \"$SVN_REPOS_UUID\", \"revision\" : \"$REV\", \"changedPaths\" : \"$SVN_CHANGED_PATHS\" }" "http://$BITBUCKET_HOST:$BITBUCKET_PORT/$BITBUCKET_PATH/rest/svn/1.0/sync"
exit 0
For add-on version 3.0.3 or older or 3.2.3 or older:
#!/bin/sh
REPOS="$1"
REV="$2"
BITBUCKET_HOST=192.168.9.10
BITBUCKET_PATH=stash
BITBUCKET_PORT=7990
SVN_REPOS_UUID=$(svnlook uuid "$REPOS")
SVN_CHANGED_PATHS=$(svnlook changed -r "$REV" "$REPOS" | awk 1 ORS='\\n')
curl -s -u username:password -H "X-Atlassian-Token:no-check" -X POST "http://$BITBUCKET_HOST:$BITBUCKET_PORT/$BITBUCKET_PATH/rest/svn/1.0/svnUUID/$SVN_REPOS_UUID?command=sync"
exit 0
Make sure post-commit hook script is executable:
$ chmod ugo+x SVN_REPOS/hooks/post-commit
Upon receiving notification, add-on will invoke sync for mirrors that might be affected by the newly committed SVN revision. To complete configuration, set “Poll interval” (Repository | Settings | Subversion Mirror | Connection Tab) to 3600 to enable occasional scheduled sync.
2. How to use REST API to configure Git/SVN Mirror Repository
Since version 3.3.5 SVN Mirror Add-On provides REST API end-point to configure Git/SVN Mirror repository non-interactively.
Prerequisites:
- SVN Mirror Add-On version 3.3.5 or newer
- Empty Git repository, one should know PROJECT_KEY and REPO_SLUG for that repository
REST API end-point reference:
Request: POST
URL: http://BITBUCKET_HOST/rest/svn/1.0/projects/PROJECT_KEY/repos/REPO_SLUG/configure?start=mirror|import|none&async=false|true
Content-Type: application/json
Body: JSON object of a form:
{
# SVN project URL (required):
"url" : "SVN_PROJECT_URL",
# credentials to access SVN project (required):
"credentials" : {
"username" : "SVN_USERNAME",
"password" : "SVN_PASSWORD"
},
# branches layout (required)
"layout" : {
"type" : "AUTO|DIRECTORY|MANUAL",
# options for AUTO layout type (optional):
"trunkPath" : "path/to/trunk/directory",
# options for MANUAL layout type (optional):
"trunk" : "trunk:refs/heads/master",
"branches" : ["branches/*:refs/heads/*", ...],
"tags" : ["tags/*:refs/tags/*", ...],
"shelves" : ["shelves/*:refs/shelves/*", ...],
"excludePaths" : [],
"excludeBranches" : []
},
# domain to use for authors mapping generation (optional):
"defaultDomain" : "company.com",
# additional configuration options (optional):
"config" : {
# poll interval:
"svn.fetchInterval" : 60,
# translation options:
"translate.eols" : false|true,
"translate.ignores" : false|true
},
# additional authors mappings (optional):
"authors" : {
"svnName" : ["Git Name", "user@company.com"],
...
}
}
Sample sh script:
#!/bin/sh
PROJECT_KEY="PROJECT_1"
REPO_SLUG="mirror"
SVN_URL="https://svn.company.com/repos/project"
SVN_USERNAME="svnUsername"
SVN_PASSWORD="svnPassword"
BITBUCKET_HOST=bitbucket.company.com
BITBUCKET_USERNAME=admin
BITBUCKET_PASSWORD=password
CONFIGURE=$(cat <<END
{
"url" : "$SVN_URL",
"credentials" : {
"username" : "$SVN_USERNAME",
"password" : "$SVN_PASSWORD"
},
"layout" : {
"type" : "AUTO"
}
}
END
)
curl -s -u "$BITBUCKET_USERNAME:$BITBUCKET_PASSWORD" \
-H "Content-Type: application/json" \
-H "X-Atlassian-Token:no-check" \
-X POST \
--data "$CONFIGURE" \
"http://$BITBUCKET_HOST/rest/svn/1.0/projects/$PROJECT_KEY/repos/$REPO_SLUG/configure?start=none&async=false"
exit 0
When “async” argument is “true”, REST call will not block. Otherwise it will block until “configure” command is completed, reporting command completion status. One may request one time import or two-way sync to be started after initial configuration by specifying “start” argument as “mirror”, “import” or “none”.
Git repository must exists prior to running “configure” command.
3. REST API end-points reference
Invoke sync for all configured Git mirrors of SVN repositories with UUID:
Request: POST
URL: http://BITBUCKET_HOST/rest/svn/1.0/svnUUID/SVN_REPOS_UUID?command=sync
Body: none
Invoke sync for all configured Git mirrors of SVN repositories with specified UUID and paths:
URL: http://BITBUCKET_HOST/rest/svn/1.0/sync
Request: POST
Content-Type: application/json
Body: JSON object of a form:
{
"uuid" : "SVN_REPOS_UUID",
"revision" : "SVN_REVISION",
"changedPaths" : "paths modified in SVN_REVISION a format of 'svnlook changed' command' with newlines escaped"
}
Invoke sync for a particular mirror:
Request: POST
URL: http://BITBUCKET_HOST/rest/svn/1.0/projects/PROJECT_KEY/repos/REPO_SLUG?command=sync
Disable or enable sync for a particular mirror:
Request: POST
URL: http://BITBUCKET_HOST/rest/svn/1.0/projects/PROJECT_KEY/repos/REPO_SLUG?command=start|stop
Change mirror configuration option (only available in 3.2.x):
Request: POST
URL: http://BITBUCKET_HOST/rest/svn/1.0/projects/PROJECT_KEY/repos/REPO_SLUG/config?name=OPTION_NAME&value=OPTION_VALUE
Change global configuration option (only available in 3.2.x):
Request: POST
URL: http://BITBUCKET_HOST/rest/svn/1.0/config?name=OPTION_NAME&value=OPTION_VALUE
4. Get Support
Would you have any question on using SubGit with Gerrit, don’t hesitate to contact us at support@subgit.com. We’d be glad to assist you.