GitLabのアクセストークンは、パスワードの代わりにGit操作やREST APIの認証へ使う文字列で、個人・プロジェクト・グループの3種類の区分です。この記事では、3種類の到達範囲の違いを整理したうえで、個人アクセストークン（従来型とfine-grained）とプロジェクト・グループアクセストークンの発行手順、17種のスコープの選び方、git cloneやcurlでの渡し方を示します。後半では有効期限365日の運用とrotate APIでの更新、CI/CDで個人トークンを使わない判断までが対象です。画面名と仕様は2026年11月時点の公式ドキュメントにもとづいています。
まとめ：GitLabのアクセストークンは用途で種類を決めスコープと期限を絞る
最初に決めるのはスコープではなく種類です。人が手元でcloneやAPIを試すなら個人アクセストークン、特定のプロジェクトだけを触る自動化ならプロジェクトアクセストークン、複数プロジェクトをまたぐ自動化ならグループアクセストークンを選びます。CIのジョブ内で完結する処理は、発行不要のCI_JOB_TOKENで足りることが多いです。
スコープは読み取りだけならread_apiやread_repositoryにとどめ、apiは書き込みが要る場合に限ります。有効期限の既定は作成日から365日で、期限が来たら延長はできず、rotateで新しい値に入れ替えます。GitLab.comのFreeではプロジェクト・グループアクセストークンが使えないため、自動化用の主体にはサービスアカウントを使うのが2026年11月時点の現実的な選択です。
GitLabのアクセストークンとは：個人・プロジェクト・グループの到達範囲の違い
3種類のアクセストークンの到達範囲・作成ロール・GitLab.comのプラン条件
3種類の違いは、誰の権限で動き、どこまで届くかです。個人アクセストークンは本人の権限で、本人が参加する全グループ・全プロジェクトに届きます。プロジェクトとグループのトークンは自動で作られるボットユーザーの権限で動き、届く範囲も対象に限られます。
| 種類 | 届く範囲 | 作成に必要なロール | GitLab.comのプラン |
|---|---|---|---|
| 個人 | 本人が参加する全体 | 本人 | Free以上 |
| プロジェクト | 1プロジェクト | Maintainer・Owner | Premium以上 |
| グループ | グループと配下 | Owner | Premium以上 |
プラン条件はProject access tokensのドキュメントとGroup access tokensのドキュメントによります。Self-ManagedとDedicatedでは、どちらもライセンスの種類を問わず利用可能です。提供形態とプランの全体像は親記事のGitLabとは（構成要素・CEとEEの違い・3つの提供形態）で整理しています。
デプロイトークン・CIジョブトークン・サービスアカウントとの使い分け
GitLab token overviewには認証用の文字列が10種類以上並んでいます。アクセストークンの代わりに選ぶ機会が多いのは次の3つで、値の先頭の接頭辞で種類を見分けられます。
| 種類 | 接頭辞 | APIで使えるか | 向く用途 |
|---|---|---|---|
| 個人・プロジェクト・グループ | glpat- | 使える | APIとGit操作全般 |
| デプロイトークン | gldt- | 原則不可 | 本番サーバーのclone・pull |
| CIジョブトークン | glcbt- | 一部のみ | ジョブ内のAPI・clone |
| サービスアカウント | glpat- | 使える | 人に紐づかない自動化 |
Deploy tokensのドキュメントによると、デプロイトークンは既定で有効期限が無く、公開APIには使えません。名前をgitlab-deploy-tokenにして作ると、CIジョブにCI_DEPLOY_USERとCI_DEPLOY_PASSWORDが自動で渡されます。
個人アクセストークンを発行する手順：従来型とfine-grainedの画面操作
Legacy tokenを発行する画面の操作順と一度しか表示されない値の保管
従来型の個人アクセストークンは、2026年11月時点の画面ではLegacy tokenという名前で並んでいます。Personal access tokensのドキュメントの手順は次のとおりです。
- 右上のアバターからEdit profileを開く
- 左サイドバーでAccess > Personal access tokensを選ぶ
- Generate tokenのドロップダウンでLegacy tokenを選ぶ
- Token name（必須）とToken description（任意）を入れる
- Expiration dateを入れ、スコープを1つ以上選ぶ
- Generate tokenを押し、表示された値をすぐに保存する
値が表示されるのはこの1回だけです。保存先はパスワードマネージャーかシークレット管理の仕組みにし、チャットやIssueには貼りません。名前は公式の命名指針に沿って、testのような汎用名を避け、用途と環境が分かる形にします。SSH鍵の登録を含む初期設定の流れはGitLabの使い方（プロジェクト作成からIssue・MR・CI/CDまで）で追えます。
GitLab 19.2でGAのfine-grained PATのリソース別権限設定
スコープより細かく権限を絞りたいときはfine-grainedのトークンを使います。Fine-grained personal access tokensのドキュメントによると、GitLab 18.10でベータとして入り、19.2で一般提供になりました。Free・Premium・Ultimateのすべてで、GitLab.com・Self-Managed・Dedicatedのどれでも使えます。
発行はLegacy tokenと同じ画面で、Generate tokenのドロップダウンからFine-grained tokenを選びます。違うのは権限の指定方法で、Group and project accessで届く範囲を決め、Add resource permissionsのGroup and project・User・Globalの各タブでリソースごとに作成・読み取り・更新・削除のどれを許すかを選びます。リクエストが通るのは、トークンの権限と所有者本人の権限の両方を満たすときだけです。19.2の他の変更点はGitLab 19.2で変わる開発運用にまとめています。
Self-Managedで管理者がfine-grainedを強制すると、強制日以降はLegacy tokenの作成とローテーションができなくなるため、新規発行はfine-grainedに寄せておきます。
プロジェクト・グループアクセストークンの発行とボットユーザーの仕組み
Settings > Access tokensのロール・スコープ指定と作成API
プロジェクトアクセストークンは、対象プロジェクトの左サイドバーでSettings > Access tokensを開き、Add new tokenから名前・有効期限・ロール・スコープを指定して作ります。グループアクセストークンも、グループ側の同じ名前の画面で同じ項目を入れます。ロールはボットユーザーに与える権限で、読み取りだけの自動化ならReporter、MRの作成やpushまでするならDeveloperが目安です。
プロジェクトが多いときはProject access tokens APIで作るほうが漏れません。作成のリクエストは個人アクセストークンで認証する必要があり、プロジェクトアクセストークン自身では新しいトークンを作れません。
# GITLAB_TOKEN は api スコープの個人アクセストークン（Maintainer 以上の人が発行したもの）
GITLAB=https://gitlab.example.com/api/v4
PID=123
# Developer 相当（access_level=30）で、リポジトリの読み取りと API の読み取りだけを許すトークンを作る
curl --request POST \
--header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"name":"release-bot","description":"リリースノート生成用","scopes":["read_api","read_repository"],"access_level":30,"expires_at":"2027-05-31"}' \
"${GITLAB}/projects/${PID}/access_tokens"
# 応答 JSON の "token" に値が入る。再取得はできないので、この場でシークレット管理へ保存するaccess_levelは10（Guest）、15（Planner）、20（Reporter）、25（Security Manager）、30（Developer）、40（Maintainer）、50（Owner）で、省略すると40です。自分のロールより高い値は指定できません。既定の40は多くの自動化で過剰なので、明示して下げます。各ロールで許される操作の範囲はGitLabの権限（ロール）：Guest〜Ownerの操作範囲と保護ブランチの設定手順で整理しています。
ボットユーザーの命名規則・シート非消費・失効30日後の削除の挙動
プロジェクトかグループのトークンを作ると、GitLabはボットユーザーを自動で作ってトークンに紐づけます。ユーザー名はproject_{project_id}_bot_{ランダム文字列}またはgroup_{group_id}_bot_{ランダム文字列}の形式で、課金対象のユーザーに数えられず、ライセンスのシートを消費しません。MRやコミットの作成者にはこのボットが表示されるため、「誰の自動化か」を履歴から追えます。
注意したいのは削除のタイミングです。最後のトークンが失効するか期限切れになってから既定で30日後に、ボットユーザーとトークンが消え、ボットの貢献はghostユーザーへ移ります。ボット名で履歴を追う監査をしているなら、期限切れのまま放置しません。
スコープ17種の選択基準：API・Git操作の用途と読み書きの権限
用途別に最小のスコープを選ぶ早見表：clone・push・API・レジストリ
Access token scopesのドキュメントには17種のスコープがありますが、日常の用途で選ぶのは8つほどです。迷ったら次の表の最小のものから始め、足りなければ足します。
| やりたいこと | 選ぶスコープ |
|---|---|
| cloneとpullだけ | read_repository |
| pushもする | write_repository |
| APIで情報を読むだけ | read_api |
| APIでIssueやMRを作る | api |
| コンテナイメージのpull | read_registry |
| コンテナイメージのpush | write_registry |
| Runnerの作成 | create_runner |
| Runnerの管理 | manage_runner |
write_repositoryはGitのpushを許すスコープで、API認証には使えません。CIからタグをpushし、続けてAPIでリリースを作る処理ならwrite_repositoryとapiの両方が要ります。プロジェクト・グループのトークンでイメージをpushするには、write_registryに加えてread_registryも必要です。Runnerの登録に使うトークンはGitLab Runnerの登録手順とconfig.tomlの設定例で扱っています。
sudo・admin_modeなど個人専用スコープと従来型でMCPに接続できない制約
17種のうちadmin_mode・read_service_ping・sudo・read_userの4つは個人アクセストークン専用です。sudoは管理者として任意のユーザーになりすましてAPIを呼べるため、他人として操作する必要がある処理に限り、期限を短くして発行します。
17.9で追加されたself_rotateは、そのトークン自身のローテーションだけを許すスコープで、後述の自動更新で使います。従来型のトークンは、apiスコープを付けてもGitLab MCPサーバーに403で拒否されるため、接続にはfine-grainedのトークンかOAuthを使います。設定手順はGitLab MCPサーバーの接続設定を参照してください。
トークンを使う設定例：git clone・REST API・CI/CD変数での渡し方
Git over HTTPSでトークンを渡す方法とURL埋め込みを避ける理由
HTTPSでcloneやpushをするとき、ユーザー名には空でない任意の文字列、パスワードにはトークンを渡します。GitLabはユーザー名を検証しません。ドキュメントにはhttps://oauth2:<トークン>@gitlab.example.com/...のようにURLへ埋める例も載っていますが、token overviewのセキュリティ指針は、URLに含めると.git/configに平文で残り、プロキシやサーバーのログにも出るとして避けるよう求めています。VS Codeの公式拡張GitLab for VS Codeをトークンで認証する場合はapiスコープが必要で、その設定はVSCodeとGitLabの連携（公式拡張の導入と認証・MRレビュー・パイプライン操作）で扱っています。
# 資格情報ヘルパーに保存させる
git config --global credential.helper store # 平文ファイル保存。共有マシンでは使わない
git clone https://gitlab.example.com/example-group/app.git
# Username: oauth2 ← 任意の文字列でよい
# Password: glpat-xxxxxxxx ← アクセストークン
# 既存のリポジトリで URL にトークンを埋めていた場合は、URL から外す
git remote set-url origin https://gitlab.example.com/example-group/app.gitPRIVATE-TOKENヘッダーのcurl例とトークン自身を確認するAPI
REST APIではPRIVATE-TOKENヘッダーにトークンを入れます。token overviewの指針も、トークンはURLのクエリではなくヘッダーで渡すよう求めています（ヘッダーでトークンを渡す一般的な書き方はBearer Tokenの書き方とJWTとの違いを参照）。発行直後は、Personal access tokens APIのselfエンドポイントで、スコープと期限が意図どおりかを確かめます。
export GITLAB_TOKEN=glpat-xxxxxxxx # 実運用ではシークレット管理から読み込む
# 1) このトークン自身の情報（scopes・expires_at・active）を確認する
curl --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
"https://gitlab.example.com/api/v4/personal_access_tokens/self"
# 2) 参加しているプロジェクトを 20 件ずつ取得する（read_api で足りる）
curl --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
"https://gitlab.example.com/api/v4/projects?membership=true&per_page=20"1)の応答でscopesとexpires_atが想定どおりかを見ます。19.5以降は応答にgranular_scopesも含まれます。発行したトークンでAPIを呼ぶときのページネーションやレート制限への対処はGitLab APIの使い方：トークン認証とcurl例・ページネーションとレート制限の実装で扱っています。
CI/CDでは個人トークンより先にCI_JOB_TOKENとプロジェクトトークンを選ぶ
CIのジョブから同じプロジェクトや別プロジェクトを触るとき、最初に検討するのはCI_JOB_TOKENです。CI/CD job tokenのドキュメントによると、このトークンはジョブの実行中だけ有効で、パイプラインを起動したユーザーと同じロールで動きます。発行も期限管理も要りません。
# .gitlab-ci.yml
fetch-shared-config:
stage: build
script:
# 別プロジェクトのリポジトリを clone（相手側の job token allowlist に本プロジェクトの追加が必要）
- git clone "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/example-group/shared-config.git"
# API は JOB-TOKEN ヘッダーで呼ぶ（使えるエンドポイントは限られる）
- 'curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages"'ジョブトークンで届かない操作（GraphQLなど）だけ、プロジェクトかグループのトークンをCI/CD変数に入れ、Protected・Masked・Hiddenを設定して渡します。変数の設定方法はGitLab CI/CDのrules・needs・変数の設定例にあります。
有効期限とローテーション運用：365日上限・通知・self_rotateでの自動更新
有効期限365日の上限と7日・30日・60日前の期限切れ通知の仕組み
3種類とも、有効期限の上限は既定で作成日から365日です。日付を入れずに作ると365日後が自動で入ります。期限切れは指定日の0時（UTC）、日本時間では当日の9時です。朝のバッチが9時をまたいで止まらないよう、期限は業務日の前日以前にそろえます。
GitLab 17.6以降は管理者がインスタンスの上限を変えられ、機能フラグbuffered_token_expiration_limit（既定は無効）で400日まで延ばせます。期限切れの通知は毎日1時（UTC）に判定され、7日前に加えて17.6以降は30日前と60日前にもメールが届きます。プロジェクト・グループのトークンの通知先はMaintainerかOwnerです。
self_rotateとrotate APIによる期限前のトークン更新スクリプト
期限が来たトークンは延長できません。同じ権限とスコープで新しい値を出し直すのがrotateで、画面ではトークン一覧の縦三点リーダーからRotateを選びます。旧トークンはその場で無効になり、取り消しはできません。
自動化する場合の落とし穴はexpires_atの既定値です。APIのrotateでexpires_atを省くと、期限が必要な設定では新しいトークンの期限が1週間後になります。毎月回すつもりのスクリプトが、翌週に止まる原因です。
#!/usr/bin/env bash
# 自分自身をローテーションする（トークンに api か self_rotate スコープが必要）
set -euo pipefail
NEW_EXPIRY=$(date -u -d "+90 days" +%Y-%m-%d) # 省略すると 1 週間後になるので必ず指定する
RESP=$(curl --fail --silent --request POST \
--header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
--data "expires_at=${NEW_EXPIRY}" \
"https://gitlab.example.com/api/v4/personal_access_tokens/self/rotate")
NEW_TOKEN=$(echo "${RESP}" | jq -r '.token')
# ここで NEW_TOKEN をシークレット管理へ書き戻す。書き戻しに失敗すると旧トークンも使えず止まる
echo "rotated: expires_at=$(echo "${RESP}" | jq -r '.expires_at')"プロジェクトアクセストークンならPOST /projects/:id/access_tokens/self/rotateで同じことができます。GitLabは新旧のトークンを「トークンファミリー」として記録しており、すでに失効したトークンでrotateを試みると、同じファミリーの有効なトークンもまとめて失効します。旧トークンを持ち出した第三者が使った場合の被害を止める仕組みです。漏えいが疑われるときは、rotateではなく画面のRevokeかDELETE /personal_access_tokens/selfで即時に失効させます。
アクセストークンの種類を決める判断：個人トークンを使わない場面と採用条件
個人アクセストークンを共有の自動化に使ってはいけない場面と失敗パターン
個人アクセストークンを使ってよいのは、本人が手元で使う場合と、本人が保守する短命なスクリプトの場合だけです。チームで共有するCI、夜間バッチ、外部サービスとの連携には使いません。
典型的な失敗は2つあります。1つ目は退職や異動で、担当者のアカウントを無効にした瞬間に、そのトークンで動いていたCIや連携が一斉に止まります。2つ目は権限の過大さです。1つのリポジトリ向けに発行したapiスコープの個人トークンが漏れると、本人が触れる他のプロジェクトまで書き換えられます。GitHubでも同じ問題があり、GitHub PATの作成方法とfine-grainedの違いで扱っている考え方はGitLabにもそのまま当てはまります。
どうしても個人トークンを使うなら、fine-grainedで対象のプロジェクトと操作を絞り、期限を90日以内にします。この2点を満たせないなら、プロジェクトかグループのトークンに切り替える判断が妥当です。
GitLab.com Freeのプロジェクトトークン代替：サービスアカウント
GitLab.comのFreeでは、プロジェクト・グループアクセストークンが使えません。代わりになるのがサービスアカウントです。Service accountsのドキュメントによると、Freeでの提供は18.10で機能フラグ付きで入り、18.11で一般提供になりました。人ではない主体を表すユーザーで、シートを消費しません。
GitLab.comではトップレベルグループのOwnerがSettings > Service accountsから作り、そのアカウントの個人アクセストークンで認証します。Freeでの上限は、トップレベルグループごとに100件（配下で作ったものを含む）です。退職でCIが止まる問題と、届く範囲が人の権限に引きずられる問題を、プランを上げずに避けられます。Premium以上で1プロジェクトに閉じた自動化ならプロジェクトアクセストークン、それ以外ならサービスアカウント、と決めておけば迷いません。
トークンの棚卸しや、CIの認証を個人トークンから切り替える作業を既存のパイプラインごと見直したい場合は、一創のDevOps・CI/CD導入支援で、現在のトークンの用途と届く範囲を洗い出したうえで置き換えの手順を作成できます。承認ルールなどMR側の設定とあわせて整える場合はGitLabのマージリクエストの承認ルール設定も参考になります。
よくある質問
GitLabのアクセストークンについて、発行と運用の段階でよく出る質問をまとめました。
発行したGitLabのアクセストークンの値はあとから確認できますか？
確認できません。値が表示されるのは作成直後の1回だけで、一覧画面にもAPIにも値は出ません。控え忘れた場合は、Revokeして新しく発行するか、rotateで新しい値を出します。一覧で確認できるのは名前・スコープ・期限・最終使用日時です。
有効期限なしのアクセストークンは作れますか？
通常の個人・プロジェクト・グループのトークンでは作れず、上限は既定で365日です。例外はサービスアカウントのトークンで、有効期限を必須としない設定になっている場合に限り、期限なしで作られます。期限なしのトークンは漏えいしたときに止まらないため、作れる環境でも期限を入れることを勧めます。
git cloneのときユーザー名には何を入れればよいですか？
空でなければ何でもかまいません。GitLabはユーザー名を検証せず、パスワード欄のトークンで認証します。oauth2や自分のユーザー名を入れる例が多いです。CIジョブトークンを使う場合だけは、ユーザー名にgitlab-ci-tokenを入れる決まりになっています。
期限が切れたアクセストークンを延長できますか？
延長はできず、期限切れのトークンを生かす手段もありません。期限前ならrotateで同じ権限とスコープの新しいトークンへ入れ替えられるので、30日前・60日前の通知を受けた時点でrotateし、使っている設定の値を更新します。
glpat-で始まる文字列は何のトークンですか？
個人アクセストークンの接頭辞で、プロジェクト・グループのアクセストークンと代理トークン（Impersonation token）も同じglpat-で始まります。パイプライントリガートークンはglptt-です。リポジトリやログで見つけた場合は漏えいとして扱い、すぐに失効させます。
関連記事
- GitLabとは：構成要素・CEとEEの違い・3つの提供形態とDockerで試す手順【2026年11月】：提供形態とプランの違いを確認できます
- GitLabの使い方：プロジェクト作成からIssue・MR・CI/CDまでの手順【2026年10月】：初期設定からGitLabを1周するときの入口です
- GitLab MCPサーバーの接続設定：Claude Code・Cursorでの使い方とツール一覧【2026年11月】：fine-grainedのトークンでAIエージェントをつなぐ手順です
- GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較：サービス自体を比べたいときに役立ちます
- GitHub PAT（Personal Access Token）とは？作成方法・classicとfine-grainedの違い・確認と失効【2026年10月】：GitHub側で同じ種類のトークンを発行する場合の手順です
