Introduction

GitLab project import via the API requires a personal access token with the api scope and appropriate project or group permissions. When the token lacks the required scope, or the user does not have Maintainer or Owner access to the target namespace, the import API returns a 403 Forbidden error, blocking automated project migration and backup restoration workflows.

Symptoms

  • Project import API call returns 403 Forbidden
  • Error message indicates insufficient permissions or missing scope
  • Token works for reading projects but fails for import operations
  • Import works via the web UI but fails via API with the same user
  • Error message: {"error":"403 Forbidden - You need admin rights to import a project"}

Common Causes

  • Personal access token created without the api scope
  • Token has read_api scope but not full api scope
  • User lacks Maintainer role in the target group or namespace
  • GitLab instance has import restrictions enabled (admin-only imports)
  • Token expired or was revoked after creation

Step-by-Step Fix

jq '.[]

Prevention

  • Document the required token scopes for each API operation in a central reference
  • Use group-level access tokens for automated project management operations
  • Verify token permissions before running import/export automation
  • Implement token validation as a pre-flight check in automation scripts
  • Rotate tokens regularly and test all dependent operations after rotation
  • Use OAuth application tokens with specific scopes instead of personal access tokens for automation