bluefeet / GitLab-API-v4

A complete GitLab API v4 client.
https://metacpan.org/pod/GitLab::API::v4
Other
20 stars 23 forks source link
cpan perl5

NAME

GitLab::API::v4 - A complete GitLab API v4 client.

SYNOPSIS

use GitLab::API::v4;

my $api = GitLab::API::v4->new(
    url           => $v4_api_url,
    private_token => $token,
);

my $branches = $api->branches( $project_id );

DESCRIPTION

This module provides a one-to-one interface with the GitLab API v4. Much is not documented here as it would just be duplicating GitLab's own API Documentation.

Note that this distribution also includes the gitlab-api-v4 command-line interface (CLI).

Upgrading

If you are upgrading from GitLab::API::v3 make sure you read:

https://docs.gitlab.com/ce/api/v3_to_v4.html

Also, review the Changes file included in the distribution as it outlines the changes made to convert the v3 module to v4:

https://github.com/bluefeet/GitLab-API-v4/blob/master/Changes

Finally, be aware that many methods were added, removed, renamed, and/or altered. If you want to review exactly what was changed you can use GitHub's compare tool:

https://github.com/bluefeet/GitLab-API-v4/compare/72e384775c9570f60f8ef68dee3a1eecd347fb69...master

Or clone the repo and run this command:

git diff 72e384775c9570f60f8ef68dee3a1eecd347fb69..HEAD -- author/sections/

Credentials

Authentication credentials may be defined by setting either the "access_token" or "private_token" arguments.

If no credentials are supplied then the client will be anonymous and greatly limited in what it can do with the API.

Extra care has been taken to hide the token arguments behind closures. This way, if you dump your api object, your tokens won't accidentally leak into places you don't want them to.

Constants

The GitLab API, in rare cases, uses a hard-coded value to represent a state. To make life easier the GitLab::API::v4::Constants module exposes these states as named variables.

Exceptions

The API methods will all throw a useful exception if an unsuccessful response is received from the API. That is except for GET requests that return a 404 response - these will return undef for methods that return a value.

If you'd like to catch and handle these exceptions consider using Try::Tiny.

Logging

This module uses Log::Any and produces some debug messages here and there, but the most useful bits are the info messages produced just before each API call.

Project ID

Note that many API calls require a $project_id. This can be specified as a numeric project ID or, in many cases, maybe all cases, as a NAMESPACE_PATH/PROJECT_PATH string. The GitLab documentation on this point is vague.

REQUIRED ARGUMENTS

url

The URL to your v4 API endpoint. Typically this will be something like https://git.example.com/api/v4.

OPTIONAL ARGUMENTS

access_token

A GitLab API OAuth2 token. If set then "private_token" may not be set.

See https://docs.gitlab.com/ce/api/#oauth2-tokens.

private_token

A GitLab API personal token. If set then "access_token" may not be set.

See https://docs.gitlab.com/ce/api/#personal-access-tokens.

retries

The number of times the request should be retried in case it fails (5XX HTTP response code). Defaults to 0 (false), meaning that a failed request will not be retried.

sudo_user

The user to execute API calls as. You may find it more useful to use the "sudo" method instead.

See https://docs.gitlab.com/ce/api/#sudo.

rest_client

An instance of GitLab::API::v4::RESTClient (or whatever "rest_client_class" is set to). Typically you will not be setting this as it defaults to a new instance and customization should not be necessary.

rest_client_class

The class to use when constructing the "rest_client". Defaults to GitLab::API::v4::RESTClient.

UTILITY METHODS

paginator

my $paginator = $api->paginator( $method, @method_args );

my $members = $api->paginator('group_members', $group_id);
while (my $member = $members->next()) {
    ...
}

my $users_pager = $api->paginator('users');
while (my $users = $users_pager->next_page()) {
    ...
}

my $all_open_issues = $api->paginator(
    'issues',
    $project_id,
    { state=>'opened' },
)->all();

Given a method who supports the page and per_page parameters, and returns an array ref, this will return a GitLab::API::v4::Paginator object that will allow you to walk the records one page or one record at a time.

sudo

$api->sudo('fred')->create_issue(...);

Returns a new instance of GitLab::API::v4 with the "sudo_user" argument set.

See https://docs.gitlab.com/ce/api/#sudo.

API METHODS

Award Emoji

See https://docs.gitlab.com/ce/api/award_emoji.html.

Branches

See https://docs.gitlab.com/ce/api/branches.html.

Broadcast Messages

See https://docs.gitlab.com/ce/api/broadcast_messages.html.

Project-level Variables

See https://docs.gitlab.com/ce/api/project_level_variables.html.

Group-level Variables

See https://docs.gitlab.com/ce/api/group_level_variables.html.

Snippets

See https://docs.gitlab.com/ce/api/snippets.html.

Commits

See https://docs.gitlab.com/ce/api/commits.html.

Container Registry

See https://docs.gitlab.com/ce/api/container_registry.html.

Custom Attributes

See https://docs.gitlab.com/ce/api/custom_attributes.html.

Deployments

See https://docs.gitlab.com/ce/api/deployments.html.

Deploy Keys

See https://docs.gitlab.com/ce/api/deploy_keys.html.

Environments

See https://docs.gitlab.com/ce/api/environments.html.

Events

See https://docs.gitlab.com/ce/api/events.html.

Feature flags

See https://docs.gitlab.com/ce/api/features.html.

Gitignores

See https://docs.gitlab.com/ce/api/templates/gitignores.html.

GitLab CI YMLs

See https://docs.gitlab.com/ce/api/templates/gitlab_ci_ymls.html.

