Skip to content

GitLab Service Account Provisioning Playbook — DRUPAL Agent

Playbook ID: PLY-GITLAB-SA-DRUPAL-001 Standard: STD-GITLAB-SA-001 — GitLab Service Accounts Target role: drupal-agent Target GitLab username: bluefly-drupal-agent

Prerequisites (human gate — Thomas only)

The following steps require human action. Agents may not self-provision.

  • [ ] GitLab Group Owner access to blueflyio group
  • [ ] 1Password admin access to create a Service Account
  • [ ] Access to GitLab Admin area (or group-level service account creation if supported)

Step 1 — Create GitLab Service Account

Human action required. Complete via GitLab UI or API.

  1. Navigate to https://gitlab.com/groups/blueflyio/-/service_accounts (or Admin → Users if group SA not available).
  2. Create a new service account with:
  3. Username: bluefly-drupal-agent
  4. Name: Bluefly Drupal Agent
  5. Email: [email protected]
  6. Generate a Personal Access Token for this account:
  7. Name: drupal-agent-main
  8. Scopes: read_repository, write_repository, create_mr (add others only with approval)
  9. Expiry: 365 days (record in 1Password with rotation reminder)
  10. Record the token in 1Password under the Bluefly Agents vault:
  11. Item name: GitLab PAT — bluefly-drupal-agent
  12. Field: token (the raw token value)

Step 2 — Verify GitLab Identity

Run this verification as the service account token (not as the human operator):

GITLAB_TOKEN=<token-from-1password>
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" https://gitlab.com/api/v4/user | jq '{id, username, name, email}'

Expected output: 

{
  "id": <number>,
  "username": "bluefly-drupal-agent",
  "name": "Bluefly Drupal Agent",
  "email": "[email protected]"
}

Do not proceed if username does not match bluefly-drupal-agent.

Record result: 

VERIFICATION_DATE=
VERIFIED_USERNAME=bluefly-drupal-agent
VERIFIED_BY=              # Thomas's name

Step 3 — Store Token in 1Password Service Account

  1. Create or verify a 1Password Service Account that agents can use to retrieve this token at runtime.
  2. The reference (op:// URI) goes into the Gas City agent session config — never the raw token.
  3. Confirm op run resolves the reference correctly (do not print the token value):
op run --env-file=<agent-env> -- printenv GITLAB_TOKEN | wc -c   # confirms token is present; length only

Step 4 — Add to CODEOWNERS

In every repository the drupal-agent is authorized to merge into, add to CODEOWNERS:

# Drupal agent — autonomous MR author; @bluefly is still required reviewer
* @bluefly @bluefly-drupal-agent

Commit this change as @bluefly (human), not as the service account.

Step 5 — Wire Git Identity in Gas City Session Config

In the drupal-agent's session template (BluCity-Packs), add or confirm:

[agents.drupal-agent.git_identity]
name  = "Bluefly Drupal Agent"
email = "[email protected]"

This ensures every git commit made by the agent carries the correct author.

Step 6 — Test Push Verification

Make a test commit as the drupal-agent on a scratch branch:

git checkout -b test/drupal-agent-identity
git commit --allow-empty -m "chore(identity): verify drupal-agent git identity"
git push origin test/drupal-agent-identity

Verify on GitLab: - Commit author: Bluefly Drupal Agent <[email protected]> - Authenticated as: bluefly-drupal-agent

Delete the scratch branch after verification.

Step 7 — Update Registry

Once all steps above are complete and verified, update agent-identity-registry.yaml:

# Find the drupal-agent entry and change:
gitlab_principal: bluefly-drupal-agent    # was: NOT_YET_PROVISIONED
provisioning_status: PROVISIONED           # was: NOT_YET_PROVISIONED

Add a note with the verification date and verifier name.

Step 8 — Record in Machine Identity Catalog

Update machine-identity-catalog.md DRUPAL row:

ROLE MACHINE_IDENTITY ONEPASSWORD_PRINCIPAL GITLAB_PRINCIPAL AUTH_SCOPE ROTATION_METHOD
DRUPAL bluefly-drupal-agent (Gas City session) Bluefly Agents / GitLab PAT — bluefly-drupal-agent bluefly-drupal-agent read_repository, write_repository, create_mr Annual rotation via 1Password reminder; new token replaces old in vault; agent picks up on next session start

Rollback

If provisioning fails or the account is compromised:

  1. Revoke the GitLab PAT immediately (GitLab UI → Service account → Tokens → Revoke).
  2. Remove the op:// reference from the agent session config.
  3. Set provisioning_status: NOT_YET_PROVISIONED in the registry.
  4. Create a P0 bead if the failure was a security event.

This playbook is the evidence record for STD-GITLAB-SA-001 compliance for the DRUPAL agent role.