A GitLab API client enabling Go programs to interact with GitLab in a simple and uniform way

go-gitlab

NOTE

Release v0.6.0 (released on 25-08-2017) no longer supports the older V3 Gitlab API. If you need V3 support, please use the f-api-v3 branch. This release contains some backwards incompatible changes that were needed to fully support the V4 Gitlab API.

Coverage

This API client package covers most of the existing Gitlab API calls and is updated regularly to add new and/or missing endpoints. Currently the following services are supported:

Usage

import "github.com/xanzy/go-gitlab"

Construct a new GitLab client, then use the various services on the client to access different parts of the GitLab API. For example, to list all users:

git, err := gitlab.NewClient("yourtokengoeshere")
if err != nil {
  log.Fatalf("Failed to create client: %v", err)
}
users, _, err := git.Users.ListUsers(&gitlab.ListUsersOptions{})

There are a few With... option functions that can be used to customize the API client. For example, to set a custom base URL:

git, err := gitlab.NewClient("yourtokengoeshere", gitlab.WithBaseURL("https://git.mydomain.com/api/v4"))
if err != nil {
  log.Fatalf("Failed to create client: %v", err)
}
users, _, err := git.Users.ListUsers(&gitlab.ListUsersOptions{})

Some API methods have optional parameters that can be passed. For example, to list all projects for user "svanharmelen":

git := gitlab.NewClient("yourtokengoeshere")
opt := &ListProjectsOptions{Search: gitlab.String("svanharmelen")}
projects, _, err := git.Projects.ListProjects(opt)

Examples

The examples directory contains a couple for clear examples, of which one is partially listed here as well:

package main

import (
	"log"

	"github.com/xanzy/go-gitlab"
)

func main() {
	git, err := gitlab.NewClient("yourtokengoeshere")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Create new project
	p := &gitlab.CreateProjectOptions{
		Name:                 gitlab.String("My Project"),
		Description:          gitlab.String("Just a test project to play with"),
		MergeRequestsEnabled: gitlab.Bool(true),
		SnippetsEnabled:      gitlab.Bool(true),
		Visibility:           gitlab.Visibility(gitlab.PublicVisibility),
	}
	project, _, err := git.Projects.CreateProject(p)
	if err != nil {
		log.Fatal(err)
	}

	// Add a new snippet
	s := &gitlab.CreateProjectSnippetOptions{
		Title:           gitlab.String("Dummy Snippet"),
		FileName:        gitlab.String("snippet.go"),
		Content:         gitlab.String("package main...."),
		Visibility:      gitlab.Visibility(gitlab.PublicVisibility),
	}
	_, _, err = git.ProjectSnippets.CreateSnippet(project.ID, s)
	if err != nil {
		log.Fatal(err)
	}
}

For complete usage of go-gitlab, see the full package docs.

ToDo

The biggest thing this package still needs is tests 😞

Issues

If you have an issue: report it on the issue tracker

Author

Sander van Harmelen ([email protected])

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

This PR continues the work in #1101, rebasing it to master, updating its interface (returning download URL), and some real-world testing (fixed the URL endpoint and request type).

https://docs.gitlab.com/ce/api/projects.html#edit-project -> Currently the CreateProjectOptions does not contain an entry to send along an avatar, even thought it is supported in the API. Would be great if we could upload an avatar :smile_cat:

Maybe we can also directly support the other new params ci_config_path and tag_list?

enhancement

Lets track this in an issue. The GitLab API v3 is officially deprecated and will be supported until at least 9.3. Given the current release schedule (once per month), that means it will be unsupported 3 months from now.

I would like to be able to start consuming v4 functionality so I might start work on a v4 branch.

I think all current documentation links need to be updated to the v3 documentation as currently the links all point to the v4 documentation which causes confusion. Separately some effort should be made to start supporting v4 specific functionality (probably in a feature branch). Once both those things are completed, v3 could be spun out to a separate branch and v4 can be merged to master.

Below are the changes made between V3 and V4. A tickbox indicates that work has been completed on that change.

Completed

