===========
idem-gitlab
===========
.. image:: https://img.shields.io/badge/made%20with-pop-teal
:alt: Made with pop, a Python implementation of Plugin Oriented Programming
:target: https://pop.readthedocs.io/
.. image:: https://img.shields.io/badge/made%20with-python-yellow
:alt: Made with Python
:target: https://www.python.org/
Gitlab provider for idem.
About
=====
Manage Gitlab with ``idem``.
What is POP?
------------
This project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based
implementation of *Plugin Oriented Programming (POP)*. POP seeks to bring
together concepts and wisdom from the history of computing in new ways to solve
modern computing problems.
For more information:
* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__
* `pop-awesome <https://gitlab.com/vmware/pop/pop-awesome>`__
* `pop-create <https://gitlab.com/vmware/pop/pop-create/>`__
Getting Started
===============
Prerequisites
-------------
* Python 3.9+
* git *(if installing from source, or contributing to the project)*
Installation
------------
.. note::
If wanting to contribute to the project, and setup your local development
environment, see the ``CONTRIBUTING.rst`` document in the source repository
for this project.
If wanting to use ``idem-gitlab``, you can do so by either
installing from PyPI or from source.
Install from PyPI
+++++++++++++++++
.. code-block:: bash
pip install idem-gitlab
Install from source
+++++++++++++++++++
.. code-block:: bash
# clone repo
git clone git@gitlab.com/vmware/idem/idem-gitlab.git
cd idem-gitlab
# Setup venv
python3 -m venv .venv
source .venv/bin/activate
pip install pip==21 -e .
Usage
=====
credentials
-----------
The preferred authentication method to idem-gitlab is with a personal access token.
To create a personal access token, see the `Gitlab documentation <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`__.
Create an acct_file with the following format:
.. code-block:: yaml
gitlab:
default:
token: <personal_access_token>
# Optional parameters
endpoint_url: https://gitlab.com
api_version: v4
sudo: <user>
owned: True
Encrypt the acct_file with:
.. code-block:: bash
idem encrypt /path/to/acct_file
The first time this command is run, it will output an ACCT_KEY that can be used to decrypt the file.
Put the ACCT_KEY and the ACCT_FILE in the environment variables and idem will find and use your gitlab profile automatically.
.. code-block:: bash
export ACCT_KEY="<acct_key>"
export ACCT_FILE=/path/to/acct_file
Once your credentials are in place, you can test them by running any of the following commands:
.. code-block:: bash
idem exec gitlab.version.get
idem exec gitlab.metadata.get
idem exec gitlab.avatar.get email="gitlab_user@example.com"
idem exec gitlab.namespace.get
idem exec gitlab.project.commit.get "<commit_sha/branch/tag/null>" project_id="<project_id>"
Supported Resources
-------------------
The following are REFs for resources that are currently supported by idem-gitlab.
- gitlab.group
- gitlab.group.member
- gitlab.group.variable
- gitlab.impersonation_token
- gitlab.personal_access_token
- gitlab.project
- gitlab.project.branch
- gitlab.project.member
- gitlab.project.protected_branch
- gitlab.project.protected_tag
- gitlab.project.tag
- gitlab.project.variable
- gitlab.runner
- gitlab.user
For each ref, there are functions for create, list, get, update, and delete operations.
Idem-gitlab uses the "auto_state" contract to combine these CRUD operations into present and absent states.
Examples
--------
Run CRUD operations using the idem exec commands:
.. code-block:: bash
idem exec gitlab.project.create path=new_project
idem exec gitlab.project.list
idem exec gitlab.project.get "<new_project_id>"
idem exec gitlab.project.update "<new_project_id>" repository_access_level=private
idem exec gitlab.project.delete "<new_project_id>"
Create an SLS files based on existing resource:
.. code-block:: bash
idem describe gitlab.group > /srv/idem/gitlab/group.sls
idem describe gitlab.group.member > /srv/idem/gitlab/group_member.sls
idem describe gitlab.group.variable > /srv/idem/gitlab/group_variable.sls
idem describe gitlab.project > /srv/idem/gitlab/project.sls
idem describe gitlab.project.branch > /srv/idem/gitlab/branch.sls
idem describe gitlab.project.member > /srv/idem/gitlab/project_member.sls
idem describe gitlab.project.protected_branch > /srv/idem/gitlab/protected_branch.sls
idem describe gitlab.project.protected_tag > /srv/idem/gitlab/protected_tag.sls
idem describe gitlab.project.tag > /srv/idem/gitlab/tag.sls
idem describe gitlab.project.variable > /srv/idem/gitlab/project_variable.sls
idem describe gitlab.runner > /srv/idem/gitlab/runner.sls
idem describe gitlab.user > /srv/idem/gitlab/user.sls
Create a top-level SLS file that sources all the others:
.. code-block:: yaml
# /srv/idem/gitlab/init.sls
include:
- group
- group_member
- group_variable
- project_member
- project
- branch
- protected_branch
- protected_tag
- tag
- project_variable
- runner
- user
Run "idem state" to idempotently enforce changes to the any of the files created:
.. code-block:: bash
idem state /srv/idem/gitlab
And that's it! You are now using idem-gitlab to manage your gitlab resources.
Testing
=======
To run the tests using a gitlab docker image, first run:
.. code-block:: bash
docker run -d -p 80:80 --env GITLAB_ROOT_PASSWORD=not_secure gitlab/gitlab-ce
For testing you can use the sample credentials file for tests:
.. code-block:: bash
export ACCT_FILE=$PWD/example/credentials.yaml
Run the test suite with nox:
.. code-block:: bash
pip3 install nox
nox -p 3.11
Autogeneration
==============
Autogeneration utilizes ``pop-create`` to parse the gitlab api and generate modules for new resources.
To perform the autogeneration, first you need to install idem-gitlab with the ``autogen`` extras:
.. code-block:: bash
pip3 install idem-gitlab[autogen]
Next, run pop-create to generate the modules in the current directory:
.. code-block:: bash
pop-create gitlab --directory $PWD --create-plugin auto_state
pop-create gitlab --directory $PWD --create-plugin tests
These modules won't work out-of-the-box, they will likely need manual changes
to conform them to the rest of idem-gitlab and make them functional.
Once you have fully implemented a new resource, submit a PR and we will review it and hopefully
add it to idem-gitlab's functionality!
Roadmap
=======
Reference the `open issues <https://gitlab.com/vmware/idem/idem-gitlab/issues>`__ for a list of
proposed features (and known issues).
Acknowledgements
================
* `Img Shields <https://shields.io>`__ for making repository badges easy.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/vmware/idem/idem-gitlab",
"name": "idem-gitlab",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "VMware, Inc.",
"author_email": "idemproject@vmware.com",
"download_url": "https://files.pythonhosted.org/packages/83/6a/19c46dc9dede25db92abd6a5aeb574a725e4373ed3bd54e4014af4420d11/idem-gitlab-2.0.1.tar.gz",
"platform": null,
"description": "===========\nidem-gitlab\n===========\n\n.. image:: https://img.shields.io/badge/made%20with-pop-teal\n :alt: Made with pop, a Python implementation of Plugin Oriented Programming\n :target: https://pop.readthedocs.io/\n\n.. image:: https://img.shields.io/badge/made%20with-python-yellow\n :alt: Made with Python\n :target: https://www.python.org/\n\nGitlab provider for idem.\n\nAbout\n=====\n\nManage Gitlab with ``idem``.\n\nWhat is POP?\n------------\n\nThis project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based\nimplementation of *Plugin Oriented Programming (POP)*. POP seeks to bring\ntogether concepts and wisdom from the history of computing in new ways to solve\nmodern computing problems.\n\nFor more information:\n\n* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__\n* `pop-awesome <https://gitlab.com/vmware/pop/pop-awesome>`__\n* `pop-create <https://gitlab.com/vmware/pop/pop-create/>`__\n\nGetting Started\n===============\n\nPrerequisites\n-------------\n\n* Python 3.9+\n* git *(if installing from source, or contributing to the project)*\n\nInstallation\n------------\n\n.. note::\n\n If wanting to contribute to the project, and setup your local development\n environment, see the ``CONTRIBUTING.rst`` document in the source repository\n for this project.\n\nIf wanting to use ``idem-gitlab``, you can do so by either\ninstalling from PyPI or from source.\n\nInstall from PyPI\n+++++++++++++++++\n\n.. code-block:: bash\n\n pip install idem-gitlab\n\nInstall from source\n+++++++++++++++++++\n\n.. code-block:: bash\n\n # clone repo\n git clone git@gitlab.com/vmware/idem/idem-gitlab.git\n cd idem-gitlab\n\n # Setup venv\n python3 -m venv .venv\n source .venv/bin/activate\n pip install pip==21 -e .\n\n\nUsage\n=====\n\ncredentials\n-----------\n\nThe preferred authentication method to idem-gitlab is with a personal access token.\nTo create a personal access token, see the `Gitlab documentation <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`__.\nCreate an acct_file with the following format:\n\n.. code-block:: yaml\n\n gitlab:\n default:\n token: <personal_access_token>\n # Optional parameters\n endpoint_url: https://gitlab.com\n api_version: v4\n sudo: <user>\n owned: True\n\nEncrypt the acct_file with:\n\n.. code-block:: bash\n\n idem encrypt /path/to/acct_file\n\nThe first time this command is run, it will output an ACCT_KEY that can be used to decrypt the file.\nPut the ACCT_KEY and the ACCT_FILE in the environment variables and idem will find and use your gitlab profile automatically.\n\n.. code-block:: bash\n\n export ACCT_KEY=\"<acct_key>\"\n export ACCT_FILE=/path/to/acct_file\n\nOnce your credentials are in place, you can test them by running any of the following commands:\n\n.. code-block:: bash\n\n idem exec gitlab.version.get\n idem exec gitlab.metadata.get\n idem exec gitlab.avatar.get email=\"gitlab_user@example.com\"\n idem exec gitlab.namespace.get\n idem exec gitlab.project.commit.get \"<commit_sha/branch/tag/null>\" project_id=\"<project_id>\"\n\nSupported Resources\n-------------------\n\nThe following are REFs for resources that are currently supported by idem-gitlab.\n\n- gitlab.group\n- gitlab.group.member\n- gitlab.group.variable\n- gitlab.impersonation_token\n- gitlab.personal_access_token\n- gitlab.project\n- gitlab.project.branch\n- gitlab.project.member\n- gitlab.project.protected_branch\n- gitlab.project.protected_tag\n- gitlab.project.tag\n- gitlab.project.variable\n- gitlab.runner\n- gitlab.user\n\n\nFor each ref, there are functions for create, list, get, update, and delete operations.\n\nIdem-gitlab uses the \"auto_state\" contract to combine these CRUD operations into present and absent states.\n\nExamples\n--------\n\nRun CRUD operations using the idem exec commands:\n\n.. code-block:: bash\n\n idem exec gitlab.project.create path=new_project\n idem exec gitlab.project.list\n idem exec gitlab.project.get \"<new_project_id>\"\n idem exec gitlab.project.update \"<new_project_id>\" repository_access_level=private\n idem exec gitlab.project.delete \"<new_project_id>\"\n\nCreate an SLS files based on existing resource:\n\n.. code-block:: bash\n\n idem describe gitlab.group > /srv/idem/gitlab/group.sls\n idem describe gitlab.group.member > /srv/idem/gitlab/group_member.sls\n idem describe gitlab.group.variable > /srv/idem/gitlab/group_variable.sls\n idem describe gitlab.project > /srv/idem/gitlab/project.sls\n idem describe gitlab.project.branch > /srv/idem/gitlab/branch.sls\n idem describe gitlab.project.member > /srv/idem/gitlab/project_member.sls\n idem describe gitlab.project.protected_branch > /srv/idem/gitlab/protected_branch.sls\n idem describe gitlab.project.protected_tag > /srv/idem/gitlab/protected_tag.sls\n idem describe gitlab.project.tag > /srv/idem/gitlab/tag.sls\n idem describe gitlab.project.variable > /srv/idem/gitlab/project_variable.sls\n idem describe gitlab.runner > /srv/idem/gitlab/runner.sls\n idem describe gitlab.user > /srv/idem/gitlab/user.sls\n\nCreate a top-level SLS file that sources all the others:\n\n.. code-block:: yaml\n\n # /srv/idem/gitlab/init.sls\n include:\n - group\n - group_member\n - group_variable\n - project_member\n - project\n - branch\n - protected_branch\n - protected_tag\n - tag\n - project_variable\n - runner\n - user\n\nRun \"idem state\" to idempotently enforce changes to the any of the files created:\n\n.. code-block:: bash\n\n idem state /srv/idem/gitlab\n\nAnd that's it! You are now using idem-gitlab to manage your gitlab resources.\n\nTesting\n=======\n\nTo run the tests using a gitlab docker image, first run:\n\n.. code-block:: bash\n\n docker run -d -p 80:80 --env GITLAB_ROOT_PASSWORD=not_secure gitlab/gitlab-ce\n\nFor testing you can use the sample credentials file for tests:\n\n.. code-block:: bash\n\n export ACCT_FILE=$PWD/example/credentials.yaml\n\nRun the test suite with nox:\n\n.. code-block:: bash\n\n pip3 install nox\n nox -p 3.11\n\nAutogeneration\n==============\n\nAutogeneration utilizes ``pop-create`` to parse the gitlab api and generate modules for new resources.\nTo perform the autogeneration, first you need to install idem-gitlab with the ``autogen`` extras:\n\n.. code-block:: bash\n\n pip3 install idem-gitlab[autogen]\n\nNext, run pop-create to generate the modules in the current directory:\n\n.. code-block:: bash\n\n pop-create gitlab --directory $PWD --create-plugin auto_state\n pop-create gitlab --directory $PWD --create-plugin tests\n\nThese modules won't work out-of-the-box, they will likely need manual changes\nto conform them to the rest of idem-gitlab and make them functional.\nOnce you have fully implemented a new resource, submit a PR and we will review it and hopefully\nadd it to idem-gitlab's functionality!\n\nRoadmap\n=======\n\nReference the `open issues <https://gitlab.com/vmware/idem/idem-gitlab/issues>`__ for a list of\nproposed features (and known issues).\n\nAcknowledgements\n================\n\n* `Img Shields <https://shields.io>`__ for making repository badges easy.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Gitlab Provider plugins for Idem",
"version": "2.0.1",
"project_urls": {
"Code": "https://gitlab.com/vmware/idem/idem-gitlab",
"Homepage": "https://gitlab.com/vmware/idem/idem-gitlab",
"Issue tracker": "https://gitlab.com/vmware/idem/idem-gitlab/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "pypi",
"digests": {
"blake2b_256": "826a9da32a62ffc04bf436e2983c7cda358fc1e0d9f248657609ea33d8b997a2",
"md5": "02e5c061d6b7b1f4b4598805e39b97b5",
"sha256": "0a0e2a0be37736353c9328bb942e7bd3fd1a9c612d02cb05defc7ecdf23883c9"
},
"downloads": -1,
"filename": "idem_gitlab-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02e5c061d6b7b1f4b4598805e39b97b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 67264,
"upload_time": "2024-01-10T23:19:58",
"upload_time_iso_8601": "2024-01-10T23:19:58.601153Z",
"url": "https://files.pythonhosted.org/packages/82/6a/9da32a62ffc04bf436e2983c7cda358fc1e0d9f248657609ea33d8b997a2/idem_gitlab-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "pypi",
"digests": {
"blake2b_256": "836a19c46dc9dede25db92abd6a5aeb574a725e4373ed3bd54e4014af4420d11",
"md5": "c131eb175f060d47d055a9078ee6461a",
"sha256": "5ca215c2c78025d2ebc4fefd1aa522c27d2bf06b9bf58cf962d305bd2d48620d"
},
"downloads": -1,
"filename": "idem-gitlab-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "c131eb175f060d47d055a9078ee6461a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 39969,
"upload_time": "2024-01-10T23:20:00",
"upload_time_iso_8601": "2024-01-10T23:20:00.510238Z",
"url": "https://files.pythonhosted.org/packages/83/6a/19c46dc9dede25db92abd6a5aeb574a725e4373ed3bd54e4014af4420d11/idem-gitlab-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-10 23:20:00",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "vmware",
"gitlab_project": "idem",
"lcname": "idem-gitlab"
}
JSON