<< Back to GForge REST API

Entity: Scm

GET

getAcl

Return the list of SCM module ACL entries for the specified project.

Parameters (1)

Name Type Description
project string Project unix name or integer database ID (route segment).

Return: array

getAssociation

Return the tracker items associated with the specified commit hash.

Parameters (2)

Name Type Description
id string Project unix name or integer database ID (route segment).
commit_hash string Full commit hash to look up associations for.

Return: (none)

getBranch

Lists the branches available in this repository, or returns info about a specific branch.

Parameters (6)

Name Type Description
id string Project unix name or integer database ID (route segment).
branch string Exact branch name (or CVS module name) to retrieve. When present returns a single record or 404.
branchName string For CVS repositories, the branch name within the specified module.
filter string Prefix filter; returns only branches whose names begin with this string.
page_num int 1-based page number. Defaults to 1.
page_size int Number of items per page. Defaults to 1000.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\plugins\scm\models\api\ScmBranch[]|\gforge\plugins\scm\models\api\ScmBranch

Zero or more ScmBranch records for a search. Zero or one ScmBranch record for a name retrieval.

Example 1

Get a single branch by name: 
  GET http://api.mygforge.tld/scm/{unixName}/branch/gforge-next


{"name":"gforge-next","type":"branch"}

Example 2

Get branches that begin with next: 
  GET http://api.mygforge.tld/scm/{unixName}/branch/?filter=next


{"paging":{"page_size":10,"page_num":1,"sort_field":"id","sort_dir":"asc"},
"items":[{"name":"next\/activitytype-filter#24004","type":"branch"},
{"name":"next\/angular_files_#20823","type":"branch"},
{"name":"next\/anon-ti-edit-redirect-#24330","type":"branch"},
{"name":"next\/anonymous-poll-query-#24322","type":"branch"},
{"name":"next\/audit-display-net-#23881","type":"branch"},
{"name":"next\/avatar-mydashboard-bug#23838","type":"branch"},
{"name":"next\/avatar-none-bug#23841","type":"branch"},
{"name":"next\/beta-users-mailchimp-#25079","type":"branch"},
{"name":"next\/blockquoyed-text-#24966","type":"branch"},
{"name":"next\/burndown-rendering-#24261","type":"branch"}],"links":[]}

Example 3

List the branches: 
  GET http://api.mygforge.tld/scm/{unixName}/branch


{"paging":{"page_size":10,"page_num":1,"sort_field":"id","sort_dir":"asc"},
"items":[{"name":"add_gitwebjs_gitignore#23837","type":"branch"},{"name":"angularjs","type":"branch"},
{"name":"api#20980","type":"branch"},{"name":"api-ga-#19613","type":"branch"},
{"name":"api-jsfooter-#19558","type":"branch"},{"name":"apidoc-css-#21234","type":"branch"},
{"name":"atmel-master","type":"branch"},{"name":"audit-text-fields-#23878","type":"branch"},
{"name":"auto_close_#15134","type":"branch"},{"name":"autoapproveproject#25365","type":"branch"}],"links":[]}
Note: Branches are always sorted by name (asc). There are no other sort fields.

getComment

Get the comments associated with any commits between the from and to parameters.

Parameters (3)

Name Type Description
id string Project unix name or integer database ID (route segment).
from string Source branch, tag or commit reference (start of the range).
to string Target branch, tag or commit reference (end of the range).

Return: \gforge\plugins\scm\models\ScmMergeComment[]

Zero or more comments for the specified range of commits.

getCommit

Parameters (8)

Name Type Description
id string Project unix name or integer database ID (route segment).
branch string Branch name to scope the commit listing or single-commit lookup.
tag string Tag name to scope the commit listing or single-commit lookup.
commit string Specific commit hash to retrieve. When present returns a single record or 404.
module string CVS module name to scope the query (CVS repositories only).
rel string Comma-separated related data. Supported: diff, trackeritem.
page_size int Number of commits per page (list mode). Defaults to 20.
page_num int 0-based page offset (list mode). Defaults to 0.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Related Entities (1)

rel= Type Description
diff string Include the diff for this commit.

Return: \gforge\plugins\scm\models\api\ScmCommitBasic|\gforge\plugins\scm\models\api\ScmCommitBasic[]

Zero or more records.

getFile

