Skip to content
Docs
Engineering

GitLab

Let hires read merge requests, issues, pipelines and files, comment, and open issues and merge requests, on GitLab.com or your own GitLab.

Explore 10 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With GitLab (open source), a hire can:

  • list merge requests and read one with its description, the files it changes (lines added and removed) and its pipeline,
  • list issues and read one with its latest comments,
  • read a file at a branch, tag or commit,
  • check recent CI pipelines, by branch or status,
  • comment on issues and merge requests, open issues, and open a merge request from a branch it pushed.

It works the same on GitLab.com and on a GitLab you run yourself. Code changes go through git in the hire's own workspace; GitLab is where it opens the merge request and talks about it.

1. Make a token in GitLab

The quickest is a personal access token: the form in Roster links to GitLab's token page (on your own GitLab's address if you run one) with the name Roster and the api scope already filled in. Set an expiry, click Create token and copy it. It starts with glpat-.

Any of these works; pick the narrowest that covers what hires should reach:

  • Project access token: in the project, Settings → Access tokens. One project only.
  • Group access token: in the group, Settings → Access tokens. Every project in the group.
  • Personal access token: your avatar → Edit profile → Access tokens. What hires do shows as you, so you may want a GitLab user just for Roster.

Give it the Developer role (for project and group tokens) and the api scope. For hires that only read, read_api is enough. Copy the token.

Or an OAuth application

Instead of a token, you can add an application in GitLab (Edit profile → Applications, or the group's or instance's) with the api scope and the callback address Roster shows on the connection. It ends in /api/integrations/gitlab/oauth/callback. Choose An OAuth application of yours in Roster, paste its ID and secret, and click Connect with GitLab.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for GitLab and choose it.
  2. How Roster signs in: leave Access token, and paste the token.
  3. GitLab address: leave https://gitlab.com for GitLab.com. If you run GitLab yourself, put its address, like https://gitlab.example.com (with any path, like /gitlab).
  4. Click Connect. Roster asks GitLab who the token belongs to, and the connection shows Connected as that user (a bot user for project and group tokens). If GitLab refuses the token, Roster says so and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on GitLab:

  • Read only: it can read merge requests, issues, files and pipelines, and nothing else.
  • Read and write: it can also comment, open issues and open merge requests.
  • Projects: paths like acme/website or acme/web/app, one per line. Leave it empty for every project the token can reach. Anything outside the list is refused.

Hires refer to merge requests as !7 and issues as #3, the way GitLab does. A merge request opened as a draft is marked Draft: so nobody merges it by accident.

Watching for changes

With projects listed, a hire's responsibility can watch GitLab: when issues or merge requests in those projects change, the hire is woken with the list. Checking costs nothing when nothing changed.

If something goes wrong

  • "Didn't accept the connection's credential": the token expired or was revoked. GitLab tokens have an expiry date; make a new one and paste it on the connection.
  • "Doesn't allow this": the token's role or scope is too small (for example read_api when the hire tried to comment).
  • "Couldn't find that": the project path is wrong, or the token can't see that project.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect GitLab and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

A personal, group or project access token with the api scope (read_api for hires that only read).

For: How Roster signs in: Access token (personal, group or project).

OAuth 2.0

From the application you added in GitLab (User settings → Applications, or the group's or instance's).

For: How Roster signs in: An OAuth application of yours.

Requested scopes:

  • api

When making a key, use these permissions from the connection guide:

  • api (or read_api for hires that only read)

Connection fields

GitLab connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		An access token is quickest. An OAuth application lets someone approve Roster in GitLab instead.

Choices: Access token (personal, group or project) (token); An OAuth application of yours (oauth).

Starts with: token.

Access token
token
Required · sealed secret		A personal, group or project access token with the api scope (read_api for hires that only read).

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From the application you added in GitLab (User settings → Applications, or the group's or instance's).

Shown when signIn: oauth.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

GitLab address
url
Optional		Leave as it is for GitLab.com. Self-managed: your GitLab's address, like https://gitlab.example.com.

Starts with: https://gitlab.com.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

GitLab per-hire limits
FieldWhat to provide
Projects
projects
Optional		group/project (or group/subgroup/project), one per line. Leave empty for every project the token can reach.

Actions

10 actions: 7 only read and 3 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

10 of 10 actions. Open an action for its arguments and full input schema.

list_projectsRead only

The GitLab projects this hire can use.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_merge_requestsRead only

Merge requests in a project, most recently updated first.

Approval: Uses your workspace and hire approval settings.

