2 releases
new 0.2.5 | Apr 30, 2025 |
---|---|
0.2.4 | Apr 30, 2025 |
#54 in Visualization
2MB
34K
SLoC
📊 GitLab Activity Plugin for MOT
Integrates your GitLab commit activity directly into MOT, allowing you to view and potentially import commit data as time entries.
✨ Features
- 🦊 Fetches commit data from one or more GitLab instances (self-hosted or gitlab.com).
- 👤 Filters commits based on author email.
- 📅 Displays commit history within MOT's weekly view.
- 🔌 Seamlessly integrates with the MOT plugin system.
- ⚙️ Configurable via a simple TOML file.
- 🐧 Includes an easy-to-use installation script for Linux/macOS.
- ⚡️ In-Memory Caching: Improves performance for repeated requests of past date ranges by caching results in memory. The cache is cleared when the plugin process exits.
🚀 Installation
This plugin is designed to be installed using the provided script within its distribution package.
Prerequisites
- MOT: You must have MOT installed and configured. See the MOT Installation Guide.
- GitLab Personal Access Token: You need a Personal Access Token from each GitLab instance you want to connect to. The token requires the
read_api
scope.- Create one at:
https://[your_gitlab_host]/-/profile/personal_access_tokens
(replace[your_gitlab_host]
with your GitLab instance's hostname, e.g.,gitlab.com
).
- Create one at:
Steps (Linux / macOS)
-
Download and Extract: Obtain the plugin release package (e.g.,
mot-plugin-gitlab-vX.Y.Z.tar.gz
or.zip
) and extract it. You should find these core files:mot-plugin-gitlab
(the executable)manifest.toml
(plugin metadata)config.toml
(configuration template)install.sh
(installation script)Readme.md
(this file)
-
Navigate: Open your terminal and
cd
into the extracted directory:cd /path/to/extracted/mot-plugin-gitlab
-
Run Installer: Execute the installation script:
bash ./install.sh
- This copies the plugin files (
mot-plugin-gitlab
,manifest.toml
,config.toml
) to the correct Mot plugin directory (~/.config/mot/plugins/mot-plugin-gitlab/
). - It sets execute permissions for the plugin binary.
- Note: If a
config.toml
already exists in the destination, it will not be overwritten.
- This copies the plugin files (
-
Configure: Proceed to the Configuration section below. This step is essential.
-
Restart MOT: Close and reopen MOT to load the new plugin.
🔧 Configuration
After installation, you must configure the plugin by editing its configuration file.
-
Location: The configuration file is located at:
- Linux/macOS:
~/.config/mot/plugins/mot-plugin-gitlab/config.toml
- Windows:
%APPDATA%\mot\plugins\mot-plugin-gitlab\config.toml
(Manual installation might be needed for Windows currently)
- Linux/macOS:
-
Editing: Open the
config.toml
file in a text editor. You need to provide details for each GitLab instance you wish to monitor within[[clients]]
blocks.# Example config.toml for mot-plugin-gitlab # Global setting for the plugin (part of manifest/standard plugin config) enabled = true # Define one or more GitLab instances to connect to [[clients]] id = "gitlab-com" # Unique identifier for this client block name = "GitLab.com Personal" # User-friendly name shown in MOT (optional) gitlab_host = "gitlab.com" gitlab_token = "YOUR_GITLAB.COM_ACCESS_TOKEN" # Replace with your actual token author_email = "your-email@example.com" # Replace with the email used in your commits [[clients]] id = "gitlab-work" name = "Work Self-Hosted GitLab" gitlab_host = "gitlab.company.com" # Replace with your company's GitLab host gitlab_token = "YOUR_WORK_ACCESS_TOKEN" author_email = "your-work-email@company.com" # Add more [[clients]] blocks if needed
-
Details:
enabled
: Set totrue
to enable the plugin within MOT (requires restart).id
: A unique string to identify this configuration block (e.g., "gitlab-com", "work-gitlab").name
: A user-friendly name displayed in MOT (optional).gitlab_host
: The hostname of your GitLab instance (e.g.,gitlab.com
orgitlab.yourcompany.com
).gitlab_token
: Your GitLab Personal Access Token withread_api
scope.author_email
: The email address associated with your Git commits on this instance. The plugin will only fetch commits matching this email.
-
Save the changes to the file.
📖 Usage
Once installed, configured, and enabled:
- Restart MOT.
- Navigate to the Plugins view (press
p
in the main view). - Ensure the "GitLab Activity Plugin" is listed and enabled (use
Space
to toggle if needed, then restart MOT). - Return to the main time entry view (
Esc
orp
). - Your GitLab commit activity (matching the configured email(s)) should appear alongside your regular MoneyBird time entries, tagged with the source plugin.
- (Optional) If MOT supports importing plugin entries (check MOT features/roadmap), you might be able to select GitLab entries and import them (
i
key in standard MOT).
Refer to the main MOT documentation for general navigation and interaction within the application.
🗑️ Uninstallation
To remove the plugin:
- Delete the plugin's directory:
# Linux / macOS rm -rf ~/.config/mot/plugins/mot-plugin-gitlab # Windows (adjust path as needed) # rmdir /s /q %APPDATA%\mot\plugins\mot-plugin-gitlab
- Restart MOT.
📜 License
This project is likely licensed under the MIT License - check the LICENSE file in the repository for confirmation.
🤝 Contributing
Contributions are welcome! Please refer to the main MOT contribution guidelines if applicable, or open an issue/pull request on this plugin's repository.
🙏 Acknowledgements
- The developers of MOT.
- GitLab Inc. for providing the API.
- The developers of apisnip. Used to trim the Gitlab api down to manageable size for progenitor.
- The developers of progenitor. Used to generate the API code from the openapi specification.
Dependencies
~11–28MB
~345K SLoC