GitSwarm-EE 2017.1-1 Documentation


Groups

List groups

Get a list of groups. (As user: my groups or all available, as admin: all groups).

Parameters:

Attribute Type Required Description
skip_groups array of integers no Skip the group IDs passes
all_available boolean no Show all the groups you have access to
search string no Return list of authorized groups matching the search criteria
order_by string no Order groups by name or path. Default is name
sort string no Order groups in asc or desc order. Default is asc
GET /groups
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]

You can search for groups by name or path, see below.

=======

List owned groups

Get a list of groups which are owned by the authenticated user.

GET /groups/owned

List a group's projects

Get a list of projects in this group.

GET /groups/:id/projects

Parameters:

[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "master",
    "tag_list": [],
    "public": false,
    "archived": false,
    "visibility_level": 10,
    "ssh_url_to_repo": "git@gitswarm.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitswarm.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitswarm.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "builds_enabled": true,
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
      "owner_id": null,
      "created_at": "2016-04-05T21:40:49.152Z",
      "updated_at": "2016-04-07T08:07:48.466Z",
      "description": "foo",
      "avatar": {
        "url": null
      },
      "share_with_group_lock": false,
      "visibility_level": 10
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_builds": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]

Details of a group

Get all details of a group.

GET /groups/:id

Parameters:

Attribute Type Required Description
id integer/string yes The ID or path of a group
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitswarm.example.com/api/v3/groups/4

Example response:

{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility_level": 20,
  "avatar_url": null,
  "web_url": "https://gitswarm.example.com/groups/twitter",
  "request_access_enabled": false,
  "projects": [
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "master",
      "tag_list": [],
      "public": true,
      "archived": false,
      "visibility_level": 20,
      "ssh_url_to_repo": "git@gitswarm.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitswarm.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitswarm.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "builds_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "owner_id": null,
        "created_at": "2016-06-17T07:47:24.216Z",
        "updated_at": "2016-06-17T07:47:24.216Z",
        "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
        "avatar": {
          "url": null
        },
        "share_with_group_lock": false,
        "visibility_level": 20
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_builds": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "master",
      "tag_list": [],
      "public": false,
      "archived": false,
      "visibility_level": 10,
      "ssh_url_to_repo": "git@gitswarm.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitswarm.example.com/twitter/flight.git",
      "web_url": "https://gitswarm.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "builds_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "owner_id": null,
        "created_at": "2016-06-17T07:47:24.216Z",
        "updated_at": "2016-06-17T07:47:24.216Z",
        "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
        "avatar": {
          "url": null
        },
        "share_with_group_lock": false,
        "visibility_level": 20
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_builds": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "master",
      "tag_list": [],
      "public": false,
      "archived": false,
      "visibility_level": 0,
      "ssh_url_to_repo": "git@gitswarm.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitswarm.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitswarm.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "builds_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
        "owner_id": null,
        "created_at": "2016-06-17T07:47:26.621Z",
        "updated_at": "2016-06-17T07:47:26.621Z",
        "description": "Id consequatur rem vel qui doloremque saepe.",
        "avatar": {
          "url": null
        },
        "share_with_group_lock": false,
        "visibility_level": 20
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_builds": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_access_level": 30
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_access_level": 10
        }
      ]
    }
  ]
}

New group

Creates a new project group. Available only for users who can create groups.

POST /groups

Parameters:

Update group

Updates a project group. Available only for users who can manage this group.

PUT /groups/:id

Parameters:

Transfer project to group

Transfer a project to the Group namespace. Available only for admin

POST  /groups/:id/projects/:project_id

Parameters:

Update group

Updates the project group. Only available to group owners and administrators.

PUT /groups/:id
Attribute Type Required Description
id integer yes The ID of the group
name string no The name of the group
path string no The path of the group
description string no The description of the group
visibility_level integer no The visibility level of the group. 0 for private, 10 for internal, 20 for public.
lfs_enabled (optional) boolean no Enable/disable Large File Storage (LFS) for the projects in this group
request_access_enabled boolean no Allow users to request member access.
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.example.com/api/v3/groups/5?name=Experimental"

Example response:

{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
  "visibility_level": 10,
  "avatar_url": null,
  "web_url": "http://gitswarm.example.com/groups/h5bp",
  "request_access_enabled": false,
  "projects": [
    {
      "id": 9,
      "description": "foo",
      "default_branch": "master",
      "tag_list": [],
      "public": false,
      "archived": false,
      "visibility_level": 10,
      "ssh_url_to_repo": "git@gitswarm.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitswarm.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitswarm.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "builds_enabled": true,
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
        "owner_id": null,
        "created_at": "2016-04-05T21:40:49.152Z",
        "updated_at": "2016-04-07T08:07:48.466Z",
        "description": "foo",
        "avatar": {
          "url": null
        },
        "share_with_group_lock": false,
        "visibility_level": 10
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_builds": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ]
}

Remove group

Removes group with all projects inside.

DELETE /groups/:id

Parameters:

Search for group

Get all groups that match your string in their name or path.

GET /groups?search=foobar
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]

Group members

Please consult the Group Members documentation.

Adds LDAP group link

POST /groups/:id/ldap_group_links

Parameters:

Deletes a LDAP group link

DELETE /groups/:id/ldap_group_links/:cn

Parameters:

Deletes a LDAP group link for a specific LDAP provider

DELETE /groups/:id/ldap_group_links/:provider/:cn

Parameters:

Namespaces in groups

By default, groups only get 20 namespaces at a time because the API results are paginated.

To get more (up to 100), pass the following as an argument to the API call:

/groups?per_page=100

And to switch pages add:

/groups?per_page=100&page=2