Get the properties for a single file, on the specified branch, tag, or commit.

Parameters (6)

Name Type Description
id string Project unix name or integer database ID (route segment).
branch string Branch name to resolve the file at.
tag string Tag name to resolve the file at.
commit string Specific commit hash to resolve the file at.
path string Path to the file within the repository; may also be supplied as trailing route segments.
rel string Comma-separated related data. Supported: raw, commit, history, blame.

Related Entities (2)

rel= Type Description
commit \gforge\plugins\scm\models\api\ScmCommitBasic The commit in which this version of the file was authored.
raw string The raw content of the file. If binary, it will be base-64 encoded. TODO Add blame data as a rel

Return: \gforge\plugins\scm\models\api\ScmFile

Basic info about the file

Name Type Description
name string
type string
mode string
size int
isBinary string
id string
lastModified \DateTime
logMessage string
commitHash string

getLfs

Stream or verify a stored Git LFS object for the specified project.

Parameters (3)

Name Type Description
id string Project unix name or integer database ID.
oid string SHA-256 OID of the LFS object to retrieve.
action string Optional action modifier. Pass verify to confirm the object exists without streaming its content.

Return: void

getMerge

Get information about the differences between two revisions Route: /api/scm/{id-unixname}/merge?from=&to=&rel=

Parameters (4)

Name Type Description
id string Project unix name or integer database ID (route segment).
from string Source branch, tag or commit reference for the merge.
to string Target branch, tag or commit reference for the merge.
rel string Comma-separated related data. Supported: diffs, commits, comments.

Related Entities (2)

rel= Type Description
diffs string Include the set of diffs for this proposed merge.
commits string Include the list of commit summaries for this proposed merge.

Return: \gforge\plugins\scm\models\api\ScmMerge

Information about the proposed merge.

Name Type Description
from string
to string
rel array
meta \StdClass Attributes about the diff/merge response, populated by ScmSizeLimitService and (for Git) by the numstat pre-pass in GitService::GetCommitDiff. Fields:
  • canMerge: If true, an automated merge can be done cleanly.
  • isMerged: If true, the $from branch is already completely merged into the $to branch.
  • fileLines: If true, one or more files in the response had too many lines and was truncated.
  • fileLinesLimit: The configured max # of lines that a single file's diff can contain.
  • fileSize: If true, one or more files in the response was too large and was truncated.
  • fileSizeLimit: The configured max size (in bytes) that a single file's diff can contain.
  • diffLines: If true, the total raw diff output exceeded the line limit and was truncated.
  • diffLinesLimit: The configured max # of raw lines the entire diff can contain (across all files).
  • diffSize: If true, the total raw diff output exceeded the byte limit and was truncated.
  • diffSizeLimit: The configured max size (in bytes) the entire raw diff can contain.
  • diffCount: If true, the diff contained too many individual files and was truncated to diffCountLimit.
  • diffCountLimit: The configured max # of files the diff can contain.
  • commitCount: If true, too many individual commits were returned and the list was truncated.
  • commitCountLimit: The configured max # of commits allowed.
  • totalFileCount: Total # of files changed in the commit (from git numstat; 0 for SVN/CVS).
  • totalAdded: Total lines added across all changed files (from git numstat; excludes binary files).
  • totalRemoved: Total lines removed across all changed files (from git numstat; excludes binary files).
  • allFiles: Array of StdClass({fileName, added, removed}) for every file changed in the commit.
  • truncatedFiles: Subset of allFiles whose diffs could not be included due to size limits.

getPromotionModel

Get the promotion model associated with this repository.

Parameters (1)

Name Type Description
id string Project unix name or integer database ID (route segment).

Return: string[]

The list of promotion branches to be tracked.

getRaw

Get the raw content for a single file, on the specified branch, tag, or commit. If the file is a directory, get its contents in tarball or zip format Route: /api/scm/{id-unixname}/raw/zero/or/more/paths?branch=&tag=&commit=

Parameters (6)

Name Type Description
id string Project unix name or integer database ID (route segment).
branch string Branch name to resolve the file at.
tag string Tag name to resolve the file at.
commit string Specific commit hash to resolve the file at.
path string Path to the file or directory within the repository; may also be supplied as trailing route segments.
type string Archive format for directory exports: zip or tar (default).

