# Import from GitLab

> Connect gitlab.com through By Dawn's GitLab app, or a self-managed GitLab through an OAuth application you add on it, pick a group or project, and check how its labels, epics and iterations map.

This page helps you bring a GitLab group or project into By Dawn, from gitlab.com or your own GitLab. At the end its
issues are By Dawn tickets, its epics are By Dawn epics, and, if you chose to keep syncing, the two stay in step until
your end date. [Import and sync](https://docs.bydawn.com/import-and-sync/) explains the steps every tracker shares, so this page
covers only what's particular to GitLab.

## Before you start

- You need to be a project admin in By Dawn, and an **org admin** has to approve the GitLab app (see
  [Before you start](https://docs.bydawn.com/import-and-sync/#before-you-start)).
- **The grant acts as the person who approves it.** By Dawn works in GitLab as that user: it sees the groups and
  projects they can see, and its changes show under their name. Approve it as someone who can see everything you
  want to bring, or as a dedicated GitLab user if you don't want By Dawn's changes under your own name. For a sync,
  By Dawn also adds webhooks as that user, which GitLab allows a Maintainer of a project or an Owner of a group. Without
  that role the sync still works, but changes reach By Dawn on its regular check rather than within a minute.
- A self-managed GitLab must be reachable from the internet over `https`. By Dawn won't call a private or internal
  address, so that a connection can never be pointed at By Dawn's own network.

## Connect gitlab.com

1. Sign in to gitlab.com as the user By Dawn should act as.

2. In By Dawn, open **Settings › Import & sync › New import**, pick **GitLab** and choose **Connect GitLab.com**.

3. GitLab asks you to authorize By Dawn with the `api` scope. By Dawn needs it to read issues, write them back when you
   sync both ways, and set up its webhooks. Choose **Authorize**.

4. GitLab sends you back to By Dawn, and the page shows the connected GitLab user.

## Connect a self-managed GitLab

A gitlab.com app can't sign anyone in to another GitLab, so for your own instance you add an OAuth application on
it and give By Dawn its details. You do this once per instance, and then every import in your organization can
connect through it.

1. In By Dawn, open **Settings › Import & sync › New import**, pick **GitLab** and choose **Self-managed: connect your
   GitLab app**. The form shows a **Redirect URI**. Copy it.

2. On your GitLab instance, add an application. An instance admin can do this under **Admin › Applications**, or
   you can add it under a group's or your own **Settings › Applications**. Fill in:
   - **Name**: `SAW`;
   - **Redirect URI**: the one you copied;
   - **Confidential**: on;
   - **Scopes**: `api`.

   Save it, and copy the **Application ID** and **Secret** that GitLab shows.

3. Back in By Dawn, fill in:
   - **GitLab URL**: your instance's address, such as `https://code.example.com`. It may include a path, such as
     `https://code.example.com/gitlab`;
   - **Application ID** and **Secret**: the ones you copied.

4. Choose **Register and connect**. By Dawn saves the application and sends you to your instance to authorize it, as
   in [Connect gitlab.com](#connect-gitlabcom).

By Dawn seals the secret and never shows it again. The next time you connect this instance, choose it from **Your
self-managed GitLab apps**. To replace the application's ID and secret, register the same URL again. To stop using
it, remove it from that list.

## Pick what to bring

- **Group**: every issue in a group and its subgroups, and the group's epics.
- **Project**: one project's issues, plus the epics of the group it belongs to. Choose this if you might create
  tickets in By Dawn that should appear in GitLab, because a new issue needs a project to go into.

All of the group's or project's issues come over, open and closed.

## How GitLab maps

- **Statuses.** Open issues go to a to-do column and closed ones to a completed column. If your boards use
  scoped labels such as `workflow::In review`, each of those becomes a status of its own that you map to a
  column, and they aren't imported as labels.
- **Priorities.** GitLab has no priority field, so tickets come in with no priority.
- **Epics** become By Dawn epics. Epics need GitLab Premium or Ultimate; on the Free tier there are none, and the
  import carries on without them.
- **Tasks** under an issue become sub-tickets.
- **Milestones** become By Dawn milestones in one epic, or `milestone:` labels.
- **Iterations** can become By Dawn cycles, `sprint:` labels, or nothing.
- **Descriptions** are already markdown, so they come over as written.

## When you sync both ways

By Dawn writes back the title, description, open or closed state, the first assignee and labels, plus new comments.
Epics are only read, never changed. New tickets you create in By Dawn are created in GitLab only on a connection
scoped to a project.

> **Note:** By Dawn sets up GitLab webhooks when a sync starts: one on the group where your GitLab plan supports group webhooks,
> or one on each project otherwise. So an edit in GitLab usually reaches By Dawn within a minute, and By Dawn removes the
> webhooks when the sync ends. Its regular check every few minutes catches anything a webhook missed.

## Where to go next

- [Import and sync](https://docs.bydawn.com/import-and-sync/): conflicts, pausing and ending a sync.

Source: https://docs.bydawn.com/import-gitlab/