Rotate Service Account Personal Access Tokens (PATs)
Rotate Service Account Personal Access Tokens (PATs) Runbook
This runbook is an approach to rotating a GitLab Service Accounts Personal Access Tokens (PATs). From here on out we will refer to Personal Access Tokens as PATS and singular use of Personal Access Token as PAT.
1. Why is this important?
- Services Accounts can have their PATs expire and therefore preventing resources from being accessed. This blocks API access, Pipeline completion, and individual jobs from running properly and completing their work.
- This runbook is meant to be a structured way to help someone new to this problem, or as a reminder to those who have engaged this problem before but forgot specifics, to attempt to solve the issue with PAT rotations for the Service Accounts.
2. Pre-requisites?
- Find the affected Service Account, hopefully you or someone in the team will receive an email like the one in the screenshot below:
- If not already completed, create an issue like GitLab Security Service - Architecture - Inventory’s PAT expired.
- Check and see if you have access to the Service Accounts login credentials in 1Password like below:
- If you do not have access, submit an Access Request (AR) like this issue.
3. Steps to fix
- Make sure you are logged out of your personal account on GitLab.com.
- Using the Service Accounts credentials in 1Password, login in to GitLab.com with them.
- Use the
one-time password
parameter in 1Password for the MFA OTP. - You should land on the Service Account’s Project page like below:
- Select the Service Account’s icon and click on
Edit Profile
like below:
- Click on
Access tokens
in theUser settings
then click theAdd new token
button:
- Add the
Token name
that matches the previous token that had expired, in this case it isGitLab Security Service - Architecture - Inventory
. - Add a
Description
of what the token is used for. - For
Expiration Date
set it for 365 days in the future (the maximum expiration). If you do not set it, it is default to expire in 30 days. - Click the
Select scopes
permission level that best matches what access the Service account needs (In this case it is API only), like in the image below:
- Before you click
Create Token
make sure to scroll down the page andRevoke
the old token, as shown in the image below:
- Then click the
Create token
button and review the confirmation that the new token is in the PAT list onPersonal access tokens
page.
4. Steps to test
- Logout of the Service Account and back in to an Account that has permissions to re-run any pipelines associated with the Service Accounts PAT.
- For this particular Service Account, the GitLab Inventory Builder uses this Service Accounts PAT to access APIs.
- So re-running a pipeline job for that repository that was previously failing due to token errors, demonstrated that the PAT rotation was successful as seen in the image below:
- If the pipeline passes, congratulations, update the issue with the success and notify any concerned parties of the successful PAT rotation, and finally, close the associated issue.
Last modified July 9, 2025: Added ProdSecEng runbook for rotating service account PATs (
ffb4cadb
)