Return: string

The contents of the requested file & version.

getRequestCommitish

Parameters (2)

Name Type Description
request \RequestParameters
project \cm\Project

Return: string[]

Branch, tag name or commit hash, and branch type

getRequestTree

Parameters (1)

Name Type Description
request \RequestParameters

Return: string

The path elements from the request, separated by / characters.

getScm

Return basic information about the SCM configuration for the specified project unix name or ID.

Parameters (1)

Name Type Description
id string Project unix name or integer database ID (route segment or query param).

Return: \gforge\plugins\scm\models\api\ScmBasic

Zero or one ScmBasic record for the specified project.

Name Type Description
unixName string
scmType string
defaultBranchName string
hostName string
options \stdClass for settings on the scm repo Fields:
  • useSsh: If true, then ssh access is enabled for this repository.
  • anonymousRead: If true, then anonymous users can read the repository.
  • requireTrackerItem: If true, then all commits must reference a Tracker Item ID.
  • validateEmail: If true, then all committer emails must belong to an authorized GForge user.
  • mailCommits: If true, then project members will receive email notifications about commits.
  • requireConventionalCommit: If true, then all commits must follow the Conventional Commits specification.
  • accessText: Optional custom text to be shown in the SCM access UI section.
  • browseText: Optional custom text to be shown in the SCM browse UI section.

Example 1

Get SCM info for a project with unix name = myproject 
  GET http://api.mygforge.tld/api/scm/myproject


  {"unixName":"myproject","scmType":"git","defaultBranchName":"master","hostName":"gforge.com",
  "options":{"useSsh":false,"anonymousRead":true,"requireTrackerItemId":false,"mailCommits":false}}

Example 2

Get SCM info for a project with database ID = 12345 
  GET http://api.mygforge.tld/api/scm/12345


  {"unixName":"myproject","scmType":"git","defaultBranchName":"master","hostName":"gforge.com",
"options":{"useSsh":false,"anonymousRead":true,"requireTrackerItemId":false,"mailCommits":false}}

getSummary

Get a summary of activity data for the specified project's SCM, over the specified (or default) date range

NOTE: The date range will be filled in by day, even if no data is found for that day, so that the array is continuous across the specified range.

Parameters (5)

Name Type Description
id string Project unix name or integer database ID.
start string Start date for the activity range (format: Y-m-d). Defaults to two weeks before end.
end string End date for the activity range (format: Y-m-d). Defaults to the day after the last commit.
by_user string When non-empty, break stats down by user per day.
rel string Comma-separated list of related data to include. Supported: chart_data, model.

Related Entities (3)

rel= Type Description
Include chart_data a transformed version of the stats data for use in charting
Include chart_data scm commit chart data.
Include model the promotion model for this repository.

Return: \gforge\plugins\scm\models\api\ScmSummary

The summary data, including a stats array with date, checkouts, commits and adds. Not all values are valid for all SCM types, may be empty or zero.

Name Type Description
stats \gforge\core\models\api\StatsBasic[] Commit stats for the repository. NOTE: If the summary was requested with the chart parameter, then this will be an array of StdClass objects, with data optimized for chart display.
totalCommits int
startDate string The date, in Y-m-d format
endDate string The date, in Y-m-d format
unixName string
scmType string
defaultBranchName string
hostName string
options \stdClass for settings on the scm repo Fields:
  • useSsh: If true, then ssh access is enabled for this repository.
  • anonymousRead: If true, then anonymous users can read the repository.
  • requireTrackerItem: If true, then all commits must reference a Tracker Item ID.
  • validateEmail: If true, then all committer emails must belong to an authorized GForge user.
  • mailCommits: If true, then project members will receive email notifications about commits.
  • requireConventionalCommit: If true, then all commits must follow the Conventional Commits specification.
  • accessText: Optional custom text to be shown in the SCM access UI section.
  • browseText: Optional custom text to be shown in the SCM browse UI section.

Example 1

Get stats for a given data range 
  GET http://api.mygforge.tld/scm/{unixName}/summary?start=2019-01-01&end=2019-01-10