[x] Rename Build Triggers to be Pipeline Triggers API !9713. Fixed in #152.
- POST /projects/:id/trigger/builds to POST /projects/:id/trigger/pipeline
- Require description when creating a new trigger POST /projects/:id/triggers
[x] Removed GET /projects/:search (use: GET /projects?search=x) !8877. Fixed in #161.
[x] iid filter has been removed from GET /projects/:id/issues !8967. Fixed in #161.
[x] GET /projects/:id/merge_requests?iid[]=x&iid[]=y array filter has been renamed to iids !8793. Fixed in #161.
[x] Endpoints under GET /projects/merge_request/:id have been removed (use: GET /projects/merge_requests/:id) !8793. Fixed in #161.
[x] Project snippets do not return deprecated field expires_at !8723. Fixed in #161.
[x] Endpoints under GET /projects/:id/keys have been removed (use GET /projects/:id/deploy_keys) !8716. Fixed in #161.
[x] Update v3 documentation to point to archived v3 docs. Fixed in #160.
[x] Return basic info about pipeline in GET /projects/:id/pipelines !8875. Fixed in #163
[x] Renamed all build references to job !9463. Fixed in #166.
[x] Use visibility as string parameter everywhere !9337. Fixed in #167.
[x] Project filters are no longer available as GET /projects/foo, but as GET /projects?foo=true instead !8962. Fixed in #170.
- GET /projects/visible & GET /projects/all are consolidated into GET /projects and can be used with or without authorization
- GET /projects/owned moved to GET /projects?owned=true
- GET /projects/starred moved to GET /projects?starred=true
[x] GET /projects returns all projects visible to current user, even if the user is not a member !9674. Fixed in #170.
- To get projects the user is a member of, use GET /projects?membership=true
[x] Return HTTP status code 400 for all validation errors when creating or updating a member instead of sometimes 422 error. !9523. Doesn't require changes.
[x] Status 409 returned for POST /projects/:id/members when a member already exists !9093. Doesn't require changes.
[x] Remove GET /groups/owned. Use GET /groups?owned=true instead !9505. Fixed in commit 62634b8.
[x] Moved POST /projects/fork/:id to POST /projects/:id/fork !8940. Fixed in commit 577e19d.
[x] Renamed the merge_when_build_succeeds parameter to merge_when_pipeline_succeeds on the following endpoints: !9335
- PUT /projects/:id/merge_requests/:merge_request_id/merge
- POST /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_pipeline_succeeds
- POST /projects
- POST /projects/user/:user_id
- PUT /projects/:id
[x] Update endpoints for repository files !9637. Fixed in commit a0b1dcb.
- Moved GET /projects/:id/repository/files?file_path=:file_path to GET /projects/:id/repository/files/:file_path (:file_path should be URL-encoded)
- GET /projects/:id/repository/blobs/:sha now returns JSON attributes for the blob identified by :sha, instead of finding the commit identified by :sha and returning the raw content of the blob in that commit identified by the required ?filepath=:filepath
- Moved GET /projects/:id/repository/commits/:sha/blob?file_path=:file_path and GET /projects/:id/repository/blobs/:sha?file_path=:file_path to GET /projects/:id/repository/files/:file_path/raw?ref=:sha
- GET /projects/:id/repository/tree parameter ref_name has been renamed to ref for consistency
[x] Removed the following deprecated Templates endpoints (these are still accessible with /templates prefix) !8853
- /licences
- /licences/:key
- /gitignores
- /gitlab_ci_ymls
- /dockerfiles
- /gitignores/:key
- /gitlab_ci_ymls/:key
- /dockerfiles/:key
[x] Moved DELETE /todos to POST /todos/mark_as_done and DELETE /todos/:todo_id to POST /todos/:todo_id/mark_as_done !9410
[x] Return pagination headers for all endpoints that return an array !8606
[x] Removed DELETE /projects/:id/deploy_keys/:key_id/disable. Use DELETE /projects/:id/deploy_keys/:key_id instead !9366
[x] Moved PUT /users/:id/(block|unblock) to POST /users/:id/(block|unblock) !9371
[x] Make subscription API more RESTful. Use POST /projects/:id/:subscribable_type/:subscribable_id/subscribe to subscribe and POST /projects/:id/:subscribable_type/:subscribable_id/unsubscribe to unsubscribe from a resource. !9325
[x] Labels filter on GET /projects/:id/issues and GET /issues now matches only issues containing all labels (i.e.: Logical AND, not OR) !8849
[x] Renamed param branch_name to branch on the following endpoints !8936
- POST /projects/:id/repository/branches
- POST /projects/:id/repository/commits
- POST/PUT/DELETE :id/repository/files
[x] Renamed branch_name to branch on DELETE /projects/:id/repository/branches/:branch response !8936
[x] Remove public param from create and edit actions of projects !8736
[x] Remove subscribed field from responses returning list of issues or merge requests. Fetch individual issues or merge requests to obtain the value of subscribed !9661
[x] Notes do not return deprecated field upvote and downvote !9384
[x] Return 202 with JSON body on async removals on V4 API (DELETE /projects/:id/repository/merged_branches and DELETE /projects/:id) !9449
[x] GET /projects/:id/milestones?iid[]=x&iid[]=y array filter has been renamed to iids !9096
[x] Drop GET /projects/:id/repository/commits/:sha/jobs !9463
[x] Simplify project payload exposed on Environment endpoints !9675
[x] API uses merge request IIDs (internal ID, as in the web UI) rather than IDs. This affects the merge requests, award emoji, todos, and time tracking APIs. !9530
[x] API uses issue IIDs (internal ID, as in the web UI) rather than IDs. This affects the issues, award emoji, todos, and time tracking APIs. !9530
[x] Change initial page from 0 to 1 on GET /projects/:id/repository/commits (like on the rest of the API) [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
[x] Return correct Link header data for GET /projects/:id/repository/commits [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)

func (s *ProjectVariablesService) UpdateVariable(pid interface{}, key string, opt *UpdateVariableOptions, options ...OptionFunc) (*ProjectVariable, *Response, error) {
	project, err := parseID(pid)
	if err != nil {
		return nil, nil, err
	}
	u := fmt.Sprintf("projects/%s/variables/%s",
		url.QueryEscape(project),
		url.QueryEscape(key),
	)

You are accepting 2 "key" variables. In function and as a parameter of UpdateVariableOptions. Can we use just one instead of two? Does it make sense or am I missing something?

GitLab recently released an API to import/export projects.

Proposal would be to add support to go-gitlab for this: https://docs.gitlab.com/ee/api/project_import_export.html

enhancement

Hello there, this is a WIP. I'd like to get early feedback on the general direction of this work. I tried to be consistent with the existing codebase. I intent to add more tests, links to docs, etc and actually test against a real GitLab instance once the support is available (it's being worked on).

In this PR, a hook function OnFinished is added in gitlab client. It will be invoked at the end of each HTTP request, whether the result succeeds or fails. This feature will be very useful, which allows users to do some extra thing with the response and error. By the way, our team really needs this feature urgently. We want to monitor the request for gitlab server, and alarm when the call failure rate is greater than the threshold.

When adding a note to a MR I can also make this a thread which is showing as something that needs to be resolved before the MR will go through. I can not find this in the Gitlab API documentation...? Any idea how that would be used? Screenshot 2021-09-09 at 13 40 20

enhancement help wanted

Sort of a feature request, use cases may include private gitlab instance not doing the rate limiting itself and not returning rate limit headers and / or when someone wishes to limit load to lower than what's automatically configured.

Can make a pull request to add it, wanted some thoughts and considerations that I'm not thinking about :)

Thanks.

Filing this ticket not as a bug report, more as an awareness.

The test suites for the Gitlab Terraform & Pulumi providers became instable since Gitlab 12.6. After some investigation, it seems that soft-delete of Projects was introduced in that version by changing the behaviour of DELETE /projects/{id}.

More context here: https://github.com/terraform-providers/terraform-provider-gitlab/issues/263 which links to even more gitlab tickets.

So be aware that a delete is not necessarily a hard delete.

waiting

Is it possible to reference github's class library and use golang's class library to cause us to fail to download in China，I cannot go get golang.org/x/oauth2

in issues.go there's no method that wrap https://docs.gitlab.com/ee/api/issues.html#single-issue . It's not possible to Get an issue by id (whole instance id and not project id aka iid).

This PR add this method and to keep BC, I've name it GetIssueByID but a imho a better name would be GetIssue and we could replace the actual GetIssue by GetProjectIssue, but anyway, both possibilities are fine. Added tests too.

I marked the two functions BranchesService.ProtectBranch() & BranchesService.UnprotectBranch() as deprecated, since they are replaced by the protected branches API.

In the ProtectedBranchesService I added some missing options, and renamed the RequireCodeOwnerApprovals() function to UpdateProtectedBranch() which has some additional options. (I kept the RequireCodeOwnerApprovals() function and marked it as deprecated.)

with the following code running towards gitlab.com:

import (
	"fmt"
	"github.com/xanzy/go-gitlab"
	"log"
	"os"
)


client, err := gitlab.NewClient(os.Getenv("GITLAB_READ_API_TOKEN"))

if err != nil {
        log.Fatalf("Failed to create client: %v", err)
}

var listOptions = gitlab.ListOptions{
	Page:    1,
	PerPage: 100,
}
var groupOptions = gitlab.ListGroupPackagesOptions{
	ListOptions:      listOptions,
	ExcludeSubGroups: gitlab.Bool(false),
	PackageType:      gitlab.String("nuget"),
}

packages, response, err := client.Packages.ListGroupPackages("YOUR_GROUP_ID", &groupOptions)

I get the error:

Failed call to group endpoint with error: 'json: cannot unmarshal object into Go struct field GroupPackage.tags of type string'

I guess this is due to that our nuget packages contains tags. I've used curl to get the response and found one with many tags, hopefully that is some data to test on:

command to get data:

curl --silent --header "PRIVATE-TOKEN: $GITLAB_READ_API_TOKEN" "https://gitlab.com/api/v4/groups/YOUR_GROUP_ID_HERE/packages?exclude_subgroups=false&package_type=nuget&per_page=100&page=1" | jq '.[].tags'

and relevant data from me with IDs replaces with 1 and 2, for having valid data.

...
[
  {
    "id": 1,
    "package_id": 2,
    "name": "convention",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  },
  {
    "id": 1,
    "package_id": 2,
    "name": "package",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  },
  {
    "id": 1,
    "package_id": 2,
    "name": "build",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  },
  {
    "id": 1,
    "package_id": 2,
    "name": "Output",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  },
  {
    "id": 1,
    "package_id": 2,
    "name": "Copy",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  },
  {
    "id": 1,
    "package_id": 2,
    "name": "Targets",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  },
  {
    "id": 1,
    "package_id": 2,
    "name": "Nuget",
    "created_at": "2021-05-07T11:47:23.118Z",
    "updated_at": "2021-05-07T11:47:23.118Z"
  }
]
...

It also seems like response.TotalPages is always 0.

bug help wanted