Gitlab Assistant 🚀🤖

Gitlab Assistant is your cheerful command-line sidekick for wrangling GitLab automation tasks with ease 💪. It currently ships with helper scripts for exporting and importing CI/CD variables, and it is built to grow 🪴 as more everyday chores get scripted away.

Why This Exists 🌟

• Keep CI/CD secrets backed up safely ✅
• Sync configuration between projects or environments 🔄
• Automate routine GitLab chores without clicking through the UI 🖱️➡️⌨️
• Provide a foundation for future GitLab helpers 🧱

Getting Started 🧭

Prerequisites

• Python 3.9 or newer 🐍
• Access to a GitLab instance with API permissions 🔐
• Optional: pip install -r requirements.txt (if you split dependencies later) 📦

Quick Setup

1. Clone the repository ☁️⬇️
2. Create a virtual environment (recommended) 🌀
3. Install dependencies such as requests and pyyaml 📚
4. Copy .env.example to .env (if present) and fill in credentials 🔑

python3 -m venv .venv
source .venv/bin/activate
pip install requests pyyaml

Tip: Add new helper libraries to a future requirements.txt so teammates can sync quickly 🌈

Credential Handling 🛡️

The scripts look for GitLab credentials in this order:

• Command-line arguments (--token, --username, --password) 🧾
• Environment variables (GITLAB_TOKEN, GITLAB_USERNAME, GITLAB_PASSWORD) 🌍
• Values loaded from a .env file 💼

You can mix and match—provide a token flag for one-off runs or keep reusable secrets in .env (never commit secrets! 🙅‍♂️).

Included Scripts 📜

1. gitlab-cicd-variables-export.py 📤

Exports CI/CD variables for a given project (and optionally its parent groups) into a tidy YAML snapshot.

Highlights

• Supports project URLs or @https://... shorthand ✂️
• Loads .env automatically to keep your shell clean 🧽
• Falls back to username/password authentication by trading them for a temporary token 💳
• Fetches group-level inherited variables when --include-groups is set 🧬
• Writes YAML using PyYAML if available, or a built-in fallback ✍️

Core Flow

1. Parse the project URL and break it into base URL + project path 🔍
2. Load credentials from CLI/env/.env 🔑
3. Create an authenticated requests.Session 🕸️
4. Paginate through /variables endpoints for project (and groups if requested) 📦
5. Assemble everything into a normalized JSON-like structure 🧱
6. Dump the result to output/<project>-cicd-variables.yaml (auto-creates the folder) 📂

Usage

./gitlab-cicd-variables-export.py @https://gitlab.example.com/team/awesome-service \
  --include-groups \
  --output awesome-service-prod.yaml

Outputs look like:

project: team/awesome-service
variables:
  - key: API_TOKEN
    value: "..."
    source: project
    masked: true
# ...

2. gitlab-cicd-variables-import.py 📥

Imports CI/CD variables from the YAML format produced by the export script, safely updating or creating entries.

Highlights

• Validates the target project matches the YAML metadata (warns if not) ⚠️
• Reuses the same authentication mechanisms as the exporter 🔄
• Upserts each variable with smart retry logic (create → update fallback) 🧠
• Handles group variables unless --skip-groups is set 🚫
• Offers --dry-run to preview actions without touching GitLab 🔍

Core Flow

1. Parse CLI arguments and resolve credentials 🛠️
2. Load the YAML document via PyYAML 📖
3. Iterate over project entries, validating schema 🔐
4. Upsert each variable into /projects/.../variables 🧱
5. Repeat for group_variables unless dry-run/skip is requested 🔁
6. Summarize created/updated/failed counts 📊

Usage

./gitlab-cicd-variables-import.py @https://gitlab.example.com/team/awesome-service \
  output/awesome-service-prod.yaml \
  --dry-run

When ready for the real run, drop --dry-run to apply changes for real ✅

Script Conventions 🧩

• Always prefer absolute paths when scripting to avoid surprises 🚫🪄
• Store generated YAML in the output/ directory 🎯
• Keep type hints and docstrings—new scripts should follow the same style 👩‍💻
• Wrap network calls with humble error handling and descriptive messages 🧯

Roadmap Ideas 🛣️

• 🔍 Discover pipeline schedules and manage them from the CLI
• 🧪 Trigger test pipelines with temporary variables for feature branches
• 🧰 Abstract common helpers into a shared module to reduce duplication
• 🧾 Generate Markdown reports of environment differences

Feel free to add your own ideas by extending this list—Gitlab Assistant loves new skills! 🤩

Contributing 🤝

• Fork or branch, then open a merge request 🪜
• Add docs and examples when introducing new scripts 📝
• Keep emoji energy high—it keeps the bots happy 😄

License 📄

Choose a license that suits the project and document it here once decided (MIT, Apache-2.0, etc.). Until then, treat it as proprietary/private. 🛡️

---

Happy automating! ⚙️✨