{
  "stats": [
  {
"statDate": "2019-01-01",
"title": "",
"measure": 0,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-02",
"title": "commits",
"measure": 6,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-03",
"title": "commits",
"measure": 15,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-04",
"title": "commits",
"measure": 8,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-05",
"title": "",
"measure": 0,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-06",
"title": "",
"measure": 0,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-07",
"title": "commits",
"measure": 2,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-08",
"title": "commits",
"measure": 5,
"section": "",
"refId": 0,
"url": ""
},
{
"statDate": "2019-01-09",
"title": "commits",
"measure": 4,
"section": "",
"refId": 0,
"url": ""
}
],
"totalCommits": 40,
"startDate": "2019-01-01",
"endDate": "2019-01-10",
"unixName": "gforge5",
"scmType": null,
"defaultBranchName": null,
"hostName": "localhost",
"options": {
"useSsh": false,
"anonymousRead": false,
"requireTrackerItemId": true,
"validateEmail": false,
"mailCommits": true,
"requireAssignment": false,
"restrictAssocCurrentProject": false,
"accessText": "",
"browseText": ""
},
"rel": []
}

getTag

Lists the tags available in this repository, or returns info about a specific tag.

Parameters (5)

Name Type Description
id string Project unix name or integer database ID (route segment).
tag string Exact tag name to retrieve. When present returns a single record or 404.
filter string Prefix filter; returns only tags whose names begin with this string.
page_num int 1-based page number. Defaults to 1.
page_size int Number of items per page. Defaults to 1000.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\plugins\scm\models\api\ScmBranch|\gforge\plugins\scm\models\api\ScmBranch[]

Zero or more ScmBranch records for a search. Zero or one ScmBranch record for a name retrieval.

Example 1

List the tags: 
  GET http://api.mygforge.tld/scm/{unixName}/tag


