feat: add support for job token

See https://docs.gitlab.com/ee/api/jobs.html#get-job-artifacts for usage

7 files changed, 58 insertions, 11 deletions

diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
index bda8141..5835acd 100755
--- a/docker-entrypoint.sh
+++ b/docker-entrypoint.sh
@@ -14,6 +14,7 @@ per_page = ${GITLAB_PER_PAGE:-10}
 url = ${GITLAB_URL:-https://gitlab.com}
 private_token = ${GITLAB_PRIVATE_TOKEN}
 oauth_token = ${GITLAB_OAUTH_TOKEN}
+job_token = ${GITLAB_JOB_TOKEN}
 http_username = ${GITLAB_HTTP_USERNAME}
 http_password = ${GITLAB_HTTP_PASSWORD}
 EOF
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 2f75584..19b9593 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -19,6 +19,10 @@ To connect to a GitLab server, create a ``gitlab.Gitlab`` object:
    # oauth token authentication
    gl = gitlab.Gitlab('http://10.0.0.1', oauth_token='my_long_token_here')
 
+   # job token authentication (to be used in CI)
+   import os
+   gl = gitlab.Gitlab('http://10.0.0.1', job_token=os.environ['CI_JOB_TOKEN'])
+
    # username/password authentication (for GitLab << 10.2)
    gl = gitlab.Gitlab('http://10.0.0.1', email='jdoe', password='s3cr3t')
 
diff --git a/docs/cli.rst b/docs/cli.rst
index 2051d03..defbf02 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -83,9 +83,9 @@ You must define the ``url`` in each GitLab server section.
    If the GitLab server you are using redirects requests from http to https,
    make sure to use the ``https://`` protocol in the ``url`` definition.
 
-Only one of ``private_token`` or ``oauth_token`` should be defined. If neither
-are defined an anonymous request will be sent to the Gitlab server, with very
-limited permissions.
+Only one of ``private_token``, ``oauth_token`` or ``job_token`` should be
+defined. If neither are defined an anonymous request will be sent to the Gitlab
+server, with very limited permissions.
 
 .. list-table:: GitLab server options
    :header-rows: 1
@@ -96,10 +96,12 @@ limited permissions.
      - URL for the GitLab server
    * - ``private_token``
      - Your user token. Login/password is not supported. Refer to `the official
-       documentation`__ to learn how to obtain a token.
+       documentation`_pat to learn how to obtain a token.
    * - ``oauth_token``
      - An Oauth token for authentication. The Gitlab server must be configured
        to support this authentication method.
+   * - ``job_token``
+     - Your job token. See `the official  documentation`_job-token to learn how to obtain a token.
    * - ``api_version``
      - GitLab API version to use (``3`` or ``4``). Defaults to ``4`` since
        version 1.3.0.
@@ -108,7 +110,8 @@ limited permissions.
    * - ``http_password``
      - Password for optional HTTP authentication
 
-__ https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html
+.. _pat: https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html
+.. _job-token: https://docs.gitlab.com/ce/api/jobs.html#get-job-artifacts
 
 CLI
 ===
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
index 11734d7..163c599 100644
--- a/gitlab/__init__.py
+++ b/gitlab/__init__.py
@@ -60,6 +60,7 @@ class Gitlab(object):
         url (str): The URL of the GitLab server.
         private_token (str): The user private token
         oauth_token (str): An oauth token
+        job_token (str): A CI job token
         email (str): The user email or login.
         password (str): The user password (associated with email).
         ssl_verify (bool|str): Whether SSL certificates should be validated. If
@@ -76,6 +77,7 @@ class Gitlab(object):
         url,
         private_token=None,
         oauth_token=None,
+        job_token=None,
         email=None,
         password=None,
         ssl_verify=True,
@@ -107,6 +109,7 @@ class Gitlab(object):
         self.http_username = http_username
         self.http_password = http_password
         self.oauth_token = oauth_token
+        self.job_token = job_token
         self._set_auth_info()
 
         #: Create a session object for requests
@@ -195,6 +198,7 @@ class Gitlab(object):
             config.url,
             private_token=config.private_token,
             oauth_token=config.oauth_token,
+            job_token=config.job_token,
             ssl_verify=config.ssl_verify,
             timeout=config.timeout,
             http_username=config.http_username,
@@ -211,7 +215,7 @@ class Gitlab(object):
         The `user` attribute will hold a `gitlab.objects.CurrentUser` object on
         success.
         """
-        if self.private_token or self.oauth_token:
+        if self.private_token or self.oauth_token or self.job_token:
             self._token_auth()
         else:
             self._credentials_auth()
@@ -346,9 +350,16 @@ class Gitlab(object):
             return url
 
     def _set_auth_info(self):
-        if self.private_token and self.oauth_token:
+        if (
+            sum(
+                bool(arg)
+                for arg in [self.private_token, self.oauth_token, self.job_token]
+            )
+            != 1
+        ):
             raise ValueError(
-                "Only one of private_token or oauth_token should " "be defined"
+                "Only one of private_token, oauth_token or job_token should "
+                "be defined"
             )
         if (self.http_username and not self.http_password) or (
             not self.http_username and self.http_password
@@ -364,12 +375,19 @@ class Gitlab(object):
 
         self._http_auth = None
         if self.private_token:
-            self.headers["PRIVATE-TOKEN"] = self.private_token
             self.headers.pop("Authorization", None)
+            self.headers["PRIVATE-TOKEN"] = self.private_token
+            self.headers.pop("JOB-TOKEN", None)
 
         if self.oauth_token:
             self.headers["Authorization"] = "Bearer %s" % self.oauth_token
             self.headers.pop("PRIVATE-TOKEN", None)
+            self.headers.pop("JOB-TOKEN", None)
+
+        if self.job_token:
+            self.headers.pop("Authorization", None)
+            self.headers.pop("PRIVATE-TOKEN", None)
+            self.headers["JOB-TOKEN"] = self.job_token
 
         if self.http_username:
             self._http_auth = requests.auth.HTTPBasicAuth(
diff --git a/gitlab/cli.py b/gitlab/cli.py
index 01d8851..0ff2f22 100644
--- a/gitlab/cli.py
+++ b/gitlab/cli.py
@@ -202,7 +202,7 @@ def main():
 
     try:
         gl = gitlab.Gitlab.from_config(gitlab_id, config_files)
-        if gl.private_token or gl.oauth_token:
+        if gl.private_token or gl.oauth_token or gl.job_token:
             gl.auth()
     except Exception as e:
         die(str(e))
diff --git a/gitlab/config.py b/gitlab/config.py
index 0c3cff7..67301a0 100644
--- a/gitlab/config.py
+++ b/gitlab/config.py
@@ -122,6 +122,12 @@ class GitlabConfigParser(object):
         except Exception:
             pass
 
+        self.job_token = None
+        try:
+            self.job_token = self._config.get(self.gitlab_id, "job_token")
+        except Exception:
+            pass
+
         self.http_username = None
         self.http_password = None
         try:
diff --git a/gitlab/tests/test_gitlab.py b/gitlab/tests/test_gitlab.py
index ee1daa3..35cfeda 100644
--- a/gitlab/tests/test_gitlab.py
+++ b/gitlab/tests/test_gitlab.py
@@ -403,17 +403,31 @@ class TestGitlabAuth(unittest.TestCase):
         gl = Gitlab("http://localhost", private_token="private_token", api_version="4")
         self.assertEqual(gl.private_token, "private_token")
         self.assertEqual(gl.oauth_token, None)
+        self.assertEqual(gl.job_token, None)
         self.assertEqual(gl._http_auth, None)
-        self.assertEqual(gl.headers["PRIVATE-TOKEN"], "private_token")
         self.assertNotIn("Authorization", gl.headers)
+        self.assertEqual(gl.headers["PRIVATE-TOKEN"], "private_token")
+        self.assertNotIn("JOB-TOKEN", gl.headers)
 
     def test_oauth_token_auth(self):
         gl = Gitlab("http://localhost", oauth_token="oauth_token", api_version="4")
         self.assertEqual(gl.private_token, None)
         self.assertEqual(gl.oauth_token, "oauth_token")
+        self.assertEqual(gl.job_token, None)
         self.assertEqual(gl._http_auth, None)
         self.assertEqual(gl.headers["Authorization"], "Bearer oauth_token")
         self.assertNotIn("PRIVATE-TOKEN", gl.headers)
+        self.assertNotIn("JOB-TOKEN", gl.headers)
+
+    def test_job_token_auth(self):
+        gl = Gitlab("http://localhost", job_token="CI_JOB_TOKEN", api_version="4")
+        self.assertEqual(gl.private_token, None)
+        self.assertEqual(gl.oauth_token, None)
+        self.assertEqual(gl.job_token, "CI_JOB_TOKEN")
+        self.assertEqual(gl._http_auth, None)
+        self.assertNotIn("Authorization", gl.headers)
+        self.assertNotIn("PRIVATE-TOKEN", gl.headers)
+        self.assertEqual(gl.headers["JOB-TOKEN"], "CI_JOB_TOKEN")
 
     def test_http_auth(self):
         gl = Gitlab(
@@ -425,6 +439,7 @@ class TestGitlabAuth(unittest.TestCase):
         )
         self.assertEqual(gl.private_token, "private_token")
         self.assertEqual(gl.oauth_token, None)
+        self.assertEqual(gl.job_token, None)
         self.assertIsInstance(gl._http_auth, requests.auth.HTTPBasicAuth)
         self.assertEqual(gl.headers["PRIVATE-TOKEN"], "private_token")
         self.assertNotIn("Authorization", gl.headers)