Git Integration for Jira Self-Managed (Data Center/Server) Documentation

Contact Support: Server  
Contact Support: Data Center  

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

  • Add new integration Wizard ➜ Connection screen ➜ Advanced ➜ Custom API Path.

    For example:

  • Manage repositories page ➜  Actions ➜ Edit integration connection settings ➜ Custom API Path.

GitHub.com and GitHub Enterprise examples

  1. Lists all repositories (default)

    /user/repos

    Gets a list of repositories by the authenticated user. 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 a list of repositories by the authenticated user. This is the same as when no API path is specified.

    /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>
    BigBrassBand

    For instance:

    /orgs/BigBrassBand/repos

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

GitLab.com and 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>johnsmith

  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.

GitLab version API support:
Gitlab v9.5 and above — only API v4
Gitlab v9.0 to v9.4.x — API v3 and API v4 (support for API v3 is deprecated)

Remember
The GitLab.com API can see all the public projects. For GitLab.com, we recommend using JMESPath over the Custom API path when possible. For more information, see Working with JMESPath filters.

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

More how-to articles


1 Logo owned by GitLab Inc used under license

Have feedback about this article? Did we miss something? Let us know!
On this page