{"paging":{"page_size":115,"page_num":1,"sort_field":"id","sort_dir":"asc"},
"items":[{"name":"6_0b2","type":"tag"},{"name":"V5_7_ce","type":"tag"},{"name":"V5_7texinst","type":"tag"},
{"name":"V_5_2_6","type":"tag"},{"name":"ge-6.1.0","type":"tag"},{"name":"ge-v6.1.2","type":"tag"},
{"name":"ge_6.0.2","type":"tag"},{"name":"noaa_5.2.4.5","type":"tag"},{"name":"raytheon-6.1.2","type":"tag"},
{"name":"raytheon-6.1.3-alpha1","type":"tag"},{"name":"raytheon-6.1.3-beta1","type":"tag"},
{"name":"raytheon-6.1.3b1","type":"tag"},{"name":"remove","type":"tag"},{"name":"sandia_5_2_7b","type":"tag"},
{"name":"siemens-v6.3.1","type":"tag"},{"name":"v5_0","type":"tag"},{"name":"v5_0_1","type":"tag"},
{"name":"v5_0_2","type":"tag"},{"name":"v5_0_3","type":"tag"},{"name":"v5_1","type":"tag"},
{"name":"v5_1_1","type":"tag"},{"name":"v5_1_2","type":"tag"},{"name":"v5_1_3","type":"tag"},
{"name":"v5_1_4","type":"tag"},{"name":"v5_1_a","type":"tag"},{"name":"v5_2","type":"tag"},
{"name":"v5_2_1","type":"tag"},{"name":"v5_2_2","type":"tag"},{"name":"v5_2_4","type":"tag"},
{"name":"v5_2_5","type":"tag"},{"name":"v5_2_6","type":"tag"},{"name":"v5_2_6b","type":"tag"},
{"name":"v5_2_7","type":"tag"},{"name":"v5_2_7b","type":"tag"},{"name":"v5_3","type":"tag"},
{"name":"v5_3_1","type":"tag"},{"name":"v5_3_2","type":"tag"},{"name":"v5_3_2_siemens","type":"tag"},
{"name":"v5_3_2_siemens2","type":"tag"},{"name":"v5_3_3","type":"tag"},{"name":"v5_3b1","type":"tag"},
{"name":"v5_3b3","type":"tag"},{"name":"v5_3b4","type":"tag"},{"name":"v5_3b5","type":"tag"},
{"name":"v5_4_1","type":"tag"},{"name":"v5_4_1ge","type":"tag"},{"name":"v5_4_1noaa","type":"tag"},
{"name":"v5_4_1sandia","type":"tag"},{"name":"v5_4_1siemens","type":"tag"},{"name":"v5_4_2","type":"tag"},
{"name":"v5_4_2ge","type":"tag"},{"name":"v5_4_3","type":"tag"},{"name":"v5_4_4","type":"tag"},
{"name":"v5_4_ge_b1","type":"tag"},{"name":"v5_4_noaa-final","type":"tag"},
{"name":"v5_4_sandia","type":"tag"},{"name":"v5_4_siemens","type":"tag"},{"name":"v5_4fb","type":"tag"},
{"name":"v5_4fb2","type":"tag"},{"name":"v5_4noaa","type":"tag"},{"name":"v5_5","type":"tag"},
{"name":"v5_5_1","type":"tag"},{"name":"v5_5b2","type":"tag"},{"name":"v5_5b3","type":"tag"},
{"name":"v5_5raytheon","type":"tag"},{"name":"v5_5rc1","type":"tag"},{"name":"v5_5rc2","type":"tag"},
{"name":"v5_5sandia","type":"tag"},{"name":"v5_5siemens","type":"tag"},{"name":"v5_6","type":"tag"},
{"name":"v5_6_1","type":"tag"},{"name":"v5_6_1_asterisk","type":"tag"},{"name":"v5_6a","type":"tag"},
{"name":"v5_6rc2","type":"tag"},{"name":"v5_6rc3","type":"tag"},{"name":"v5_6rc4","type":"tag"},
{"name":"v5_7","type":"tag"},{"name":"v5_7_1","type":"tag"},{"name":"v5_7_1_b1_cisco","type":"tag"},
{"name":"v5_7_1_b1_oracle","type":"tag"},{"name":"v5_7_1_ge","type":"tag"},
{"name":"v5_7_1_raytheon","type":"tag"},{"name":"v5_7_1_siemens","type":"tag"},
{"name":"v5_7_1_texinst","type":"tag"},{"name":"v5_7_1ge","type":"tag"},{"name":"v5_7_2","type":"tag"},
{"name":"v5_7_2_ge","type":"tag"},{"name":"v5_7_2_raytheon","type":"tag"},{"name":"v5_7_b2_ge","type":"tag"},
{"name":"v5_7_ge","type":"tag"},{"name":"v5_7_raytheon","type":"tag"},{"name":"v5_7_sandia","type":"tag"},
{"name":"v5_7_siemens","type":"tag"},{"name":"v5_7b1","type":"tag"},{"name":"v5_7b1_oracle","type":"tag"},
{"name":"v5_7ce","type":"tag"},{"name":"v5_7rc1","type":"tag"},{"name":"v5_7rc1-ce","type":"tag"},
{"name":"v5_7texinst","type":"tag"},{"name":"v6.0.3","type":"tag"},{"name":"v6.1","type":"tag"},
{"name":"v6.1.1","type":"tag"},{"name":"v6.1.2","type":"tag"},{"name":"v6.2","type":"tag"},
{"name":"v6.2.1","type":"tag"},{"name":"v6.3.0","type":"tag"},{"name":"v6.3.1","type":"tag"},
{"name":"v6.4.0","type":"tag"},{"name":"v6.4.1","type":"tag"},{"name":"v6_0_1","type":"tag"},
{"name":"v6_0b1","type":"tag"},{"name":"v6_0b2","type":"tag"},{"name":"v6_1b1","type":"tag"},
{"name":"v6_1b2","type":"tag"},{"name":"v_5_2_5","type":"tag"}],"links":[]}

Example 2

Get a single tag by name: 
  GET http://api.mygforge.tld/scm/{unixName}/tag/{branchname}


{"name":"6_0b2","type":"tag"}

Example 3

Get tags that begin with v (e.g., v1.0, v0.1): 
  GET http://api.mygforge.tld/scm/{unixName}/tag/?filter=v


{"paging":{"page_size":10,"page_num":1,"sort_field":"id","sort_dir":"asc"},
"items":[{"name":"V5_7_ce","type":"tag"},{"name":"V5_7texinst","type":"tag"},
{"name":"V_5_2_6","type":"tag"},{"name":"v5_0","type":"tag"},{"name":"v5_0_1","type":"tag"},
{"name":"v5_0_2","type":"tag"},{"name":"v5_0_3","type":"tag"},{"name":"v5_1","type":"tag"},
{"name":"v5_1_1","type":"tag"},{"name":"v5_1_2","type":"tag"}],"links":[]}

