go-gitlab

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

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:

• Applications
• Award Emojis
• Branches
• Broadcast Messages
• Commits
• Container Registry
• Custom Attributes
• Deploy Keys
• Deployments
• Discussions (threaded comments)
• Environments
• Epic Issues
• Epics
• Events
• Feature Flags
• Geo Nodes
• Generic Packages
• GitLab CI Config Templates
• Gitignores Templates
• Group Access Requests
• Group Issue Boards
• Group Members
• Group Milestones
• Group Wikis
• Group-Level Variables
• Groups
• Instance Clusters
• Invites
• Issue Boards
• Issues
• Jobs
• Keys
• Labels
• License
• Markdown
• Merge Request Approvals
• Merge Requests
• Namespaces
• Notes (comments)
• Notification Settings
• Open Source License Templates
• Packages
• Pages
• Pages Domains
• Personal Access Tokens
• Pipeline Schedules
• Pipeline Triggers
• Pipelines
• Plan limits
• Project Access Requests
• Project Badges
• Project Clusters
• Project Import/export
• Project Members
• Project Milestones
• Project Snippets
• Project-Level Variables
• Projects (including setting Webhooks)
• Protected Branches
• Protected Environments
• Protected Tags
• Repositories
• Repository Files
• Repository Submodules
• Runners
• Search
• Services
• Settings
• Sidekiq Metrics
• System Hooks
• Tags
• Todos
• Users
• Validate CI Configuration
• Version
• Wikis

Development

Use a Remote Environment via GitPod

You can choose to use your own development environment if desired, however a .gitpod.yml file is included within the repository to allow the use of GitPod easily. This will allow you to use GitPod's integration with GitHub to quickly start a web-based development environment including Go and Docker, which are necessary for running tests. To use GitPod's integration, you have two different options described below. After you've completed one of the two options, your development environment will be ready within a minute or two. As part of starting up, your development environment will automatically start up the gitlab-ce container necessary for running tests.

Option 1: Manually navigate to GitPod

You can manually sign in and open your workspace within GitPod by following these steps:

1. Navigate to GitPod
2. Click Login if you have an account, or Sign Up if you do not.
3. Click on "Continue with GitHub" and authorize GitPod to access your account.
4. After you've signed in, select "Projects" along the top menu, click on your forked go-gitlab project
5. Hover over either the main branch for your fork or the branch you created for your fork, and click "New Workspace"

Option 2: Open your GitPod Workspace directly via URL

1. Navigate to your fork of the go-gitlab project in GitHub
2. Select the branch you want to develop
3. Add https://gitpod.io/# to the front of your URL

Your workspace will automatically open the repository and branch that you selected in GitHub.

Testing individual go-gitlab services with GitPods

Once a GitPod has started up with the gitlab-ce container service running, port 8080 will be exposed for API calls where each individual go-gitlab service can be tested against. Please note that the ce container service is started by default and to test any ee go-gitlab service you will need to have a valid license file provided in the top level directory named Gitlab-license.txt. Then modify the GNUmakefile to set the SERVICE variable to gitlab-ee instead of gitlab-ce. Once these modifications are done run make testacc-down to stop the current ce container service and then run make testacc-up to start the new ee container service

• Connection Information
  • PAT/API Token: ACCTEST1234567890123
  • API URL: http://127.0.0.1:8080/api/v4/

1. Create a dummy testing file (something.go, main.go, etc.) where you will be testing the services you are developing
2. Follow the format of one of the services under the examples folder
3. Set the connection information to the above for the GitLab client
4. On the terminal enter go run <filename.go> to run the test file that was created against the local gitlab container service

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