Working with Custom API Path

The Custom API Path is a relative path that starts with “/”. The maximum allowed length is 2000 characters. The integration will use the relative REST API path to retrieve the list of tracked repositories.

The Custom API Path is called in the integration setup, settings changes, on a regular scheduled reindex and for a manual reindex.

What’s on this page:

• Accessible Locations
• GitHub.com examples
• GitHub Enterprise examples
• GitLab.com | GitLab CE/EE examples
• Bitbucket Cloud examples

Accessible Locations

• Go to Manage Git repositories page ➜ Full feature integration wizard ➜ Connect screen ➜ Advanced ➜ Custom API Path. In this case, we use GitHub as an example:

  
  

• Go to Manage Git repositories page ➜ Actions ➜ Edit integration settings (for integration) or Edit repository settings (for repositories) ➜ Integration settings section ➜ Custom API Path.

  
  

GitHub.com examples

1. Lists all repositories (default)

/user/repos

Gets a list of repositories. This is the same as when no API path is specified.

2. Display all repositories from <username>

/users/<username>/repos

Gets a list of public repositories for the specified user, <username>.

For example: /users/johnsmith/repos

3. Displays starred repositories

/user/starred

Gets the list of starred repositories for the authenticated user.

/users/<username>/starred

Gets the list of starred public/private repositories for the specified user, <username>.

For example: /users/johnsmith/starred

4. List all repositories for the specified organization

/orgs/<org>/repos

Gets a list of repositories for the specified org, <org>. GitKraken

For instance:
/orgs/BigBrassBand/repos
This will filter for repositories only within the org: BigBrassBand. This works for GitHub.com integrations.

GitHub Enterprise examples

1. Lists all repositories (default)

/api/v3/user/repos

Gets the list of starred repositories for the authenticated user.

2. Display all repositories from <username>

/api/v3/users/<username>/repos

Gets a list of public repositories for the specified user, <username>.

For example: /api/v3/users/johnsmith/repos

3. Display starred repositories

/api/v3/user/starred

Gets the list of starred repositories for the authenticated user.

/api/v3/users/<username>/starred

Gets the list of public/private starred repositories for the specified user, <username>.

For example: /api/v3/users/johnsmith/starred

4. List all repositories for the specified organization

/api/v3/orgs/<org>/repos

Gets a list of repositories for the specified org, <org>. GitKraken

For instance:
/api/v3/orgs/BigBrassBand/repos

This will filter for repositories only within the org: GitKraken. This works for GitHub Enterprise integrations.

GitLab.com | GitLab CE/EE examples

1. Lists all projects (default)

/api/v4/projects?membership=true

Gets a list of projects. This is the same as when no API path is specified.

2. Display all projects from <user_id>

/api/v4/users/<user_id>/projects

Gets a list of projects for the specified user, <user_id>.

For example: /api/v4/users/johnsmith/projects

3. Displays starred projects

/api/v4/projects?starred=true

Returns GitLab projects that have been starred by the connecting GitLab user.

4. Limit to owned projects

/api/v4/projects?owned=true

The current user will be limited to the projects it’s explicitly owned.

5. List projects from within a Group

/api/v4/groups/5245789/projects<br>/api/v4/groups/BigBrassBand/projects

Returns the list of repositories within a GitLab Group (or GitLab Subgroup).

In the above examples, you can use the Group id or your Group name as query parameter.

6. List projects from the specified sub-group

/api/v4/groups/5245789/projects?include_subgroups=true

/api/v4/groups/BigBrassBand/projects?include_subgroups=true

In the above examples, the ?include_subgroups=true API extension will return a recursive list of repositories within a nested GitLab Group (or GitLab Subgroup) where the #, 5245789, is the Group id; and BigBrassBand is the Group name.

For more information on GitLab custom API paths, see GitLab API.

Bitbucket Cloud examples

1. Lists all repositories for the specific user (default)

/!api/2.0/repositories/<username>

Displays a list of git repositories of the user with the specified username. This is the same as when no API path is specified.

For example:
/!api/2.0/repositories/wcoyote

2. Lists all repositories for the specified workspace ID

/!api/2.0/repositories/<workspaceID>

Displays a list of git repositories for the specified workspace ID.

For example:
/!api/2.0/repositories/acmegroup

While Custom API Path and JMESPath filter are mutually exclusive, you can use one, the other, both or neither.