getTree

Get the list of files and folders associated with the specified branch, tag, commit and tree path.

Parameters (5)

Name Type Description
id string Project unix name or integer database ID (route segment).
branch string Branch name to scope the tree listing.
tag string Tag name to scope the tree listing.
commit string Specific commit hash to scope the tree listing.
path string Path within the repository tree; may also be supplied as trailing route segments.

Return: \gforge\plugins\scm\models\api\ScmFile[]

Zero or more files and folders

Name Type Description
name string
type string
mode string
size int
isBinary string
id string
lastModified \DateTime
logMessage string
commitHash string

POST

postAcl

Create or update a single SCM module ACL entry for the specified project.

Parameters (4)

Name Type Description
project string Project unix name or integer database ID (route segment).
id int Module record ID (0 to create a new module).
moduleName string Name of the SCM module / path being controlled.
rolePermissions array Array of role-permission objects to apply to this module.

Return: \gforge\plugins\scm\models\api\ScmModuleApi

Name Type Description
id int
path string
projectId int
userPermissions \ScmModuleUserApi[]
rolePermissions \ScmModuleRoleApi[]

postAssociation

Associate a commit with a tracker item in the specified project.

Parameters (3)

Name Type Description
id string Project unix name or integer database ID (route segment).
commitHash string Full commit hash to associate.
trackerItemId int Database ID of the tracker item to associate the commit with.

Return: (none)

postComment

Add a comment to the specified commit, file and line. A new record will always be created.

Parameters (5)

Name Type Description
id string Project unix name or integer database ID (route segment).
commit string SHA hash of the commit to attach the comment to.
path string Repository-relative file path within the commit.
line int Line number within the file that the comment refers to.
body string Comment text.

Return: \gforge\plugins\scm\models\api\ScmMergeComment

The newly-created comment, or a set of validation error(s).

Name Type Description
id int Unique identifier for this comment, 0 for a new comment.
path string The path/file name of the file to which the comment applies
line int The line number (within $path) to which the comment applies.
postDate \DateTime The date and time when the comment was created
status int The lifecycle status of this comment. See models\ScmMergeComment for constants/values.
body string The comment text.
context string JSON-encoded excerpt of the diff lines around the line that was commented on. Can be used for display of the original content that prompted the comment, after the file has been changed.
commit mixed A string or ScmCommitBasic object representing the revision to which the comment applies.
user mixed The ID, unix name or UserBasic object representing the user that submitted the comment.

postDeploy

Records deployment events on all open tracker items whose associated commits are included in the given revision and have not already been covered by a prior deployment at the same level.

Parameters (3)

Name Type Description
id string Project unix name or integer database ID (route segment).
sub string -id The revision (commit hash or branch tip) being deployed (route segment).
level string Deployment environment label. Defaults to production.

Return: void

postLfs

Handle a Git LFS batch API request (upload or download) for the specified project.

Parameters (5)

Name Type Description
id string Project unix name or integer database ID.
operation string LFS operation type: download or upload.
objects array Array of LFS object descriptors (each with oid and size).
ref array Reference object with name key; required for upload operations.
oid string When present, triggers LFS verify mode instead of batch mode.

Return: array

postMerge

Merge one set of changes into another branch/tag/revision.

Parameters (3)

Name Type Description
id string Project unix name or integer database ID (route segment).
from string Source branch, tag or commit reference to merge from.
to string Target branch to merge into. The authenticated user must have write access to this branch.

Related Entities (2)

rel= Type Description
diff string Include the diff for this proposed merge.
commits string Include the list of commit summaries for this proposed merge.

Return: \gforge\plugins\scm\models\api\ScmMerge

Information about the completed merge.

