From 57778f033c2cdc099d2dc3e2cd8285eb57936cf9 Mon Sep 17 00:00:00 2001 From: Philipp Scheit Date: Mon, 21 Jul 2025 16:55:40 +0200 Subject: [PATCH 1/2] Adding an article about the GitLab token rotation --- features/gitlab-automatic-token-rotation.md | 86 +++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 features/gitlab-automatic-token-rotation.md diff --git a/features/gitlab-automatic-token-rotation.md b/features/gitlab-automatic-token-rotation.md new file mode 100644 index 00000000..7d9e2577 --- /dev/null +++ b/features/gitlab-automatic-token-rotation.md @@ -0,0 +1,86 @@ +# Automatic GitLab Token Rotation +## + +Your GitLab access token expired again, breaking your `composer install` in production at 3 AM. Sound familiar? + +This became a widespread problem starting in May 2023 when GitLab began requiring all new tokens to expire within 365 days, then reached a crisis point in May 2024 when existing non-expiring tokens were forced to expire on May 14, 2024. Many developers were caught off guard when their long-running integrations suddenly stopped working. + +Private Packagist automatically rotates your GitLab tokens before they expire, eliminating those surprise failures that disrupt your development workflow and break CI/CD pipelines. + +## How automatic token rotation works + +Private Packagist monitors your GitLab tokens and automatically rotates them 24 hours before expiration. No more emergency scrambles to update tokens across your development team, CI systems, and production environments. + +When a token is about to expire, Private Packagist uses GitLab's official rotation API to seamlessly create a new token and update your credentials in the background. Your existing composer projects, CI/CD systems, and development workflows continue without any interruptions. + +### Requirements for automatic rotation + +Your GitLab token must have these scopes: +- `api` - Required for GitLab API access +- `read_user` - Required to read user information +- `self_rotate` - Required for automatic token rotation + +
+
+

Tokens without the self_rotate scope cannot be automatically rotated and may cause service interruptions when they expire.

+
+
+ +## Setting up automatic token rotation + +### Creating a GitLab token with rotation support + +1. Go to your GitLab instance (GitLab.com or self-hosted) +2. Navigate to token settings: + - **Personal tokens**: Profile → Access Tokens + - **Group tokens**: Group Settings → Access Tokens + - **Project tokens**: Project Settings → Access Tokens +3. Create a new token: + - Enter a descriptive name like "Private Packagist" + - Set your preferred expiration date + - Check the scopes: `api`, `read_user`, and `self_rotate` +4. Generate the token and copy it immediately +5. Add the token to Private Packagist in your credentials section + +### GitLab version requirements + +| GitLab Version | Automatic Rotation | +|---------------|-------------------| +| 17.9.0 and later | ✅ Supported | +| Before 17.9.0 | ❌ Not supported | +| GitLab.com | ✅ Always supported | + +## Works with all token types + +Whether you use personal access tokens, group access tokens, or project access tokens, Private Packagist handles the rotation seamlessly: + +**Personal Access Tokens** +Created by individual users with their account permissions. + +**Group Access Tokens** +Created at the group level, recommended for organizational use. + +**Project Access Tokens** +Scoped to specific projects with project-level permissions. + +## Monitoring your tokens + +Check your credentials section in Private Packagist to view: +- Token expiration dates +- Available scopes +- Last rotation date + +Rotation activities are logged in your organization log for audit and security purposes. + +## Troubleshooting rotation issues + +### Token not rotating automatically +- Verify your token has the `self_rotate` scope +- Check your GitLab version is 17.9.0 or later +- Ensure the token hasn't already expired + +### GitLab version too old +- Upgrade to GitLab 17.9.0 or later for automatic rotation +- Manually renew tokens for older GitLab versions + +**Ready to eliminate token expiration headaches?** Private Packagist's automatic GitLab token rotation runs in the background, ensuring your development workflow doesn't get interrupted by expired credentials again. \ No newline at end of file From 027398c3e843b146904540d89cbc949fa1896bfc Mon Sep 17 00:00:00 2001 From: Philipp Scheit Date: Mon, 21 Jul 2025 17:39:23 +0200 Subject: [PATCH 2/2] Api scope includes self rotation There is no auditlog nor scopes shown on the credential page --- features/gitlab-automatic-token-rotation.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/features/gitlab-automatic-token-rotation.md b/features/gitlab-automatic-token-rotation.md index 7d9e2577..d673698c 100644 --- a/features/gitlab-automatic-token-rotation.md +++ b/features/gitlab-automatic-token-rotation.md @@ -15,14 +15,11 @@ When a token is about to expire, Private Packagist uses GitLab's official rotati ### Requirements for automatic rotation -Your GitLab token must have these scopes: -- `api` - Required for GitLab API access -- `read_user` - Required to read user information -- `self_rotate` - Required for automatic token rotation +Your GitLab token must have either the `api` scope (which includes rotation capabilities) or the `self_rotate` scope for rotation-only permission.
-

Tokens without the self_rotate scope cannot be automatically rotated and may cause service interruptions when they expire.

+

Most GitLab integrations already use the api scope, which supports automatic rotation. Tokens without either api or self_rotate scope cannot be automatically rotated.

@@ -38,7 +35,7 @@ Your GitLab token must have these scopes: 3. Create a new token: - Enter a descriptive name like "Private Packagist" - Set your preferred expiration date - - Check the scopes: `api`, `read_user`, and `self_rotate` + - Check the required scopes: `api` and `read_user` (the `api` scope enables automatic rotation) 4. Generate the token and copy it immediately 5. Add the token to Private Packagist in your credentials section @@ -65,12 +62,7 @@ Scoped to specific projects with project-level permissions. ## Monitoring your tokens -Check your credentials section in Private Packagist to view: -- Token expiration dates -- Available scopes -- Last rotation date - -Rotation activities are logged in your organization log for audit and security purposes. +Private Packagist displays a warning icon with expiration information for credentials that are expiring soon or have already expired. ## Troubleshooting rotation issues