dario_swain / stash-api
REST-ish endpoint for interacting with Stash
Requires
- php: >=5.4.0
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- apimatic/jsonmapper: ~1.2.0
- mashape/unirest-php: ~3.0.1
Requires (Dev)
This package is not auto-updated.
Last update: 2024-10-04 18:47:30 UTC
README
UNSTABLE - under heavy development.
About
Auto-generated PHP client for Stash API. Was generated using APIMATIC, based on Stash official WADL definition.
Getting started
How to Build
The generated code has dependencies over external libraries like UniRest. These dependencies are defined in the composer.json
file that comes with the SDK.
To resolve these dependencies, we use the Composer package manager which requires PHP greater than 5.3.2 installed in your system.
Visit https://getcomposer.org/download/ to download the installer file for Composer and run it in your system.
Open command prompt and type composer --version
. This should display the current version of the Composer installed if the installation was successful.
- Using command line, navigate to the directory containing the generated files (including
composer.json
) for the SDK. - Run the command
composer install
. This should install all the required dependencies and create thevendor
directory in your project directory.
[For Windows Users Only] Configuring CURL Certificate Path in php.ini
CURL used to include a list of accepted CAs, but no longer bundles ANY CA certs. So by default it will reject all SSL certificates as unverifiable. You will have to get your CA's cert and point curl at it. The steps are as follows:
- Download the certificate bundle (.pem file) from https://curl.haxx.se/docs/caextract.html on to your system.
- Add curl.cainfo = "PATH_TO/cacert.pem" to your php.ini file located in your php installation. “PATH_TO” must be an absolute path containing the .pem file.
[curl] ; A default value for the CURLOPT_CAINFO option. This is required to be an ; absolute path. ;curl.cainfo =
How to Use
The following section explains how to use the StashAPILib library in a new project.
1. Open Project in an IDE
Open an IDE for PHP like PhpStorm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.
Click on Open
in PhpStorm to browse to your generated SDK directory and then click OK
.
2. Add a new Test Project
Create a new directory by right clicking on the solution name as shown below:
Name the directory as "test"
Add a PHP file to this project
Name it "testSDK"
Depending on your project setup, you might need to include composer's autoloader in your PHP code to enable auto loading of classes.
require_once "../vendor/autoload.php";
It is important that the path inside require_once correctly points to the file autoload.php
inside the vendor directory created during dependency installations.
After this you can add code to initialize the client library and acquire the instance of a Controller class. Sample code to initialize the client library and using controller methods is given in the subsequent sections.
3. Run the Test Project
To run your project you must set the Interpreter for your project. Interpreter is the PHP engine installed on your computer.
Open Settings
from File
menu.
Select PHP
from within Languages & Frameworks
Browse for Interpreters near the Interpreter
option and choose your interpreter.
Once the interpreter is selected, click OK
To run your project, right click on your PHP file inside your Test project and click on Run
How to Test
Unit tests in this SDK can be run using PHPUnit.
- First install the dependencies using composer including the
require-dev
dependencies. - Run
vendor\bin\phpunit --verbose
from commandline to execute tests. If you have installed PHPUnit globally, run tests usingphpunit --verbose
instead.
You can change the PHPUnit test configuration in the phpunit.xml
file.
Initialization
Authentication
In order to setup authentication and initialization of the API client, you need the following information.
API client can be initialized as following.
// Configuration parameters and credentials $stashDomain = "stashDomain"; $basicAuthUserName = "basicAuthUserName"; // The username to use with basic authentication $basicAuthPassword = "basicAuthPassword"; // The password to use with basic authentication $client = new StashAPILib\StashAPILibClient($stashDomain, $basicAuthUserName, $basicAuthPassword);
Class Reference
List of Controllers
- RepositoryController
- AdminController
- PullRequestController
- HookController
- ProjectController
- TaskController
- GroupController
- ProfileController
- ApplicationController
- LogController
- UserController
- MarkupController
RepositoryController
Get singleton instance
The singleton instance of the RepositoryController
class can be accessed from the API Client.
$repository = $client->getRepository();
getRepositoryCommitChanges
Retrieve a page of changes made in a specified commit.
Note: The implementation will apply a hard cap ({@code page.max.changes}) and it is not possible to request subsequent content when that cap is exceeded.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryCommitChanges( $projectKey, $repositorySlug, $commitId, $since = null, $withComments = true)
Parameters
If not specified the commit's first parent is assumed (if one exists) |
| withComments | Optional
DefaultValue
| {@code true} to apply comment counts in the changes (the default); otherwise, {@code false}
to stream changes without comment counts |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $since = 'since'; $withComments = true; $result = $repository->getRepositoryCommitChanges($projectKey, $repositorySlug, $commitId, $since, $withComments);
getRepositoryCompareDiffByPath
Gets a diff of the changes available in the {@code from} changeset but not in the {@code to} changeset.
If either the {@code from} or {@code to} changeset are not specified, they will be replaced by the default branch of their containing repository.
function getRepositoryCompareDiffByPath( $projectKey, $repositorySlug, $path, $from = null, $to = null, $fromRepo = null, $srcPath = null, $contextLines = -1, $whitespace = null)
Parameters
if that changeset is not present in the current repository; the repository can be specified
by either its ID <em>fromRepo=42</em> or by its project key plus its repo slug separated by
a slash: <em>fromRepo=projectKey/repoSlug</em> |
| srcPath | Optional
| TODO: Add a parameter description |
| contextLines | Optional
DefaultValue
| an optional number of context lines to include around each added or removed lines in the diff |
| whitespace | Optional
| an optional whitespace flag which can be set to ignore-all
|
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $path = 'path'; $from = 'from'; $to = 'to'; $fromRepo = 'fromRepo'; $srcPath = 'srcPath'; $contextLines = -1; $whitespace = 'whitespace'; $result = $repository->getRepositoryCompareDiffByPath($projectKey, $repositorySlug, $path, $from, $to, $fromRepo, $srcPath, $contextLines, $whitespace);
getRepositoryCompareChanges
Gets the file changes available in the {@code from} changeset but not in the {@code to} changeset.
If either the {@code from} or {@code to} changeset are not specified, they will be replaced by the default branch of their containing repository.
function getRepositoryCompareChanges( $projectKey, $repositorySlug, $from = null, $to = null, $fromRepo = null)
Parameters
if that changeset is not present in the current repository; the repository can be specified
by either its ID <em>fromRepo=42</em> or by its project key plus its repo slug separated by
a slash: <em>fromRepo=projectKey/repoSlug</em> |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $from = 'from'; $to = 'to'; $fromRepo = 'fromRepo'; $result = $repository->getRepositoryCompareChanges($projectKey, $repositorySlug, $from, $to, $fromRepo);
getRepositoryCompareCommits
Gets the commits accessible from the {@code from} changeset but not in the {@code to} changeset.
If either the {@code from} or {@code to} changeset are not specified, they will be replaced by the default branch of their containing repository.
function getRepositoryCompareCommits( $projectKey, $repositorySlug, $from = null, $to = null, $fromRepo = null)
Parameters
if that changeset is not present in the current repository; the repository can be specified
by either its ID <em>fromRepo=42</em> or by its project key plus its repo slug separated by
a slash: <em>fromRepo=projectKey/repoSlug</em> |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $from = 'from'; $to = 'to'; $fromRepo = 'fromRepo'; $result = $repository->getRepositoryCompareCommits($projectKey, $repositorySlug, $from, $to, $fromRepo);
getRepositoryBranches
Retrieve the branches matching the supplied filterText param.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryBranches( $projectKey, $repositorySlug, $base = null, $details = null, $filterText = null, $orderBy = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $base = 'base'; $details = false; $filterText = 'filterText'; $orderBy = 'orderBy'; $result = $repository->getRepositoryBranches($projectKey, $repositorySlug, $base, $details, $filterText, $orderBy);
getRepositoryDefaultBranch
Get the default branch of the repository.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryDefaultBranch( $projectKey, $repositorySlug)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $result = $repository->getRepositoryDefaultBranch($projectKey, $repositorySlug);
updateSetRepositoryDefaultBranch
Update the default branch of a repository.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function updateSetRepositoryDefaultBranch( $dynamic, $projectKey, $repositorySlug)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $result = $repository->updateSetRepositoryDefaultBranch($dynamic, $projectKey, $repositorySlug);
updateSetRepositoryPermissionForGroup
Promote or demote a group's permission level for the specified repository. Available repository permissions are:
See the Stash documentation for a detailed explanation of what each permission entails.
- REPO_READ
- REPO_WRITE
- REPO_ADMIN
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.
function updateSetRepositoryPermissionForGroup( $projectKey, $repositorySlug, $permission = null, $name = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $permission = 'permission'; $name = 'name'; $result = $repository->updateSetRepositoryPermissionForGroup($projectKey, $repositorySlug, $permission, $name);
getRepositoryGroupsWithAnyPermission
Retrieve a page of groups that have been granted at least one permission for the specified repository.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
function getRepositoryGroupsWithAnyPermission( $projectKey, $repositorySlug, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $filter = 'filter'; $result = $repository->getRepositoryGroupsWithAnyPermission($projectKey, $repositorySlug, $filter);
deleteRevokeRepositoryPermissionsForGroup
Revoke all permissions for the specified repository for a group.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.
function deleteRevokeRepositoryPermissionsForGroup( $projectKey, $repositorySlug, $name = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $name = 'name'; $result = $repository->deleteRevokeRepositoryPermissionsForGroup($projectKey, $repositorySlug, $name);
updateSetRepositoryPermissionForUser
Promote or demote a user's permission level for the specified repository. Available repository permissions are:
See the Stash documentation for a detailed explanation of what each permission entails.
- REPO_READ
- REPO_WRITE
- REPO_ADMIN
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a project or global permission that already implies that permission.
function updateSetRepositoryPermissionForUser( $projectKey, $repositorySlug, $name = null, $permission = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $name = 'name'; $permission = 'permission'; $result = $repository->updateSetRepositoryPermissionForUser($projectKey, $repositorySlug, $name, $permission);
getRepositoryUsersWithAnyPermission
Retrieve a page of users that have been granted at least one permission for the specified repository.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
function getRepositoryUsersWithAnyPermission( $projectKey, $repositorySlug, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $filter = 'filter'; $result = $repository->getRepositoryUsersWithAnyPermission($projectKey, $repositorySlug, $filter);
deleteRevokeRepositoryPermissionsForUser
Revoke all permissions for the specified repository for a user.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
In addition, a user may not revoke their own repository permissions if they do not have a higher project or global permission.
function deleteRevokeRepositoryPermissionsForUser( $projectKey, $repositorySlug, $name = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $name = 'name'; $result = $repository->deleteRevokeRepositoryPermissionsForUser($projectKey, $repositorySlug, $name);
getRepositoryGroupsWithoutAnyPermission
Retrieve a page of groups that have no granted permissions for the specified repository.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
function getRepositoryGroupsWithoutAnyPermission( $projectKey, $repositorySlug, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $filter = 'filter'; $result = $repository->getRepositoryGroupsWithoutAnyPermission($projectKey, $repositorySlug, $filter);
getRepositoryUsersWithoutPermission
Retrieve a page of licensed users that have no granted permissions for the specified repository.
The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.
function getRepositoryUsersWithoutPermission( $projectKey, $repositorySlug, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $filter = 'filter'; $result = $repository->getRepositoryUsersWithoutPermission($projectKey, $repositorySlug, $filter);
getRepositoryCommits
Retrieve a page of commits from a given starting commit or "between" two commits. If no explicit commit is specified, the tip of the repository's default branch is assumed. commits may be identified by branch or tag name or by ID. A path may be supplied to restrict the returned commits to only those which affect that path.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryCommits( $projectKey, $repositorySlug, $path = null, $since = null, $until = null, $withCounts = false)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $path = 'path'; $since = 'since'; $until = 'until'; $withCounts = false; $result = $repository->getRepositoryCommits($projectKey, $repositorySlug, $path, $since, $until, $withCounts);
getRepositoryCommit
Retrieve a single commit identified by its ID>. In general, that ID is a SHA1. From 2.11, ref names like "refs/heads/master" are no longer accepted by this resource.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryCommit( $projectKey, $repositorySlug, $commitId, $path = null)
Parameters
be for the specified commit. Instead, starting from the specified commit, they will be the
details for the first commit affecting the specified path. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $path = 'path'; $result = $repository->getRepositoryCommit($projectKey, $repositorySlug, $commitId, $path);
getRepositoryTags
Retrieve the tags matching the supplied filterText param.
The authenticated user must have REPO_READ permission for the context repository to call this resource.
function getRepositoryTags( $projectKey, $repositorySlug, $filterText = null, $orderBy = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $filterText = 'filterText'; $orderBy = 'orderBy'; $result = $repository->getRepositoryTags($projectKey, $repositorySlug, $filterText, $orderBy);
getRepositories
Retrieve a page of repositories based on query parameters that control the search. See the documentation of the parameters for more details.
This resource is anonymously accessible.
Note on permissions. In absence of the {@code permission} query parameter the implicit 'read' permission is assumed. Please note that this permission is lower than the REPO_READ permission rather than being equal to it. The implicit 'read' permission for a given repository is assigned to any user that has any of the higher permissions, such as , as well as to anonymous users if the repository is marked as public. The important implication of the above is that an anonymous request to this resource with a permission level is guaranteed to receive an empty list of repositories as a result. For anonymous requests it is therefore recommended to not specify the parameter at all.
function getRepositories( $name = null, $projectname = null, $permission = null, $visibility = null)
Parameters
matches this parameter's value. The match will be done case-insensitive and any leading
and/or trailing whitespace characters on the <code>name</code> parameter will be stripped. |
| projectname | Optional
| (optional) if specified, this will limit the resulting repository list to ones whose project's
name matches this parameter's value. The match will be done case-insensitive and any leading
and/or trailing whitespace characters on the projectname
parameter will
be stripped. |
| permission | Optional
| (optional) if specified, it must be a valid repository permission level name and will limit
the resulting repository list to ones that the requesting user has the specified permission
level to. If not specified, the default implicit 'read' permission level will be assumed. The
currently supported explicit permission values are ,
and . |
| visibility | Optional
| (optional) if specified, this will limit the resulting repository list based on the
repositories visibility. Valid values are public or private. |
Example Usage
$name = 'name'; $projectname = 'projectname'; $permission = 'permission'; $visibility = 'visibility'; $result = $repository->getRepositories($name, $projectname, $permission, $visibility);
listRepositoryFiles
Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function listRepositoryFiles( $projectKey, $repositorySlug, $at = null)
Parameters
If not specified the default branch will be used instead. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $at = 'at'; $result = $repository->listRepositoryFiles($projectKey, $repositorySlug, $at);
listRepositoryFilesByPath
Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function listRepositoryFilesByPath( $projectKey, $repositorySlug, $path, $at = null)
Parameters
If not specified the default branch will be used instead. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $path = 'path'; $at = 'at'; $result = $repository->listRepositoryFilesByPath($projectKey, $repositorySlug, $path, $at);
createRepository
Create a new repository. Requires an existing project in which this repository will be created. The only parameters which will be used are name and scmId.
The authenticated user must have PROJECT_ADMIN permission for the context project to call this resource.
function createRepository( $dynamic, $projectKey)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $result = $repository->createRepository($dynamic, $projectKey);
deleteRepository
Schedule the repository matching the supplied projectKey and repositorySlug to be deleted. If the request repository is not present
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function deleteRepository( $repositorySlug, $projectKey)
Parameters
Example Usage
$repositorySlug = 'repositorySlug'; $projectKey = 'projectKey'; $result = $repository->deleteRepository($repositorySlug, $projectKey);
createForkRepository
Create a new repository forked from an existing repository.
The JSON body for this {@code POST} is not required to contain any properties. Even the name may be omitted. The following properties will be used, if provided:
- {@code "name":"Fork name"} - Specifies the forked repository's name
- Defaults to the name of the origin repository if not specified
- {@code "project":{"key":"TARGET_KEY"}} - Specifies the forked repository's target project by key
- Defaults to the current user's personal project if not specified
The authenticated user must have REPO_READ permission for the specified repository and PROJECT_ADMIN on the target project to call this resource. Note that users always have PROJECT_ADMIN permission on their personal projects.
function createForkRepository( $dynamic, $repositorySlug, $projectKey)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $repositorySlug = 'repositorySlug'; $projectKey = 'projectKey'; $result = $repository->createForkRepository($dynamic, $repositorySlug, $projectKey);
getRepository
Retrieve the repository matching the supplied projectKey and repositorySlug.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepository( $repositorySlug, $projectKey)
Parameters
Example Usage
$repositorySlug = 'repositorySlug'; $projectKey = 'projectKey'; $result = $repository->getRepository($repositorySlug, $projectKey);
updateRepository
Update the repository matching the repositorySlug supplied in the resource path.
The repository's slug is derived from its name. If the name changes the slug may also change.
This API can be used to move the repository to a different project by setting the new project in the request, example: {@code {"project":{"key":"NEW_KEY"}}} .
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function updateRepository( $dynamic, $repositorySlug, $projectKey)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $repositorySlug = 'repositorySlug'; $projectKey = 'projectKey'; $result = $repository->updateRepository($dynamic, $repositorySlug, $projectKey);
getForkedRepositories
Retrieve repositories which have been forked from this one. Unlike {@link #getRelatedRepositories(Repository, PageRequest) related repositories}, this only looks at a given repository's direct forks. If those forks have themselves been the origin of more forks, such "grandchildren" repositories will not be retrieved.
Only repositories to which the authenticated user has REPO_READ permission will be included, even if other repositories have been forked from this one.
function getForkedRepositories( $projectKey, $repositorySlug)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $result = $repository->getForkedRepositories($projectKey, $repositorySlug);
getRelatedRepositories
Retrieve repositories which are related to this one. Related repositories are from the same {@link Repository#getHierarchyId() hierarchy} as this repository.
Only repositories to which the authenticated user has REPO_READ permission will be included, even if more repositories are part of this repository's hierarchy.
function getRelatedRepositories( $projectKey, $repositorySlug)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $result = $repository->getRelatedRepositories($projectKey, $repositorySlug);
createRetryCreateRepository
If a create or fork operation fails, calling this method will clean up the broken repository and try again. The repository must be in an INITIALISATION_FAILED state.
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
function createRetryCreateRepository( $projectKey, $repositorySlug)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $result = $repository->createRetryCreateRepository($projectKey, $repositorySlug);
getRepositoryShowDiff
Retrieve the diff for a specified file path between two provided revisions.
Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more
truncated
flags will be set totrue
on the segments, hunks and diffs substructures in the returned JSON response.The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryShowDiff( $projectKey, $repositorySlug, $contextLines = -1, $since = null, $srcPath = null, $until = null, $whitespace = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $contextLines = -1; $since = 'since'; $srcPath = 'srcPath'; $until = 'until'; $whitespace = 'whitespace'; $result = $repository->getRepositoryShowDiff($projectKey, $repositorySlug, $contextLines, $since, $srcPath, $until, $whitespace);
getRepositoryShowDiffByPath
Retrieve the diff for a specified file path between two provided revisions.
Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more
truncated
flags will be set totrue
on the segments, hunks and diffs substructures in the returned JSON response.The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryShowDiffByPath( $projectKey, $repositorySlug, $path, $contextLines = -1, $since = null, $srcPath = null, $until = null, $whitespace = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $path = 'path'; $contextLines = -1; $since = 'since'; $srcPath = 'srcPath'; $until = 'until'; $whitespace = 'whitespace'; $result = $repository->getRepositoryShowDiffByPath($projectKey, $repositorySlug, $path, $contextLines, $since, $srcPath, $until, $whitespace);
getRepositoryContent
Retrieve a page of content for a file path at a specified revision.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryContent( $projectKey, $repositorySlug, $at = null, $type = false, $blame = null, $noContent = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $at = 'at'; $type = false; $blame = 'blame'; $noContent = 'noContent'; $result = $repository->getRepositoryContent($projectKey, $repositorySlug, $at, $type, $blame, $noContent);
getRepositoryContentByPath
Retrieve a page of content for a file path at a specified revision.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryContentByPath( $projectKey, $repositorySlug, $path, $at = null, $type = false, $blame = null, $noContent = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $path = 'path'; $at = 'at'; $type = false; $blame = 'blame'; $noContent = 'noContent'; $result = $repository->getRepositoryContentByPath($projectKey, $repositorySlug, $path, $at, $type, $blame, $noContent);
createRepositoryCommitComment
Add a new comment.
Comments can be added in a few places by setting different attributes:
General commit comment:
{ "text": "An insightful general comment on a commit." }Reply to a comment:
{ "text": "A measured reply.", "parent": { "id": 1 } }General file comment:
{ "text": "An insightful general comment on a file.", "anchor": { "path": "path/to/file", "srcPath": "path/to/file" } }File line comment:
{ "text": "A pithy comment on a particular line within a file.", "anchor": { "line": 1, "lineType": "CONTEXT", "fileType": "FROM" "path": "path/to/file", "srcPath": "path/to/file" } }Note: general file comments are an experimental feature and may change in the near future!
For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves).
For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
- 'ADDED' - for an added line;
- 'REMOVED' - for a removed line; or
- 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
If the current user is not a participant the user is added as one and updated to watch the commit.
- 'FROM' - the source file of the diff
- 'TO' - the destination file of the diff
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.
function createRepositoryCommitComment( $dynamic, $projectKey, $repositorySlug, $commitId, $since = null)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $since = 'since'; $result = $repository->createRepositoryCommitComment($dynamic, $projectKey, $repositorySlug, $commitId, $since);
getRepositoryCommitComments
TODO: Add a method description
function getRepositoryCommitComments( $projectKey, $repositorySlug, $commitId, $path = null, $since = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $path = 'path'; $since = 'since'; $result = $repository->getRepositoryCommitComments($projectKey, $repositorySlug, $commitId, $path, $since);
updateRepositoryCommitComment
Update the text of a comment. Only the user who created a comment may update it.
Note: the supplied supplied JSON object must contain a
version
that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.
function updateRepositoryCommitComment( $dynamic, $projectKey, $repositorySlug, $commitId, $commentId)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $commentId = 51; $result = $repository->updateRepositoryCommitComment($dynamic, $projectKey, $repositorySlug, $commitId, $commentId);
deleteRepositoryCommitComment
Delete a commit comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users. Comments which have replies may not be deleted, regardless of the user's granted permissions.
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.
function deleteRepositoryCommitComment( $projectKey, $repositorySlug, $commitId, $commentId, $version = -1)
Parameters
the delete will fail. To determine the current version of the comment, the comment should be
fetched from the server prior to the delete. Look for the 'version' attribute in the returned
JSON structure. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $commentId = 51; $version = -1; $result = $repository->deleteRepositoryCommitComment($projectKey, $repositorySlug, $commitId, $commentId, $version);
getRepositoryCommitComment
Retrieves a commit discussion comment.
The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.
function getRepositoryCommitComment( $projectKey, $repositorySlug, $commitId, $commentId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $commentId = 51; $result = $repository->getRepositoryCommitComment($projectKey, $repositorySlug, $commitId, $commentId);
getRepositoryHooks
Retrieve a page of repository hooks for this repository.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function getRepositoryHooks( $projectKey, $repositorySlug, $type = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $type = 'type'; $result = $repository->getRepositoryHooks($projectKey, $repositorySlug, $type);
updateSetRepositoryHookSettings
Modify the settings for a repository hook for this repositories.
The service will reject any settings which are too large, the current limit is 32KB once serialized.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function updateSetRepositoryHookSettings( $dynamic, $projectKey, $repositorySlug, $hookKey)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $hookKey = 'hookKey'; $result = $repository->updateSetRepositoryHookSettings($dynamic, $projectKey, $repositorySlug, $hookKey);
getRepositoryHookSettings
Retrieve the settings for a repository hook for this repositories.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function getRepositoryHookSettings( $projectKey, $repositorySlug, $hookKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $hookKey = 'hookKey'; $result = $repository->getRepositoryHookSettings($projectKey, $repositorySlug, $hookKey);
getRepositoryHook
Retrieve a repository hook for this repositories.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function getRepositoryHook( $projectKey, $repositorySlug, $hookKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $hookKey = 'hookKey'; $result = $repository->getRepositoryHook($projectKey, $repositorySlug, $hookKey);
updateEnableRepositoryHook
Enable a repository hook for this repositories and optionally applying new configuration.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function updateEnableRepositoryHook( $projectKey, $repositorySlug, $hookKey, $contentLength = 0)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $hookKey = 'hookKey'; $contentLength = 0; $result = $repository->updateEnableRepositoryHook($projectKey, $repositorySlug, $hookKey, $contentLength);
deleteDisableRepositoryHook
Disable a repository hook for this repositories.
The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.
function deleteDisableRepositoryHook( $projectKey, $repositorySlug, $hookKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $hookKey = 'hookKey'; $result = $repository->deleteDisableRepositoryHook($projectKey, $repositorySlug, $hookKey);
getRepositoryChanges
Retrieve a page of changes made in a specified commit.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryChanges( $projectKey, $repositorySlug, $since = null, $until = null)
Parameters
If not specified the commit's first parent is assumed (if one exists) |
| until | Optional
| the commit to retrieve changes for |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $since = 'since'; $until = 'until'; $result = $repository->getRepositoryChanges($projectKey, $repositorySlug, $since, $until);
deleteUnwatchRepositoryCommit
Removes the authenticated user as a watcher for the specified commit.
The authenticated user must have REPO_READ permission for the repository containing the commit to call this resource.
function deleteUnwatchRepositoryCommit( $projectKey, $repositorySlug, $commitId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $result = $repository->deleteUnwatchRepositoryCommit($projectKey, $repositorySlug, $commitId);
createWatchRepositoryCommit
Adds the authenticated user as a watcher for the specified commit.
The authenticated user must have REPO_READ permission for the repository containing the commit to call this resource.
function createWatchRepositoryCommit( $projectKey, $repositorySlug, $commitId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $result = $repository->createWatchRepositoryCommit($projectKey, $repositorySlug, $commitId);
getRepositoryCommitDiff
Retrieve the diff between two provided revisions.
Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more
truncated
flags will be set totrue
on the segments, hunks and diffs substructures in the returned JSON response.The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryCommitDiff( $projectKey, $repositorySlug, $commitId, $contextLines = -1, $since = null, $srcPath = null, $whitespace = null, $withComments = true)
Parameters
to stream the diff without comments |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $commitId = 'commitId'; $contextLines = -1; $since = 'since'; $srcPath = 'srcPath'; $whitespace = 'whitespace'; $withComments = true; $result = $repository->getRepositoryCommitDiff($projectKey, $repositorySlug, $commitId, $contextLines, $since, $srcPath, $whitespace, $withComments);
getRepositoryCommitDiffByPath
Retrieve the diff between two provided revisions.
Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more
truncated
flags will be set totrue
on the segments, hunks and diffs substructures in the returned JSON response.The authenticated user must have REPO_READ permission for the specified repository to call this resource.
function getRepositoryCommitDiffByPath( $projectKey, $repositorySlug, $path, $commitId, $contextLines = -1, $since = null, $srcPath = null, $whitespace = null, $withComments = true)
Parameters
to stream the diff without comments |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $path = 'path'; $commitId = 'commitId'; $contextLines = -1; $since = 'since'; $srcPath = 'srcPath'; $whitespace = 'whitespace'; $withComments = true; $result = $repository->getRepositoryCommitDiffByPath($projectKey, $repositorySlug, $path, $commitId, $contextLines, $since, $srcPath, $whitespace, $withComments);
getRepositories1
Retrieve repositories from the project corresponding to the supplied projectKey.
The authenticated user must have REPO_READ permission for the specified project to call this resource.
function getRepositories1($projectKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $result = $repository->getRepositories1($projectKey);
AdminController
Get singleton instance
The singleton instance of the AdminController
class can be accessed from the API Client.
$admin = $client->getAdmin();
getClusterInformation
Gets information about the nodes that currently make up the stash cluster.
The authenticated user must have the SYS_ADMIN permission to call this resource.
function getClusterInformation()
Example Usage
$result = $admin->getClusterInformation();
updateLicense
Decodes the provided encoded license and sets it as the active license. If no license was provided, a 400 is returned. If the license cannot be decoded, or cannot be applied, a 409 is returned. Some possible reasons a license may not be applied include:
Otherwise, if the license is updated successfully, details for the new license are returned with a 200 response.
- It is for a different product
- It is already expired
Warning: It is possible to downgrade the license during update, applying a license with a lower number of permitted users. If the number of currently-licensed users exceeds the limits of the new license, pushing will be disabled until the licensed user count is brought into compliance with the new license.
The authenticated user must have SYS_ADMIN permission. ADMIN users may view the current license details, but they may not update the license.
function updateLicense($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->updateLicense($dynamic);
deleteMailConfig
Deletes the current mail configuration.
The authenticated user must have the SYS_ADMIN permission to call this resource.
function deleteMailConfig()
Example Usage
$result = $admin->deleteMailConfig();
getMailConfig
Retrieves the current mail configuration.
The authenticated user must have the SYS_ADMIN permission to call this resource.
function getMailConfig()
Example Usage
$result = $admin->getMailConfig();
updateSetMailConfig
Updates the mail configuration
The authenticated user must have the SYS_ADMIN permission to call this resource.
function updateSetMailConfig($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->updateSetMailConfig($dynamic);
deleteClearSenderAddress
Clears the server email address.
The authenticated user must have the ADMIN permission to call this resource.
function deleteClearSenderAddress()
Example Usage
$result = $admin->deleteClearSenderAddress();
getSenderAddress
Retrieves the server email address
function getSenderAddress()
Example Usage
$result = $admin->getSenderAddress();
updateSetSenderAddress
Updates the server email address
The authenticated user must have the ADMIN permission to call this resource.
function updateSetSenderAddress($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->updateSetSenderAddress($dynamic);
getUsersWithoutAnyPermission
Retrieve a page of users that have no granted global permissions.
The authenticated user must have ADMIN permission or higher to call this resource.
function getUsersWithoutAnyPermission($filter = null)
Parameters
Example Usage
$filter = 'filter'; $result = $admin->getUsersWithoutAnyPermission($filter);
getGroupsWithAnyPermission
Retrieve a page of groups that have been granted at least one global permission.
The authenticated user must have ADMIN permission or higher to call this resource.
function getGroupsWithAnyPermission($filter = null)
Parameters
Example Usage
$filter = 'filter'; $result = $admin->getGroupsWithAnyPermission($filter);
updateSetPermissionForGroups
Promote or demote a user's global permission level. Available global permissions are:
See the Stash documentation for a detailed explanation of what each permission entails.
- LICENSED_USER
- PROJECT_CREATE
- ADMIN
- SYS_ADMIN
The authenticated user must have:
to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.
- ADMIN permission or higher; and
- the permission they are attempting to grant or higher; and
- greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
function updateSetPermissionForGroups( $permission = null, $name = null)
Parameters
Example Usage
$permission = 'permission'; $name = 'name'; $result = $admin->updateSetPermissionForGroups($permission, $name);
deleteRevokePermissionsForGroup
Revoke all global permissions for a group.
The authenticated user must have:
to call this resource. In addition, a user may not revoke a group's permissions if their own permission level would be reduced as a result.
- ADMIN permission or higher; and
- greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
function deleteRevokePermissionsForGroup($name = null)
Parameters
Example Usage
$name = 'name'; $result = $admin->deleteRevokePermissionsForGroup($name);
getGroupsWithoutAnyPermission
Retrieve a page of groups that have no granted global permissions.
The authenticated user must have ADMIN permission or higher to call this resource.
function getGroupsWithoutAnyPermission($filter = null)
Parameters
Example Usage
$filter = 'filter'; $result = $admin->getGroupsWithoutAnyPermission($filter);
getUsersWithAnyPermission
Retrieve a page of users that have been granted at least one global permission.
The authenticated user must have ADMIN permission or higher to call this resource.
function getUsersWithAnyPermission($filter = null)
Parameters
Example Usage
$filter = 'filter'; $result = $admin->getUsersWithAnyPermission($filter);
updateSetPermissionForUsers
Promote or demote the global permission level of a user. Available global permissions are:
See the Stash documentation for a detailed explanation of what each permission entails.
- LICENSED_USER
- PROJECT_CREATE
- ADMIN
- SYS_ADMIN
The authenticated user must have:
to call this resource. In addition, a user may not demote their own permission level.
- ADMIN permission or higher; and
- the permission they are attempting to grant; and
- greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
function updateSetPermissionForUsers( $name = null, $permission = null)
Parameters
Example Usage
$name = 'name'; $permission = 'permission'; $result = $admin->updateSetPermissionForUsers($name, $permission);
deleteRevokePermissionsForUser
Revoke all global permissions for a user.
The authenticated user must have:
to call this resource. In addition, a user may not demote their own permission level.
- ADMIN permission or higher; and
- greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
function deleteRevokePermissionsForUser($name = null)
Parameters
Example Usage
$name = 'name'; $result = $admin->deleteRevokePermissionsForUser($name);
getUsers
Retrieve a page of users.
The authenticated user must have the LICENSED_USER permission to call this resource.
function getUsers($filter = null)
Parameters
string will be returned |
Example Usage
$filter = 'filter'; $result = $admin->getUsers($filter);
createUser
Creates a new user from the assembled query parameters.
The default group can be used to control initial permissions for new users, such as granting users the ability to login or providing read access to certain projects or repositories. If the user is not added to the default group, they may not be able to login after their account is created until explicit permissions are configured.
The authenticated user must have the ADMIN permission to call this resource.
function createUser( $name = null, $password = null, $displayName = null, $emailAddress = null, $addToDefaultGroup = true, $notify = null)
Parameters
a set of initial permissions; otherwise, <code>false</code> to not add them to a group |
| notify | Optional
| if present and not false
instead of requiring a password,
the create user will be notified via email their account has been created and requires
a password to be reset. This option can only be used if a mail server has been configured |
Example Usage
$name = 'name'; $password = 'password'; $displayName = 'displayName'; $emailAddress = 'emailAddress'; $addToDefaultGroup = true; $notify = 'notify'; $result = $admin->createUser($name, $password, $displayName, $emailAddress, $addToDefaultGroup, $notify);
deleteUser
Deletes the specified user, removing them from the system. This also removes any permissions that may have been granted to the user.
A user may not delete themselves, and a user with ADMIN permissions may not delete a user with SYS_ADMINpermissions.
The authenticated user must have the ADMIN permission to call this resource.
function deleteUser($name = null)
Parameters
Example Usage
$name = 'name'; $result = $admin->deleteUser($name);
updateUserDetails
Update a user's details.
The authenticated user must have the ADMIN permission to call this resource.
function updateUserDetails($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->updateUserDetails($dynamic);
createRenameUser
Rename a user.
The authenticated user must have the ADMIN permission to call this resource.
function createRenameUser($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->createRenameUser($dynamic);
deleteClearUserCaptchaChallenge
Clears any CAPTCHA challenge that may constrain the user with the supplied username when they authenticate. Additionally any counter or metric that contributed towards the user being issued the CAPTCHA challenge (for instance too many consecutive failed logins) will also be reset.
The authenticated user must have the ADMIN permission to call this resource, and may not clear the CAPTCHA of a user with greater permissions than themselves.
function deleteClearUserCaptchaChallenge($name = null)
Parameters
Example Usage
$name = 'name'; $result = $admin->deleteClearUserCaptchaChallenge($name);
deleteGroup
Deletes the specified group, removing them from the system. This also removes any permissions that may have been granted to the group.
A user may not delete the last group that is granting them administrative permissions, or a group with greater permissions than themselves.
The authenticated user must have the ADMIN permission to call this resource.
function deleteGroup($name = null)
Parameters
Example Usage
$name = 'name'; $result = $admin->deleteGroup($name);
createGroup
Create a new group.
The authenticated user must have ADMIN permission or higher to call this resource.
function createGroup($name = null)
Parameters
Example Usage
$name = 'name'; $result = $admin->createGroup($name);
getGroups
Retrieve a page of groups.
The authenticated user must have LICENSED_USER permission or higher to call this resource.
function getGroups($filter = null)
Parameters
Example Usage
$filter = 'filter'; $result = $admin->getGroups($filter);
addUserToGroup
Deprecated since 2.10 for removal in 4.0. Use {@code /rest/users/add-groups} instead.
Add a user to a group.
In the request entity, the context attribute is the group and the itemName is the user.
The authenticated user must have the ADMIN permission to call this resource.
function addUserToGroup($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->addUserToGroup($dynamic);
addGroupToUser
Deprecated since 2.10 for removal in 4.0. Use {@code /rest/users/add-groups} instead.
Add a user to a group. This is very similar to
groups/add-user
, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.In the request entity, the context attribute is the user and the itemName is the group.
The authenticated user must have the ADMIN permission to call this resource.
function addGroupToUser($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->addGroupToUser($dynamic);
addUsersToGroup
Add multiple users to a group.
The authenticated user must have the ADMIN permission to call this resource.
function addUsersToGroup($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->addUsersToGroup($dynamic);
addUserToGroups
Add a user to one or more groups.
The authenticated user must have the ADMIN permission to call this resource.
function addUserToGroups($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->addUserToGroups($dynamic);
createRemoveUserFromGroup
Deprecated since 2.10 for removal in 3.0. Use {@code /rest/users/remove-groups} instead.
Remove a user from a group.
The authenticated user must have the ADMIN permission to call this resource.
In the request entity, the context attribute is the group and the itemName is the user.
function createRemoveUserFromGroup($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->createRemoveUserFromGroup($dynamic);
createRemoveGroupFromUser
Remove a user from a group. This is very similar to
groups/remove-user
, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.In the request entity, the context attribute is the user and the itemName is the group.
The authenticated user must have the ADMIN permission to call this resource.
function createRemoveGroupFromUser($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->createRemoveGroupFromUser($dynamic);
findUsersInGroup
Retrieves a list of users that are members of a specified group.
The authenticated user must have the LICENSED_USER permission to call this resource.
function findUsersInGroup( $context = null, $filter = null)
Parameters
supplied string will be returned |
Example Usage
$context = 'context'; $filter = 'filter'; $result = $admin->findUsersInGroup($context, $filter);
findUsersNotInGroup
Retrieves a list of users that are not members of a specified group.
The authenticated user must have the LICENSED_USER permission to call this resource.
function findUsersNotInGroup( $context = null, $filter = null)
Parameters
supplied string will be returned |
Example Usage
$context = 'context'; $filter = 'filter'; $result = $admin->findUsersNotInGroup($context, $filter);
findGroupsForUser
Retrieves a list of groups the specified user is a member of.
The authenticated user must have the LICENSED_USER permission to call this resource.
function findGroupsForUser( $context = null, $filter = null)
Parameters
Example Usage
$context = 'context'; $filter = 'filter'; $result = $admin->findGroupsForUser($context, $filter);
findOtherGroupsForUser
Retrieves a list of groups the specified user is not a member of.
The authenticated user must have the LICENSED_USER permission to call this resource.
function findOtherGroupsForUser( $context = null, $filter = null)
Parameters
Example Usage
$context = 'context'; $filter = 'filter'; $result = $admin->findOtherGroupsForUser($context, $filter);
updateUserPassword
Update a user's password.
The authenticated user must have the ADMIN permission to call this resource, and may not update the password of a user with greater permissions than themselves.
function updateUserPassword($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $admin->updateUserPassword($dynamic);
getLicense
Retrieves details about the current license, as well as the current status of the system with regards to the installed license. The status includes the current number of users applied toward the license limit, as well as any status messages about the license (warnings about expiry or user counts exceeding license limits).
The authenticated user must have ADMIN permission. Unauthenticated users, and non-administrators, are not permitted to access license details.
function getLicense()
Example Usage
$result = $admin->getLicense();
PullRequestController
Get singleton instance
The singleton instance of the PullRequestController
class can be accessed from the API Client.
$pullRequest = $client->getPullRequest();
deleteUnwatchPullRequest
Make the authenticated user stop watching the specified pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function deleteUnwatchPullRequest( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->deleteUnwatchPullRequest($projectKey, $repositorySlug, $pullRequestId);
createWatchPullRequest
Make the authenticated user watch the specified pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function createWatchPullRequest( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->createWatchPullRequest($projectKey, $repositorySlug, $pullRequestId);
getPullRequestDiff
Streams a diff within a pull request.
If the specified file has been copied, moved or renamed, the
srcPath
must also be specified to produce the correct diff.Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequestDiff( $projectKey, $repositorySlug, $pullRequestId, $contextLines = -1, $srcPath = null, $whitespace = null, $withComments = true)
Parameters
to stream the diff without comments |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $contextLines = -1; $srcPath = 'srcPath'; $whitespace = 'whitespace'; $withComments = true; $result = $pullRequest->getPullRequestDiff($projectKey, $repositorySlug, $pullRequestId, $contextLines, $srcPath, $whitespace, $withComments);
getPullRequestDiffByPath
Streams a diff within a pull request.
If the specified file has been copied, moved or renamed, the
srcPath
must also be specified to produce the correct diff.Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequestDiffByPath( $projectKey, $repositorySlug, $pullRequestId, $path, $contextLines = -1, $srcPath = null, $whitespace = null, $withComments = true)
Parameters
to stream the diff without comments |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $path = 'path'; $contextLines = -1; $srcPath = 'srcPath'; $whitespace = 'whitespace'; $withComments = true; $result = $pullRequest->getPullRequestDiffByPath($projectKey, $repositorySlug, $pullRequestId, $path, $contextLines, $srcPath, $whitespace, $withComments);
getPullRequestCommits
Retrieve changesets for the specified pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequestCommits( $projectKey, $repositorySlug, $pullRequestId, $withCounts = null)
Parameters
"authorCount" is the number of different authors and "totalCount" is the total number of changesets. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $withCounts = true; $result = $pullRequest->getPullRequestCommits($projectKey, $repositorySlug, $pullRequestId, $withCounts);
getPullRequestTasks
Retrieve the tasks associated with a pull request.
function getPullRequestTasks( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $result = $pullRequest->getPullRequestTasks($projectKey, $repositorySlug, $pullRequestId);
getCountPullRequestTasks
Retrieve the total number of {@link com.atlassian.stash.task.TaskState#OPEN open} and {@link com.atlassian.stash.task.TaskState#RESOLVED resolved} tasks associated with a pull request.
function getCountPullRequestTasks( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $result = $pullRequest->getCountPullRequestTasks($projectKey, $repositorySlug, $pullRequestId);
createPullRequestComment
Add a new comment.
Comments can be added in a few places by setting different attributes:
General pull request comment:
{ "text": "An insightful general comment on a pull request." }Reply to a comment:
{ "text": "A measured reply.", "parent": { "id": 1 } }General file comment:
{ "text": "An insightful general comment on a file.", "anchor": { "path": "path/to/file", "srcPath": "path/to/file" } }File line comment:
{ "text": "A pithy comment on a particular line within a file.", "anchor": { "line": 1, "lineType": "CONTEXT", "fileType": "FROM" "path": "path/to/file", "srcPath": "path/to/file" } }Note: general file comments are an experimental feature and may change in the near future!
For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves).
For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
- 'ADDED' - for an added line;
- 'REMOVED' - for a removed line; or
- 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
If the current user is not a participant the user is added as a watcher of the pull request.
- 'FROM' - the source file of the diff
- 'TO' - the destination file of the diff
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function createPullRequestComment( $dynamic, $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->createPullRequestComment($dynamic, $projectKey, $repositorySlug, $pullRequestId);
getPullRequestComments
TODO: Add a method description
function getPullRequestComments( $projectKey, $repositorySlug, $pullRequestId, $path = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $path = 'path'; $result = $pullRequest->getPullRequestComments($projectKey, $repositorySlug, $pullRequestId, $path);
updatePullRequestComment
Update the text of a comment. Only the user who created a comment may update it.
Note: the supplied supplied JSON object must contain a
version
that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function updatePullRequestComment( $dynamic, $projectKey, $repositorySlug, $pullRequestId, $commentId)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $commentId = 234; $result = $pullRequest->updatePullRequestComment($dynamic, $projectKey, $repositorySlug, $pullRequestId, $commentId);
deletePullRequestComment
Delete a pull request comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function deletePullRequestComment( $projectKey, $repositorySlug, $pullRequestId, $commentId, $version = -1)
Parameters
the delete will fail. To determine the current version of the comment, the comment should be
fetched from the server prior to the delete. Look for the 'version' attribute in the
returned JSON structure. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $commentId = 234; $version = -1; $result = $pullRequest->deletePullRequestComment($projectKey, $repositorySlug, $pullRequestId, $commentId, $version);
getPullRequestComment
Retrieves a pull request comment.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequestComment( $projectKey, $repositorySlug, $pullRequestId, $commentId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $commentId = 234; $result = $pullRequest->getPullRequestComment($projectKey, $repositorySlug, $pullRequestId, $commentId);
getPullRequestChanges
Gets changes for the specified PullRequest.
Note: This resource is currently not paged. The server will return at most one page. The server will truncate the number of changes to either the request's page limit or an internal maximum, whichever is smaller. The start parameter of the page request is also ignored.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequestChanges( $projectKey, $repositorySlug, $pullRequestId, $withComments = true)
Parameters
to stream changes without comment counts |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $withComments = true; $result = $pullRequest->getPullRequestChanges($projectKey, $repositorySlug, $pullRequestId, $withComments);
getPullRequests
Retrieve a page of pull requests to or from the specified repository.
The authenticated user must have REPO_READ permission for the specified repository to call this resource.
Optionally clients can specify PR participant filters. Each filter has a mandatory {@code username.N} parameter, and the optional {@code role.N} and {@code approved.N} parameters.
- {@code username.N} - the "root" of a single participant filter, where "N" is a natural number starting from 1. This allows clients to specify multiple participant filters, by providing consecutive filters as {@code username.1}, {@code username.2} etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of participant filters is 10 and all filters exceeding that limit will be dropped.
- {@code role.N}(optional) the role associated with {@code username.N}. This must be one of {@code AUTHOR}, {@code REVIEWER}, or{@code PARTICIPANT}
- {@code approved.N}(optional) the approved status associated with {@code username.N}. That is whether {@code username.N} has approved the PR. Either {@code true}, or {@code false}
function getPullRequests( $projectKey, $repositorySlug, $direction = 'incoming', $at = null, $state = null, $order = null, $withAttributes = true, $withProperties = true)
Parameters
repository. Either <strong>INCOMING</strong> or <strong>OUTGOING</strong>. |
| at | Optional
| (optional) a fully-qualified branch ID to find pull requests to or from,
such as {@code refs/heads/master} |
| state | Optional
| (optional, defaults to OPEN). Supply ALL to return pull request
in any state. If a state is supplied only pull requests in the specified state will be returned.
Either OPEN, DECLINED or MERGED. |
| order | Optional
| (optional) the order to return pull requests in, either OLDEST (as in: "oldest
first") or NEWEST. |
| withAttributes | Optional
DefaultValue
| (optional) defaults to true, whether to return additional pull request attributes |
| withProperties | Optional
DefaultValue
| (optional) defaults to true, whether to return additional pull request properties |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $direction = 'incoming'; $at = 'at'; $state = 'state'; $order = 'order'; $withAttributes = true; $withProperties = true; $result = $pullRequest->getPullRequests($projectKey, $repositorySlug, $direction, $at, $state, $order, $withAttributes, $withProperties);
Errors
createDeclinePullRequest
Decline a pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function createDeclinePullRequest( $projectKey, $repositorySlug, $pullRequestId, $version = -1)
Parameters
version the operation will fail. To determine the current version of the pull request it should be
fetched from the server prior to this operation. Look for the 'version' attribute in the returned
JSON structure. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $version = -1; $result = $pullRequest->createDeclinePullRequest($projectKey, $repositorySlug, $pullRequestId, $version);
getPullRequestActivities
Retrieve a page of activity associated with a pull request.
Activity items include comments, approvals, rescopes (i.e. adding and removing of commits), merges and more.
Different types of activity items may be introduced in newer versions of Stash or by user installed plugins, so clients should be flexible enough to handle unexpected entity shapes in the returned page.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequestActivities( $projectKey, $repositorySlug, $pullRequestId, $fromId = null, $fromType = null)
Parameters
<strong>fromId</strong> (either <strong>COMMENT</strong> or <strong>ACTIVITY</strong>) |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $fromId = 234; $fromType = 'fromType'; $result = $pullRequest->getPullRequestActivities($projectKey, $repositorySlug, $pullRequestId, $fromId, $fromType);
createReopenPullRequest
Re-open a declined pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function createReopenPullRequest( $projectKey, $repositorySlug, $pullRequestId, $version = -1)
Parameters
version the operation will fail. To determine the current version of the pull request it should be
fetched from the server prior to this operation. Look for the 'version' attribute in the returned
JSON structure. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $version = -1; $result = $pullRequest->createReopenPullRequest($projectKey, $repositorySlug, $pullRequestId, $version);
getCanMergePullRequest
Test whether a pull request can be merged.
A pull request may not be merged if:
- there are conflicts that need to be manually resolved before merging; and/or
- one or more merge checks have vetoed the merge.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getCanMergePullRequest( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->getCanMergePullRequest($projectKey, $repositorySlug, $pullRequestId);
createMergePullRequest
Merge the specified pull request.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.
function createMergePullRequest( $projectKey, $repositorySlug, $pullRequestId, $version = -1)
Parameters
version the operation will fail. To determine the current version of the pull request it should be
fetched from the server prior to this operation. Look for the 'version' attribute in the returned
JSON structure. |
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $version = -1; $result = $pullRequest->createMergePullRequest($projectKey, $repositorySlug, $pullRequestId, $version);
getPullRequest
Retrieve a pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function getPullRequest( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $result = $pullRequest->getPullRequest($projectKey, $repositorySlug, $pullRequestId);
updatePullRequest
Update the title, description, reviewers or destination branch of an existing pull request.
Note: the reviewers list may be updated using this resource. However the author and participants list may not.
The authenticated user must either:
to call this resource.
- be the author of the pull request and have the REPO_READ permission for the repository that this pull request targets; or
- have the REPO_WRITE permission for the repository that this pull request targets
function updatePullRequest( $dynamic, $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 'pullRequestId'; $result = $pullRequest->updatePullRequest($dynamic, $projectKey, $repositorySlug, $pullRequestId);
createAssignPullRequestParticipantRole
Assigns a participant to an explicit role in pull request. Currently only the REVIEWER role may be assigned.
If the user is not yet a participant in the pull request, they are made one and assigned the supplied role.
If the user is already a participant in the pull request, their previous role is replaced with the supplied role unless they are already assigned the AUTHOR role which cannot be changed and will result in a Bad Request (400) response code.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.
function createAssignPullRequestParticipantRole( $dynamic, $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->createAssignPullRequestParticipantRole($dynamic, $projectKey, $repositorySlug, $pullRequestId);
deleteUnassignPullRequestParticipantRole
Unassigns a participant from the REVIEWER role they may have been given in a pull request.
If the participant has no explicit role this method has no effect.
Afterwards, the user will still remain a participant in the pull request but their role will be reduced to PARTICIPANT. This is because once made a participant of a pull request, a user will forever remain a participant. Only their role may be altered.
The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.
function deleteUnassignPullRequestParticipantRole( $projectKey, $repositorySlug, $pullRequestId, $username = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $username = 'username'; $result = $pullRequest->deleteUnassignPullRequestParticipantRole($projectKey, $repositorySlug, $pullRequestId, $username);
listPullRequestParticipants
Retrieves a page of the participants for a given pull request.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function listPullRequestParticipants( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->listPullRequestParticipants($projectKey, $repositorySlug, $pullRequestId);
createApprovePullRequest
Approve a pull request as the current user. Implicitly adds the user as a participant if they are not already.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function createApprovePullRequest( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 234; $result = $pullRequest->createApprovePullRequest($projectKey, $repositorySlug, $pullRequestId);
deleteWithdrawPullRequestApproval
Remove approval from a pull request as the current user. This does not remove the user as a participant.
The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.
function deleteWithdrawPullRequestApproval( $projectKey, $repositorySlug, $pullRequestId)
Parameters
Example Usage
$projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $pullRequestId = 192; $result = $pullRequest->deleteWithdrawPullRequestApproval($projectKey, $repositorySlug, $pullRequestId);
createPullRequest
Create a new pull request between two branches. The branches may be in the same repository, or different ones. When using different repositories, they must still be in the same {@link Repository#getHierarchyId() hierarchy}.
The authenticated user must have REPO_READ permission for the "from" and "to"repositories to call this resource.
function createPullRequest( $pullRequest, $projectKey, $repositorySlug)
Parameters
Example Usage
$pullRequest = new PullRequest(); $projectKey = 'projectKey'; $repositorySlug = 'repositorySlug'; $result = $pullRequest->createPullRequest($pullRequest, $projectKey, $repositorySlug);
Errors
HookController
Get singleton instance
The singleton instance of the HookController
class can be accessed from the API Client.
$hook = $client->getHook();
getAvatar
Retrieve the avatar for the project matching the supplied moduleKey.
function getAvatar( $hookKey, $version = null)
Parameters
Note that this does not affect the Last-Modified header. |
Example Usage
$hookKey = 'hookKey'; $version = 'version'; $result = $hook->getAvatar($hookKey, $version);
ProjectController
Get singleton instance
The singleton instance of the ProjectController
class can be accessed from the API Client.
$project = $client->getProject();
getProjectGroupsWithAnyPermission
Retrieve a page of groups that have been granted at least one permission for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
function getProjectGroupsWithAnyPermission( $projectKey, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $filter = 'filter'; $result = $project->getProjectGroupsWithAnyPermission($projectKey, $filter);
updateSetProjectPermissionForGroups
Promote or demote a group's permission level for the specified project. Available project permissions are:
See the Stash documentation for a detailed explanation of what each permission entails.
- PROJECT_READ
- PROJECT_WRITE
- PROJECT_ADMIN
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.
function updateSetProjectPermissionForGroups( $projectKey, $permission = null, $name = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $permission = 'permission'; $name = 'name'; $result = $project->updateSetProjectPermissionForGroups($projectKey, $permission, $name);
deleteRevokeProjectPermissionsForGroup
Revoke all permissions for the specified project for a group.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
In addition, a user may not revoke a group's permissions if it will reduce their own permission level.
function deleteRevokeProjectPermissionsForGroup( $projectKey, $name = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $name = 'name'; $result = $project->deleteRevokeProjectPermissionsForGroup($projectKey, $name);
getProjectGroupsWithoutAnyPermission
Retrieve a page of groups that have no granted permissions for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
function getProjectGroupsWithoutAnyPermission( $projectKey, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $filter = 'filter'; $result = $project->getProjectGroupsWithoutAnyPermission($projectKey, $filter);
getProjectUsersWithAnyPermission
Retrieve a page of users that have been granted at least one permission for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
function getProjectUsersWithAnyPermission( $projectKey, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $filter = 'filter'; $result = $project->getProjectUsersWithAnyPermission($projectKey, $filter);
updateSetProjectPermissionForUsers
Promote or demote a user's permission level for the specified project. Available project permissions are:
See the Stash documentation for a detailed explanation of what each permission entails.
- PROJECT_READ
- PROJECT_WRITE
- PROJECT_ADMIN
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a global permission that already implies that permission.
function updateSetProjectPermissionForUsers( $projectKey, $name = null, $permission = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $name = 'name'; $permission = 'permission'; $result = $project->updateSetProjectPermissionForUsers($projectKey, $name, $permission);
deleteRevokeProjectPermissionsForUser
Revoke all permissions for the specified project for a user.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
In addition, a user may not revoke their own project permissions if they do not have a higher global permission.
function deleteRevokeProjectPermissionsForUser( $projectKey, $name = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $name = 'name'; $result = $project->deleteRevokeProjectPermissionsForUser($projectKey, $name);
getProjectUsersWithoutPermission
Retrieve a page of licensed users that have no granted permissions for the specified project.
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
function getProjectUsersWithoutPermission( $projectKey, $filter = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $filter = 'filter'; $result = $project->getProjectUsersWithoutPermission($projectKey, $filter);
getHasProjectAllUserPermission
Check whether the specified permission is the default permission (granted to all users) for a project. Available project permissions are:
- PROJECT_READ
- PROJECT_WRITE
- PROJECT_ADMIN
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
function getHasProjectAllUserPermission( $projectKey, $permission)
Parameters
Example Usage
$projectKey = 'projectKey'; $permission = 'permission'; $result = $project->getHasProjectAllUserPermission($projectKey, $permission);
modifyProjectAllUserPermission
Grant or revoke a project permission to all users, i.e. set the default permission. Available project permissions are:
- PROJECT_READ
- PROJECT_WRITE
- PROJECT_ADMIN
The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.
function modifyProjectAllUserPermission( $projectKey, $permission, $allow = null)
Parameters
Example Usage
$projectKey = 'projectKey'; $permission = 'permission'; $allow = true; $result = $project->modifyProjectAllUserPermission($projectKey, $permission, $allow);
createProject
Create a new project.
To include a custom avatar for the project, the project definition should contain an additional attribute with the key
avatar
and the value a data URI containing Base64-encoded image data. The URI should be in the following format:data:(content type, e.g. image/png);base64,(data)If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.The authenticated user must have PROJECT_CREATE permission to call this resource.
function createProject($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $project->createProject($dynamic);
getProjects
Retrieve a page of projects.
Only projects for which the authenticated user has the PROJECT_VIEW permission will be returned.
function getProjects( $name = null, $permission = null)
Parameters
Example Usage
$name = 'name'; $permission = 'permission'; $result = $project->getProjects($name, $permission);
deleteProject
Delete the project matching the supplied projectKey.
The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
function deleteProject($projectKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $result = $project->deleteProject($projectKey);
updateProject
Update the project matching the projectKey supplied in the resource path.
To include a custom avatar for the updated project, the project definition should contain an additional attribute with the key
avatar
and the value a data URI containing Base64-encoded image data. The URI should be in the following format:data:(content type, e.g. image/png);base64,(data)
If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
function updateProject( $dynamic, $projectKey)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $projectKey = 'projectKey'; $result = $project->updateProject($dynamic, $projectKey);
getProject
Retrieve the project matching the supplied projectKey.
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.
function getProject($projectKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $result = $project->getProject($projectKey);
getProjectAvatar
Retrieve the avatar for the project matching the supplied projectKey.
The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.
function getProjectAvatar( $projectKey, $s = 0)
Parameters
size. |
Example Usage
$projectKey = 'projectKey'; $s = 0; $result = $project->getProjectAvatar($projectKey, $s);
uploadProjectAvatar
Update the avatar for the project matching the supplied projectKey.
This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.
An example curl request to upload an image name 'avatar.png' would be:
curl -X POST -u username:password http://example.com/rest/api/1.0/projects/STASH/avatar.png -F avatar=@avatar.pngThe authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.
function uploadProjectAvatar($projectKey)
Parameters
Example Usage
$projectKey = 'projectKey'; $result = $project->uploadProjectAvatar($projectKey);
TaskController
Get singleton instance
The singleton instance of the TaskController
class can be accessed from the API Client.
$task = $client->getTask();
createTask
Create a new task.
function createTask($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $task->createTask($dynamic);
deleteTask
Delete a task.
Note that only the task's creator, the context's author or an admin of the context's repository can delete a task. (For a pull request task, those are the task's creator, the pull request's author or an admin on the repository containing the pull request). Additionally a task cannot be deleted if it has already been resolved.
function deleteTask($taskId)
Parameters
Example Usage
$taskId = 192; $result = $task->deleteTask($taskId);
updateTask
Update a existing task.
As of Stash 3.3, only the state and text of a task can be updated.
Updating the state of a task is allowed for any user having READ access to the repository. However only the task's creator, the context's author or an admin of the context's repository can update the task's text. (For a pull request task, those are the task's creator, the pull request's author or an admin on the repository containing the pull request). Additionally the task's text cannot be updated if it has been resolved.
function updateTask( $dynamic, $taskId)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $taskId = 192; $result = $task->updateTask($dynamic, $taskId);
getTask
Retrieve a existing task.
function getTask($taskId)
Parameters
Example Usage
$taskId = 192; $result = $task->getTask($taskId);
GroupController
Get singleton instance
The singleton instance of the GroupController
class can be accessed from the API Client.
$group = $client->getGroup();
getGroups
Retrieve a page of group names.
The authenticated user must have PROJECT_ADMIN permission or higher to call this resource.
function getGroups($filter = null)
Parameters
Example Usage
$filter = 'filter'; $result = $group->getGroups($filter);
ProfileController
Get singleton instance
The singleton instance of the ProfileController
class can be accessed from the API Client.
$profile = $client->getProfile();
getProfileRepositoriesRecentlyAccessed
Retrieve a page of recently accessed repositories for the currently authenticated user.
Repositories are ordered from most recently to least recently accessed.
Only authenticated users may call this resource.
function getProfileRepositoriesRecentlyAccessed($permission = null)
Parameters
the resulting repository list to ones that the requesting user has the specified permission
level to. If not specified, the default <code>REPO_READ</code> permission level will be assumed. |
Example Usage
$permission = 'permission'; $result = $profile->getProfileRepositoriesRecentlyAccessed($permission);
ApplicationController
Get singleton instance
The singleton instance of the ApplicationController
class can be accessed from the API Client.
$application = $client->getApplication();
getApplicationProperties
Retrieve version information and other application properties.
No authentication is required to call this resource.
function getApplicationProperties()
Example Usage
$result = $application->getApplicationProperties();
LogController
Get singleton instance
The singleton instance of the LogController
class can be accessed from the API Client.
$log = $client->getLog();
getRootLevel
Retrieve the current log level for the root logger.
The authenticated user must have ADMIN permission or higher to call this resource.
function getRootLevel()
Example Usage
$result = $log->getRootLevel();
updateSetRootLevel
Set the current log level for the root logger.
The authenticated user must have ADMIN permission or higher to call this resource.
function updateSetRootLevel($levelName)
Parameters
Example Usage
$levelName = 'levelName'; $result = $log->updateSetRootLevel($levelName);
getLevel
Retrieve the current log level for a given logger.
The authenticated user must have ADMIN permission or higher to call this resource.
function getLevel($loggerName)
Parameters
Example Usage
$loggerName = 'loggerName'; $result = $log->getLevel($loggerName);
updateSetLevel
Set the current log level for a given logger.
The authenticated user must have ADMIN permission or higher to call this resource.
function updateSetLevel( $levelName, $loggerName)
Parameters
Example Usage
$levelName = 'levelName'; $loggerName = 'loggerName'; $result = $log->updateSetLevel($levelName, $loggerName);
UserController
Get singleton instance
The singleton instance of the UserController
class can be accessed from the API Client.
$user = $client->getUser();
getUsers
Retrieve a page of users, optionally run through provided filters.
Only authenticated users may call this resource.
Supported Filters
Filters are provided in query parameters in a standard
name=value
fashion. The following filters are currently supported:
- {@code filter} - return only users, whose username, name or email address contain the {@code filter} value
- {@code permission} - the "root" of a permission filter, whose value must be a valid global, project, or repository permission. Additional filter parameters referring to this filter that specify the resource (project or repository) to apply the filter to must be prefixed with
permission.
. See the section "Permission Filters" below for more details.- {@code permission.N} - the "root" of a single permission filter, similar to the {@code permission} parameter, where "N" is a natural number starting from 1. This allows clients to specify multiple permission filters, by providing consecutive filters as {@code permission.1}, {@code permission.2} etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of permission filters is 50 and all filters exceeding that limit will be dropped. See the section "Permission Filters" below for more details on how the permission filters are processed.
Permission Filters
The following three sub-sections list parameters supported for permission filters (where
[root]
is the root permission filter name, e.g. {@code permission}, {@code permission.1} etc.) depending on the permission resource. The system determines which filter to apply (Global, Project or Repository permission) based on the[root]
permission value. E.g. {@code ADMIN} is a global permission, {@code PROJECT_ADMIN} is a project permission and {@code REPO_ADMIN} is a repository permission. Note that the parameters for a given resource will be looked up in the order as they are listed below, that is e.g. for a project resource, if both {@code projectId} and {@code projectKey} are provided, the system will use {@code projectId} for the lookup.Global permissions
The permission value under
[root]
is the only required and recognized parameter, as global permissions do not apply to a specific resource.Example valid filter:
permission=ADMIN
.Project permissions
[root]
- specifies the project permission[root].projectId
- specifies the project ID to lookup the project by[root].projectKey
- specifies the project key to lookup the project byExample valid filter:
permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT
.Repository permissions
Example valid filter:
[root]
- specifies the repository permission[root].projectId
- specifies the repository ID to lookup the repository by[root].projectKey
and[root].repositorySlug
- specifies the project key and repository slug to lookup the repository by; both values need to be provided for this look up to be triggeredpermission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo
.
function getUsers()
Example Usage
$result = $user->getUsers();
updateUserDetails
Update the currently authenticated user's details. Note that the name attribute is ignored, the update will always be applied to the currently authenticated user.
function updateUserDetails($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $user->updateUserDetails($dynamic);
deleteUserAvatar
Delete the avatar associated to a user.
Users are always allowed to delete their own avatar. To delete someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.
function deleteUserAvatar($userSlug)
Parameters
Example Usage
$userSlug = 'userSlug'; $result = $user->deleteUserAvatar($userSlug);
uploadUserAvatar
Update the avatar for the user with the supplied slug.
This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.
There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.
This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to pass the XSRF check the caller needs to send an
X-Atlassian-Token
HTTP header with the valueno-check
.An example curl request to upload an image name 'avatar.png' would be:
curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/latest/users/jdoe/avatar.png -F avatar=@avatar.pngUsers are always allowed to update their own avatar. To update someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.
function uploadUserAvatar($userSlug)
Parameters
Example Usage
$userSlug = 'userSlug'; $result = $user->uploadUserAvatar($userSlug);
getUser
Retrieve the user matching the supplied userSlug.
function getUser($userSlug)
Parameters
Example Usage
$userSlug = 'userSlug'; $result = $user->getUser($userSlug);
updateUserPassword
Update the currently authenticated user's password.
function updateUserPassword($dynamic)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $result = $user->updateUserPassword($dynamic);
getUserSettings
Retrieve a map of user setting key values for a specific user identified by the user slug.
function getUserSettings($userSlug)
Parameters
Example Usage
$userSlug = 'userSlug'; $result = $user->getUserSettings($userSlug);
updateUserSettings
Update the entries of a map of user setting key/values for a specific user identified by the user slug.
function updateUserSettings( $dynamic, $userSlug)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $userSlug = 'userSlug'; $result = $user->updateUserSettings($dynamic, $userSlug);
MarkupController
Get singleton instance
The singleton instance of the MarkupController
class can be accessed from the API Client.
$markup = $client->getMarkup();
createPreviewMarkup
Preview the generated html for given markdown contents.
Only authenticated users may call this resource.
function createPreviewMarkup( $dynamic, $urlMode = null, $hardwrap = null, $htmlEscape = null)
Parameters
Example Usage
$dynamic = array('key' => 'value'); $urlMode = 'urlMode'; $hardwrap = true; $htmlEscape = true; $result = $markup->createPreviewMarkup($dynamic, $urlMode, $hardwrap, $htmlEscape);