API des artefacts de job

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Utilisez cette API pour télécharger, conserver et supprimer les artefacts de job.

Télécharger les artefacts de job par ID de job {#download-job-artifacts-by-job-id}

Téléchargez l'archive des artefacts d'un job en utilisant un ID de job.

Si vous utilisez cURL pour télécharger des artefacts depuis GitLab.com, utilisez le paramètre --location car la requête peut être redirigée via un CDN.

GET /projects/:id/jobs/:job_id/artifacts

Attributs pris en charge :

En cas de succès, retourne 200 et sert le fichier d'artefacts.

Exemple de requête :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts" \
  --output artifacts.zip

Exemple de requête utilisant un jeton de job CI/CD :

# Uses the job_token parameter
artifact_download:
  stage: test
  script:
    - 'curl --request GET \
         --location \
         --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN" \
         --output artifacts.zip'

Télécharger les artefacts de job par nom de référence {#download-job-artifacts-by-reference-name}

{{< history >}}

• L'attribut search_recent_successful_pipelines a été introduit dans GitLab 18.7 avec un flag nommé ci_search_recent_successful_pipelines. Désactivé par défaut.
• Le feature flag ci_search_recent_successful_pipelines a été supprimé dans GitLab 18.10

{{< /history >}}

Téléchargez l'archive des artefacts d'un job depuis le dernier pipeline réussi en utilisant un nom de référence. Lorsque search_recent_successful_pipelines=true, la recherche inclut jusqu'à 100 pipelines réussis récents pour la référence spécifiée.

Le dernier pipeline réussi est déterminé en fonction de l'heure de création. L'heure de début ou de fin des jobs individuels n'a pas d'incidence sur le pipeline le plus récent.

Pour les pipelines parent et enfant, les artefacts sont recherchés dans un ordre hiérarchique du parent vers l'enfant. Si les pipelines parent et enfant ont tous les deux un job portant le même nom, l'artefact du pipeline parent est retourné.

Prérequis :

• Vous devez disposer d'un pipeline terminé avec un statut success.
• Si le pipeline inclut des jobs manuels, ceux-ci doivent soit :
  • Se terminer avec succès.
  • Avoir allow_failure: true défini.

Si vous utilisez cURL pour télécharger des artefacts depuis GitLab.com, utilisez le paramètre --location car la requête peut être redirigée via un CDN.

GET /projects/:id/jobs/artifacts/:ref_name/download?job=name

Attributs pris en charge :

En cas de succès, retourne 200 et sert le fichier d'artefacts.

Si le job ou les artefacts sont introuvables, retourne 404.

Exemple de requête :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test"

Exemple de requête utilisant un jeton de job CI/CD :

# Uses the job_token parameter
artifact_download:
  stage: test
  script:
    - 'curl --request GET \
         --location \
         --url "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" \
         --output artifacts.zip'

Exemple de requête avec recherche dans les pipelines récents :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&search_recent_successful_pipelines=true"

Télécharger un seul fichier d'artefact par ID de job {#download-a-single-artifact-file-by-job-id}

Téléchargez un seul fichier depuis les artefacts d'un job en utilisant un ID de job. Le fichier est extrait de l'archive et transmis en flux au client.

Si vous utilisez cURL pour télécharger des artefacts depuis GitLab.com, utilisez le paramètre --location car la requête peut être redirigée via un CDN.

GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

Attributs pris en charge :

En cas de succès, retourne 200 et envoie un seul fichier d'artefact.

Exemple de requête :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"

Lister tous les fichiers dans l'archive d'artefacts {#list-all-files-in-the-artifacts-archive}

{{< history >}}

• Introduit dans GitLab 18.8.

{{< /history >}}

Listez tous les fichiers et répertoires dans l'archive d'artefacts d'un job spécifié. Cette opération lit les métadonnées de l'artefact sans extraire l'archive complète, ce qui la rend efficace pour parcourir de grandes archives.

GET /projects/:id/jobs/:job_id/artifacts/tree

Attributs pris en charge :

Ce point de terminaison prend en charge la pagination.

En cas de succès, renvoie 200 et les attributs de réponse suivants :

Si le job, les artefacts, les métadonnées d'artefact ou le chemin spécifié sont introuvables, retourne 404.

Exemple de requête :

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree"

Exemple de réponse :

[
  {
    "name": "ci_build_artifacts.zip",
    "path": "ci_build_artifacts.zip",
    "type": "file",
    "size": 1024,
    "mode": "100644"
  },
  {
    "name": "other_artifacts_0.1.2",
    "path": "other_artifacts_0.1.2/",
    "type": "directory",
    "mode": "040755"
  }
]

Exemple de requête pour parcourir un sous-répertoire :

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree?path=coverage/reports"

Exemple de requête pour un listage récursif :

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree?recursive=true"

Exemple de requête utilisant un jeton de job CI/CD :

# Uses the job_token parameter
list_artifacts:
  stage: test
  script:
    - 'curl --request GET \
         --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree?job_token=$CI_JOB_TOKEN"'

Télécharger un seul fichier d'artefact par nom de référence {#download-a-single-artifact-file-by-reference-name}

{{< history >}}

• L'attribut search_recent_successful_pipelines a été introduit dans GitLab 18.9 avec un flag nommé ci_search_recent_successful_pipelines. Désactivé par défaut.
• Le feature flag ci_search_recent_successful_pipelines a été supprimé dans GitLab 18.10

{{< /history >}}

Téléchargez un seul fichier depuis les artefacts d'un job dans le dernier pipeline réussi en utilisant le nom de référence. Le fichier est extrait de l'archive et transmis en flux au client avec le type de contenu plain/text. Lorsque search_recent_successful_pipelines=true, la recherche inclut jusqu'à 100 pipelines réussis récents pour la référence spécifiée.

Pour les pipelines parent et enfant, les artefacts sont recherchés dans un ordre hiérarchique du parent vers l'enfant. Si les pipelines parent et enfant ont tous les deux un job portant le même nom, l'artefact du pipeline parent est retourné.

Le fichier d'artefact fournit plus de détails que ce qui est disponible dans l'export CSV.

Prérequis :

• Vous devez disposer d'un pipeline terminé avec un statut success.
• Si le pipeline inclut des jobs manuels, ceux-ci doivent soit :
  • Se terminer avec succès.
  • Avoir allow_failure: true défini.
• Pour effectuer une recherche dans les pipelines réussis récents, le feature flag ci_search_recent_successful_pipelines doit être activé pour le projet.

Si vous utilisez cURL pour télécharger des artefacts depuis GitLab.com, utilisez le paramètre --location car la requête peut être redirigée via un CDN.

GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name

Attributs pris en charge :

En cas de succès, retourne 200 et envoie un seul fichier d'artefact.

Si le job ou le fichier d'artefact sont introuvables, retourne 404.

Exemple de requête :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf"

Exemple de requête avec recherche dans les pipelines récents :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf&search_recent_successful_pipelines=true"

Conserver les artefacts de job {#keep-job-artifacts}

Empêchez la suppression automatique des artefacts d'un job lorsqu'ils atteignent leur date d'expiration.

POST /projects/:id/jobs/:job_id/artifacts/keep

Attributs pris en charge :

En cas de succès, retourne 200 et les détails du job.

Exemple de requête :

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep"

Exemple de réponse :

{
  "commit": {
    "author_email": "[email protected]",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "allow_failure": false,
  "download_url": null,
  "id": 42,
  "name": "rubocop",
  "ref": "main",
  "artifacts": [],
  "runner": null,
  "stage": "test",
  "created_at": "2016-01-11T10:13:33.506Z",
  "started_at": "2016-01-11T10:13:33.506Z",
  "finished_at": "2016-01-11T10:15:10.506Z",
  "duration": 97.0,
  "status": "failed",
  "failure_reason": "script_failure",
  "tag": false,
  "web_url": "https://example.com/foo/bar/-/jobs/42",
  "user": null
}

Supprimer les artefacts de job {#delete-job-artifacts}

Supprimez tous les artefacts associés à un job spécifique. Les artefacts ne peuvent pas être récupérés après leur suppression.

Prérequis :

• Vous devez avoir le rôle Maintainer ou Owner pour le projet.

DELETE /projects/:id/jobs/:job_id/artifacts

Attributs pris en charge :

En cas de succès, retourne 204 No Content.

Exemple de requête :

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts"

Supprimer tous les artefacts de job dans un projet {#delete-all-job-artifacts-in-a-project}

Supprimez tous les artefacts de job éligibles à la suppression dans un projet. Les artefacts ne peuvent pas être récupérés après leur suppression.

Par défaut, les artefacts du pipeline réussi le plus récent de chaque ref ne sont pas supprimés.

Les requêtes adressées à ce point de terminaison définissent l'expiration de tous les artefacts de job pouvant être supprimés à l'heure actuelle. Les fichiers sont ensuite supprimés du système dans le cadre du nettoyage régulier des artefacts de job expirés. Les job logs ne sont jamais supprimés.

Le nettoyage régulier s'effectue de manière asynchrone selon un calendrier, il peut donc y avoir un court délai avant la suppression des artefacts.

Prérequis :

• Vous devez avoir le rôle Maintainer ou Owner pour le projet.

DELETE /projects/:id/artifacts

Attributs pris en charge :

En cas de succès, retourne 202 Accepted.

Exemple de requête :

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/artifacts"

Dépannage {#troubleshooting}

Utilisation des noms de branche avec les pipelines de merge request {#using-branch-names-with-merge-request-pipelines}

Vous pouvez obtenir une erreur 404 Not Found lorsque vous tentez de télécharger des artefacts de job en utilisant un nom de branche comme ref_name.

Ce problème se produit car les pipelines de merge request utilisent un format de référence différent de celui des pipelines de branche. Les pipelines de merge request s'exécutent sur refs/merge-requests/:iid/head, pas directement sur la branche source.

Pour télécharger les artefacts de job d'un pipeline de merge request, utilisez refs/merge-requests/:iid/head comme ref_name à la place du nom de branche, où :iid est l'ID du merge request. Dans les pipelines de merge request, l'ID est disponible depuis la variable $CI_MERGE_REQUEST_IID et le ref_name complet depuis la variable $CI_MERGE_REQUEST_REF_PATH.

Par exemple, pour le merge request !123 :

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/refs/merge-requests/123/head/raw/file.txt?job=test"

Téléchargement de fichiers artifacts:reports {#downloading-artifactsreports-files}

Vous pouvez obtenir une erreur 404 Not Found lorsque vous tentez de télécharger des rapports via l'API des artefacts de job.

Ce problème se produit car les rapports ne sont pas téléchargeables par défaut.

Pour rendre les rapports téléchargeables, ajoutez leurs noms de fichiers ou gl-*-report.json à artifacts:paths.