1# go-gitlab
2
3A GitLab API client enabling Go programs to interact with GitLab in a simple and uniform way
4
5[](https://travis-ci.org/xanzy/go-gitlab)
6[](https://github.com/xanzy/go-gitlab/blob/master/LICENSE)
7[](https://sourcegraph.com/github.com/xanzy/go-gitlab?badge)
8[](https://godoc.org/github.com/xanzy/go-gitlab)
9[](https://goreportcard.com/report/github.com/xanzy/go-gitlab)
10[](https://github.com/xanzy/go-gitlab/issues)
11
12## NOTE
13
14Release v0.6.0 (released on 25-08-2017) no longer supports the older V3 Gitlab API. If
15you need V3 support, please use the `f-api-v3` branch. This release contains some backwards
16incompatible changes that were needed to fully support the V4 Gitlab API.
17
18## Coverage
19
20This API client package covers most of the existing Gitlab API calls and is updated regularly
21to add new and/or missing endpoints. Currently the following services are supported:
22
23- [x] Award Emojis
24- [x] Branches
25- [x] Broadcast Messages
26- [x] Commits
27- [x] Container Registry
28- [x] Custom Attributes
29- [x] Deploy Keys
30- [x] Deployments
31- [ ] Discussions (threaded comments)
32- [x] Environments
33- [ ] Epic Issues
34- [ ] Epics
35- [x] Events
36- [x] Feature Flags
37- [ ] Geo Nodes
38- [x] GitLab CI Config Templates
39- [x] Gitignores Templates
40- [x] Group Access Requests
41- [x] Group Issue Boards
42- [x] Group Members
43- [x] Group Milestones
44- [x] Group-Level Variables
45- [x] Groups
46- [x] Issue Boards
47- [x] Issues
48- [x] Jobs
49- [x] Keys
50- [x] Labels
51- [x] License
52- [x] Merge Request Approvals
53- [x] Merge Requests
54- [x] Namespaces
55- [x] Notes (comments)
56- [x] Notification Settings
57- [x] Open Source License Templates
58- [x] Pages Domains
59- [x] Pipeline Schedules
60- [x] Pipeline Triggers
61- [x] Pipelines
62- [x] Project Access Requests
63- [x] Project Badges
64- [x] Project Clusters
65- [x] Project Import/export
66- [x] Project Members
67- [x] Project Milestones
68- [x] Project Snippets
69- [x] Project-Level Variables
70- [x] Projects (including setting Webhooks)
71- [x] Protected Branches
72- [x] Protected Tags
73- [x] Repositories
74- [x] Repository Files
75- [x] Runners
76- [x] Search
77- [x] Services
78- [x] Settings
79- [x] Sidekiq Metrics
80- [x] System Hooks
81- [x] Tags
82- [x] Todos
83- [x] Users
84- [x] Validate CI Configuration
85- [x] Version
86- [x] Wikis
87
88## Usage
89
90```go
91import "github.com/xanzy/go-gitlab"
92```
93
94Construct a new GitLab client, then use the various services on the client to
95access different parts of the GitLab API. For example, to list all
96users:
97
98```go
99git := gitlab.NewClient(nil, "yourtokengoeshere")
100//git.SetBaseURL("https://git.mydomain.com/api/v4")
101users, _, err := git.Users.ListUsers(&gitlab.ListUsersOptions{})
102```
103
104Some API methods have optional parameters that can be passed. For example,
105to list all projects for user "svanharmelen":
106
107```go
108git := gitlab.NewClient(nil)
109opt := &ListProjectsOptions{Search: gitlab.String("svanharmelen")}
110projects, _, err := git.Projects.ListProjects(opt)
111```
112
113### Examples
114
115The [examples](https://github.com/xanzy/go-gitlab/tree/master/examples) directory
116contains a couple for clear examples, of which one is partially listed here as well:
117
118```go
119package main
120
121import (
122 "log"
123
124 "github.com/xanzy/go-gitlab"
125)
126
127func main() {
128 git := gitlab.NewClient(nil, "yourtokengoeshere")
129
130 // Create new project
131 p := &gitlab.CreateProjectOptions{
132 Name: gitlab.String("My Project"),
133 Description: gitlab.String("Just a test project to play with"),
134 MergeRequestsEnabled: gitlab.Bool(true),
135 SnippetsEnabled: gitlab.Bool(true),
136 Visibility: gitlab.Visibility(gitlab.PublicVisibility),
137 }
138 project, _, err := git.Projects.CreateProject(p)
139 if err != nil {
140 log.Fatal(err)
141 }
142
143 // Add a new snippet
144 s := &gitlab.CreateProjectSnippetOptions{
145 Title: gitlab.String("Dummy Snippet"),
146 FileName: gitlab.String("snippet.go"),
147 Code: gitlab.String("package main...."),
148 Visibility: gitlab.Visibility(gitlab.PublicVisibility),
149 }
150 _, _, err = git.ProjectSnippets.CreateSnippet(project.ID, s)
151 if err != nil {
152 log.Fatal(err)
153 }
154}
155```
156
157For complete usage of go-gitlab, see the full [package docs](https://godoc.org/github.com/xanzy/go-gitlab).
158
159## ToDo
160
161- The biggest thing this package still needs is tests :disappointed:
162
163## Issues
164
165- If you have an issue: report it on the [issue tracker](https://github.com/xanzy/go-gitlab/issues)
166
167## Author
168
169Sander van Harmelen (<sander@xanzy.io>)
170
171## License
172
173Licensed 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>