GitLab

Connect a GitLab project to manage its issues and merge requests and to react to project activity. metamorphOS creates and updates issues, opens and merges merge requests, and posts comments, and GitLab notifies metamorphOS by webhook when an issue or merge request changes. Works with gitlab.com and self-hosted GitLab.

What you can do

• Issues: create, look up, list, and update issues, including closing and reopening them, assigning users, and applying labels.
• Comments: add a comment to an issue and list an issue’s comments.
• Merge requests: create, look up, list, and merge merge requests.
• Projects: look up a project’s details.
• Issue events: trigger a process automatically when an issue is opened or closed.
• Merge events: trigger a process automatically when a merge request is merged.

Before you start

You need a GitLab account and permission to create an application in the settings scope you want the connector to act in: your own user settings, a group you administer, or (on self-hosted GitLab) the instance admin area. To receive events, you also need permission to add a webhook to the project or group.

Set up GitLab

1. Create an application. In GitLab, open Applications under the scope you want the connector to act in:

   • User: User Settings -> Applications (acts as you).
   • Group: Group -> Settings -> Applications (group-owned).
   • Instance (self-hosted admin): Admin Area -> Applications (instance-wide).

   Create a new application and give it a name (for example, metamorphOS).

2. Keep it confidential. Leave Confidential enabled. The connector signs in with a client secret, so the application must be confidential.

3. Set the redirect URI. Set the application’s Redirect URI to the callback URL metamorphOS provides for this connector. It must match exactly, including scheme and path.

4. Grant access. Grant the api scope, which allows the connector to read and write issues, merge requests, and comments. If you only need read access, read_api is enough for the look-up and list actions.

5. Copy the credentials. Save the application, then copy the generated Application ID and Secret. You need both to connect in metamorphOS.

Connect in metamorphOS

Activate the GitLab connector from the marketplace, add an account, and connect:

• Enter the Application ID and Secret from the step above, then complete the GitLab consent screen to authorize access. GitLab returns you to metamorphOS once you approve.
• Host: for self-hosted GitLab, supply your GitLab host so the connector targets your instance instead of gitlab.com. Each account can point at a different host, and the default is gitlab.com.

Receive events (webhooks)

To trigger a process when an issue or merge request changes, add a webhook in GitLab that points at metamorphOS:

• In Project -> Settings -> Webhooks (or Group -> Settings -> Webhooks to cover every project in a group), set the URL to the receiver URL metamorphOS provides for this connector.
• Under Trigger events, enable Issues events (for issue opened and closed) and Merge request events (for merges). Leave the rest off. Keep SSL verification enabled.
• Set a Secret token to a value you choose, and supply that same value to metamorphOS as the connector’s webhook signing secret. GitLab sends the token with every delivery, and metamorphOS rejects any delivery whose token does not match.

Good to know

• Each account works with one project at a time, addressed by its numeric ID or its namespace/project path.
• Field coverage is a representative subset of GitLab’s data, so some advanced fields on issues, merge requests, and comments may not be available yet.