Groups

See https://docs.gitlab.com/ce/api/groups.html.

Group access requests

See https://docs.gitlab.com/ce/api/access_requests.html.

Group badges

See https://docs.gitlab.com/ce/api/group_badges.html.

Group members

See https://docs.gitlab.com/ce/api/members.html.

Issues

See https://docs.gitlab.com/ce/api/issues.html.

Issue Boards

See https://docs.gitlab.com/ce/api/boards.html.

Group Issue Boards

See https://docs.gitlab.com/ce/api/group_boards.html.

Jobs

See https://docs.gitlab.com/ce/api/jobs.html.

Keys

See https://docs.gitlab.com/ce/api/keys.html.

Labels

See https://docs.gitlab.com/ce/api/labels.html.

Markdown

See https://docs.gitlab.com/ce/api/markdown.html.

Merge requests

See https://docs.gitlab.com/ce/api/merge_requests.html.

Milestones

See https://docs.gitlab.com/ce/api/milestones.html.

Group milestones

See https://docs.gitlab.com/ce/api/group_milestones.html.

Namespaces

See https://docs.gitlab.com/ce/api/namespaces.html.

Notes

See https://docs.gitlab.com/ce/api/notes.html.

Discussions

See https://docs.gitlab.com/ce/api/discussions.html.

Resource label events

See https://docs.gitlab.com/ce/api/resource_label_events.html.

Notification settings

See https://docs.gitlab.com/ce/api/notification_settings.html.

Licenses

See https://docs.gitlab.com/ce/api/templates/licenses.html.

Pages domains

See https://docs.gitlab.com/ce/api/pages_domains.html.

Pipelines

See https://docs.gitlab.com/ce/api/pipelines.html.

Pipeline triggers

See https://docs.gitlab.com/ce/api/pipeline_triggers.html.

Pipeline schedules

See https://docs.gitlab.com/ce/api/pipeline_schedules.html.

Projects

See https://docs.gitlab.com/ce/api/projects.html.

Project access requests

See https://docs.gitlab.com/ce/api/access_requests.html.

Project badges

See https://docs.gitlab.com/ce/api/project_badges.html.

Project import/export

See https://docs.gitlab.com/ce/api/project_import_export.html.

Project members

See https://docs.gitlab.com/ce/api/members.html.

Project snippets

See https://docs.gitlab.com/ce/api/project_snippets.html.

Protected branches

See https://docs.gitlab.com/ce/api/protected_branches.html.

Protected tags

See https://docs.gitlab.com/ce/api/protected_tags.html.

Releases

See https://docs.gitlab.com/ce/api/releases/index.html.

Release Links

See https://docs.gitlab.com/ce/api/releases/links.html.

Remote Mirrors

See https://docs.gitlab.com/ce/api/remote_mirrors.html.

Repositories

See https://docs.gitlab.com/ce/api/repositories.html.

Repository files

See https://docs.gitlab.com/ce/api/repository_files.html.

Runners

See https://docs.gitlab.com/ce/api/runners.html.

Search

See https://docs.gitlab.com/ce/api/search.html.

Services

See https://docs.gitlab.com/ce/api/services.html.

Application settings

See https://docs.gitlab.com/ce/api/settings.html.

Application statistics

See https://docs.gitlab.com/ce/api/statistics.html.

Sidekiq Metrics

See https://docs.gitlab.com/ce/api/sidekiq_metrics.html.

System hooks

See https://docs.gitlab.com/ce/api/system_hooks.html.

Tags

See https://docs.gitlab.com/ce/api/tags.html.

Todos

See https://docs.gitlab.com/ce/api/todos.html.

Users

See https://docs.gitlab.com/ce/api/users.html.

Validate the .gitlab-ci.yml

See https://docs.gitlab.com/ce/api/lint.html.

Version

See https://docs.gitlab.com/ce/api/version.html.

Wikis

See https://docs.gitlab.com/ce/api/wikis.html.

CONTRIBUTING

This module is auto-generated from a set of YAML files defining the interface of GitLab's API. If you'd like to contribute to this module then please feel free to make a fork on GitHub and submit a pull request, just make sure you edit the files in the authors/ directory instead of lib/GitLab/API/v4.pm directly.

Please see https://github.com/bluefeet/GitLab-API-v4/blob/master/author/README.pod for more information.

Alternatively, you can open a ticket.

SUPPORT

Please submit bugs and feature requests to the GitLab-API-v4 GitHub issue tracker:

https://github.com/bluefeet/GitLab-API-v4/issues

AUTHOR

Aran Clary Deltac <bluefeet@gmail.com>

CONTRIBUTORS

Dotan Dimet <dotan@corky.net>
Nigel Gregoire <nigelgregoire@gmail.com>
trunov-ms <trunov.ms@gmail.com>
Marek R. Sotola <Marek.R.Sotola@nasa.gov>
José Joaquín Atria <jjatria@gmail.com>
Dave Webb <github@d5ve.com>
Simon Ruderich <simon@ruderich.org>
royce55 <royce@ecs.vuw.ac.nz>
gregor herrmann <gregoa@debian.org>
Luc Didry <luc@didry.org>
Kieren Diment <kieren.diment@staples.com.au>
Dmitry Frolov <dmitry.frolov@gmail.com>
Thomas Klausner <domm@plix.at>
Graham Knop <haarg@haarg.org>
Stig Palmquist <git@stig.io>
Dan Book <grinnz@grinnz.com>
James Wright <jwright@ecstuning.com>
Jonathan Taylor <jon@stackhaus.com>
g0t mi1k <have.you.g0tmi1k@gmail.com>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.