Import from GitLab

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 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).
• 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.

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: conflicts, pausing and ending a sync.