Name Type Description
from string
to string
rel array
meta \StdClass Attributes about the diff/merge response, populated by ScmSizeLimitService and (for Git) by the numstat pre-pass in GitService::GetCommitDiff. Fields:
  • canMerge: If true, an automated merge can be done cleanly.
  • isMerged: If true, the $from branch is already completely merged into the $to branch.
  • fileLines: If true, one or more files in the response had too many lines and was truncated.
  • fileLinesLimit: The configured max # of lines that a single file's diff can contain.
  • fileSize: If true, one or more files in the response was too large and was truncated.
  • fileSizeLimit: The configured max size (in bytes) that a single file's diff can contain.
  • diffLines: If true, the total raw diff output exceeded the line limit and was truncated.
  • diffLinesLimit: The configured max # of raw lines the entire diff can contain (across all files).
  • diffSize: If true, the total raw diff output exceeded the byte limit and was truncated.
  • diffSizeLimit: The configured max size (in bytes) the entire raw diff can contain.
  • diffCount: If true, the diff contained too many individual files and was truncated to diffCountLimit.
  • diffCountLimit: The configured max # of files the diff can contain.
  • commitCount: If true, too many individual commits were returned and the list was truncated.
  • commitCountLimit: The configured max # of commits allowed.
  • totalFileCount: Total # of files changed in the commit (from git numstat; 0 for SVN/CVS).
  • totalAdded: Total lines added across all changed files (from git numstat; excludes binary files).
  • totalRemoved: Total lines removed across all changed files (from git numstat; excludes binary files).
  • allFiles: Array of StdClass({fileName, added, removed}) for every file changed in the commit.
  • truncatedFiles: Subset of allFiles whose diffs could not be included due to size limits.

postPromotionModel

Update the promotion model associated with this repository

Parameters (2)

Name Type Description
id string Project unix name or integer database ID (route segment).
branches string Comma-separated ordered list of branch names that make up the promotion model.

Return: array

The updated model

postRepo

Upload an SVN dump file to the repository for the specified project.

Parameters (2)

Name Type Description
project string Project unix name or integer database ID (route segment).
hash string Chunked-upload hash identifying the uploaded dump file.

Return: (none)

postScm

Update the SCM configuration for the specified project.

Parameters (13)

Name Type Description
id string Project unix name or integer database ID.
useSsh bool Whether SSH access is enabled.
anonymousRead bool Whether anonymous read access is enabled.
requireTrackerItemId bool Whether commits must reference a tracker item ID.
mailCommits bool Whether commit notifications are e-mailed.
validateEmail bool Whether committer e-mail addresses are validated (git only).
requireAssignment bool Whether commits must be assigned to a tracker item.
requireMessage bool Whether a commit message is required (svn/cvs only).
requireConventionalCommit bool Whether conventional-commit format is enforced (git only).
restrictAssocCurrentProject bool Whether commit associations are restricted to the current project.
enableLFS bool Whether Git LFS is enabled (git only).
accessText string Custom access instructions shown to users.
browseText string Custom browse instructions shown to users.

Return: \gforge\plugins\scm\models\api\ScmBasic

Name Type Description
unixName string
scmType string
defaultBranchName string
hostName string
options \stdClass for settings on the scm repo Fields:
  • useSsh: If true, then ssh access is enabled for this repository.
  • anonymousRead: If true, then anonymous users can read the repository.
  • requireTrackerItem: If true, then all commits must reference a Tracker Item ID.
  • validateEmail: If true, then all committer emails must belong to an authorized GForge user.
  • mailCommits: If true, then project members will receive email notifications about commits.
  • requireConventionalCommit: If true, then all commits must follow the Conventional Commits specification.
  • accessText: Optional custom text to be shown in the SCM access UI section.
  • browseText: Optional custom text to be shown in the SCM browse UI section.

PUT

putLfs

Accept a raw PUT upload of a Git LFS object and persist it for the specified project.

Parameters (2)

Name Type Description
id string Project unix name or integer database ID (route segment).
oid string SHA-256 OID of the LFS object being uploaded (route segment).

Return: void

putSshKeys

Trigger a full rebuild of SSH authorised-keys files for all users. Site admin only.

Parameters (1)

Name Type Description
id string Non-empty site-scoped identifier (required but not used beyond validation).

Return: (none)

DELETE

deleteAcl

Delete a single SCM module ACL entry by its database ID.

Parameters (2)

Name Type Description
project string Project unix name or integer database ID (route segment).
module_id int Database ID of the SCM module record to delete (route segment).

Return: (none)

deleteAssociation

Remove the association between a commit and a tracker item in the specified project.

Parameters (3)

Name Type Description
id string Project unix name or integer database ID (route segment).
commitHash string Full commit hash whose association should be removed.
trackerItemId int Database ID of the tracker item to disassociate.

Return: (none)