Coop Symbiotic uses Gitlab for project management and technical support. Gitlab includes features such as tracking requests, code changes and some automation tools. If you are familiar with Github, JIRA or Trello, Gitlab is very similar.
Questions, bugs, or requests for a new feature should be tracked in Gitlab. By using Gitlab, we can ensure that requests are documented, prioritized and resolved. This can be a very helpful source of documentation both for Symbiotic and for your organization. For example, if a colleague is absent, another colleague can continue the work.
This guide explains how to use Gitlab. We thank you in advance for taking a few moments to learn how to use this tool. It ensures more efficient communication, faster response times, overall lower costs and a more sustainable relationship.
Gitlab user account
Each organization has their own private space on our Gitlab. Members of your organization can access it by connecting to Gitlab with a user account. Symbiotic creates the user accounts during the on-boarding. If there are new members in your team, we can create an account for them (and disable their account if they leave). To request changes to an account, you can open an issue (more on that later).
Once we create the Gitlab account, you will receive an email notification. Please check your spam folder if you have not received it.
Here is how it looks like:
From: Lab SymbioTIC (gitlab at symbiotic.coop)
Subject: Account was created for you
Hi!
The Administrator created an account for you. Now you are a member of the company GitLab application.
login.......................................... you@example.org
Click here to set your password
This link is valid for 2 days. After it expires, you can request a new one.
—
View it on GitLab.
You're receiving this email because of your account on lab.symbiotic.coop.
If you'd like to receive fewer emails, you can adjust your notification settings.
To enable your account and set a password, click on the link "Click here to set your password". We recommend that you set a strong password and save it in a password manager for convenience. Please never re-use the same password between sites, as this is a very common way to be hacked. We will see later how to enable two-factor authentication for more security.
Login to Gitlab
While it might seem obvious to some, the login button might be easy to miss:
Clicking this button will lead you to the login page, where you can also ask for a password reset, if necessary.
Two-factor authentication
For high-risk projects, we strongly recommend enabling two-factor authentication (2FA). In addition to supplying your username and password to sign in, you will be prompted for your two-factor code (for example, the "Google Authenticator" or "Authy" app on your mobile device). By enabling 2FA, the only way someone other than you can sign in to your account is to know your username and password and have access to your one-time password secret.
To enable two-factor authentication, go to your account profile:
Then click on "enable two-factor authentication" and follow the indications on the screen.
Your organization's project space
Once connected to Gitlab, you will have access to the project space of your organization:
Each organization has their own private space on our Gitlab. Technically, it's a group for the organization, and inside that group there is usually just one project.
Creating a new request (issue)
Gitlab uses the term "issue" for anything that might be a question, a feature request or a bug report.
To create a new issue, go to the project space for your organization (as described in the previous section), then navigate to the issues screen:
From that screen you can view existing issues, and also create a new issue:
This leads to the form to enter the details of the new issue. The important fields have been highlighted:
- Title: a short, descriptive summary of the error.
- Description: describe the request or bug report. Please be brief, but include the following information:
- What are the exact steps to reproduce the error? Example: "I clicked on New Contact, then entered ABC in Field-A, then clicked the Save button".
- Is there an error message? If yes, please copy-paste the error, or include a screenshot.
- Is the problem happening in a specific situation? If yes, please be as specific as possible. For example, maybe we cannot save a contact record. Maybe it affects all contacts records, but maybe not. We might test it and not be able to reproduce it, which will add a 24h delay. If you encountered the problem with a specific contact, please provide a link to that contact record.
- In general, please include direct links (URL) to the page described. This can save us a few minutes, trying to find the right location.
- If possible, please include a screenshot, including the location bar of the browser (URL). This can provide important details of the context and avoid any misunderstandings. You can attach screenshots by clicking on the "Attach a file" link.
You can ignore the other fields. We might use them to facilitate project management on our end. Please note that setting a "Due Date" does not guarantee a resolution date. The response and resolution time depend on your service level agreement (SLA). Otherwise, we try to respond to requests as quickly as possible, but this depends on our capacity and other engagements. Also depending on your hosting or support agreement, we may charge up to 1 hour of time for a request. If we cannot complete the request within 1 hour, we will provide an estimate and wait for your approval before incurring any further costs.
Once the issue is saved, it will have its own issue identifier (ID) and a unique URL. For example: https://lab.symbiotic.coop/myorg/myproject/issues/123 This is important because it saves a lot of time when communicating by phone or chat, to say "please see issue #123 on Gitlab" (and ideally, copy-paste the URL), instead of, for example, "can you fix the bug I sent you?". We also use these IDs for tracking our time.
Commenting on an issue
We might comment on the issue and then re-assign it to you, either to clarify the requirements or to validate the resolution.
It is also possible to reply directly to email notifications, however, we recommend using the Gitlab user interface, since the end result will be more clear and structured.
Closing an issue
Once an issue is considered resolved, we will wait for your confirmation in Gitlab. You can also click the "close" button to close the issue:
Issue board
The issue board can help provide a global view of the project. It also helps to set priorities. To access it, click on the "Issues" menu, then "Boards":
Here is an example board:
You can drag and drop cards from one column to another, and also sort cards within a column. The first card in a column is the one with the highest priority.
Managing email notifications
Depending on the project, you may find that you are receiving too many notifications from Gitlab. It is possible to change the notification preferences to only receive an email when you are explicitly mentioned:
Urgent issues
For urgent issues, we recommend to 1) add the label "urgent" to the issue, and 2) mention "URGENT" in the subject. The former is to help triage issue, and the later triggers our email filters.
The response time to urgent issues depends on your your support agreement. This agreement also usually clarifies if you can contact us using another communication medium, such as Signal, phone or email.
If you do not have a support agreement, please use our contact form. Please mention the Gitlab issue number/link in your message (and write "urgent" in the subject of the Gitlab issue). It will be received by multiple people at the same time. We strongly recommend the above form, instead of phone, since we do not often check our voicemail. Emergency requests for which Symbiotic is not responsible may result in additional fees (minimum 1h of work at double the regular hourly rate).
Wiki documentation
A wiki is an ad-hoc documentation structure. We often use this space to keep notes or to write documentation on how to do specific actions.
The right side of the screen has a list of all pages. The "home" page sometimes only lists a few links to the most important pages.
Security
Gitlab helps improve the security of communications in a few ways:
- It helps us to authenticate requests, that we are communicating with the right person. It would be easy to falsify an email to ask us to reset your password, create a new admin account, etc.
- We host our own instance of Gitlab, on our own servers, which lets us maintain more control on who has access to the data, and where it is stored.
- Information sent on Gitlab is automatically encrypted (using https). Gitlab might send an email notification, but we also host our own email server, and communication between the two is encrypted.