Arguments for list_merge_requests
ArgumentTypeDetails
projectRequiredstringgroup/project
stateOptional"opened" | "closed" | "merged" | "all"See input schema below.Default: "opened"
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "state": {
      "default": "opened",
      "type": "string",
      "enum": [
        "opened",
        "closed",
        "merged",
        "all"
      ]
    }
  },
  "required": [
    "project"
  ]
}
get_merge_requestRead only

A merge request's description, changed files with lines added and removed, and pipeline status.

Approval: Uses your workspace and hire approval settings.

Arguments for get_merge_request
ArgumentTypeDetails
projectRequiredstringgroup/project
iidRequiredintegerSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "iid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "project",
    "iid"
  ]
}
list_issuesRead only

Issues in a project, most recently updated first.

Approval: Uses your workspace and hire approval settings.

Arguments for list_issues
ArgumentTypeDetails
projectRequiredstringgroup/project
stateOptional"opened" | "closed" | "all"See input schema below.Default: "opened"
labelsOptionalstringcomma-separated
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "state": {
      "default": "opened",
      "type": "string",
      "enum": [
        "opened",
        "closed",
        "all"
      ]
    },
    "labels": {
      "description": "comma-separated",
      "type": "string"
    }
  },
  "required": [
    "project"
  ]
}
get_issueRead only

An issue's description and its latest comments.

Approval: Uses your workspace and hire approval settings.

Arguments for get_issue
ArgumentTypeDetails
projectRequiredstringgroup/project
iidRequiredintegerSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "iid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "project",
    "iid"
  ]
}
get_fileRead only

Read a file from a project at a branch, tag or commit (default branch if omitted).

Approval: Uses your workspace and hire approval settings.

Arguments for get_file
ArgumentTypeDetails
projectRequiredstringgroup/project
pathRequiredstringSee input schema below.
refOptionalstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "path": {
      "type": "string",
      "minLength": 1
    },
    "ref": {
      "type": "string"
    }
  },
  "required": [
    "project",
    "path"
  ]
}
list_pipelinesRead only

Recent CI pipelines, to check CI. Filter by branch or status (e.g. failed).

Approval: Uses your workspace and hire approval settings.

Arguments for list_pipelines
ArgumentTypeDetails
projectRequiredstringgroup/project
refOptionalstringa branch or tag
statusOptional"created" | "waiting_for_resource" | "preparing" | "pending" | "running" | "success" | "failed" | "canceled" | "skipped" | "manual" | "scheduled"See input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "ref": {
      "description": "a branch or tag",
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "created",
        "waiting_for_resource",
        "preparing",
        "pending",
        "running",
        "success",
        "failed",
        "canceled",
        "skipped",
        "manual",
        "scheduled"
      ]
    }
  },
  "required": [
    "project"
  ]
}
commentRead and write

Comment on an issue or a merge request.

Approval: Uses your workspace and hire approval settings.

Arguments for comment
ArgumentTypeDetails
projectRequiredstringgroup/project
onRequired"issue" | "merge_request"See input schema below.
iidRequiredintegerSee input schema below.
bodyRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "on": {
      "type": "string",
      "enum": [
        "issue",
        "merge_request"
      ]
    },
    "iid": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "body": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "project",
    "on",
    "iid",
    "body"
  ]
}
create_issueRead and write

Open a new issue.

Approval: Uses your workspace and hire approval settings.

Arguments for create_issue
ArgumentTypeDetails
projectRequiredstringgroup/project
titleRequiredstringSee input schema below.
descriptionOptionalstringSee input schema below.Default: ""
labelsOptionalstring[]See input schema below.Default: []
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "default": "",
      "type": "string"
    },
    "labels": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    }
  },
  "required": [
    "project",
    "title"
  ]
}
create_merge_requestRead and write

Open a merge request from a branch already pushed (with git in the workdir) into the target branch (default: the project's default branch).

Approval: Uses your workspace and hire approval settings.

Arguments for create_merge_request
ArgumentTypeDetails
projectRequiredstringgroup/project
source_branchRequiredstringSee input schema below.
target_branchOptionalstringSee input schema below.
titleRequiredstringSee input schema below.
descriptionOptionalstringSee input schema below.Default: ""
draftOptionalbooleanSee input schema below.Default: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "pattern": "^(?:(?!\\.{1,2}\\/)[\\w.-]+\\/){1,19}(?!\\.{1,2}$)[\\w.-]+$",
      "description": "group/project"
    },
    "source_branch": {
      "type": "string"
    },
    "target_branch": {
      "type": "string"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "default": "",
      "type": "string"
    },
    "draft": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "project",
    "source_branch",
    "title"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

GitHub

Let hires read and work on pull requests, issues, files and CI, as themselves or with a shared token.

Postman

API collections, environments and workspaces.

On this page

1. Make a token in GitLab2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference