Federation PAT Migration Guide¶

Overview¶

SkillMeat v0.49.0 introduces a new project:deploy Personal Access Token (PAT) scope that replaces the legacy materialization:write scope for federation deployment operations. This guide helps you migrate your existing tokens to the new scope during the 90-day deprecation window.

What Changed¶

Aspect	Details
New Scope	`project:deploy` — narrower, purpose-specific scope for deployment operations
Legacy Scope	`materialization:write` — deprecated, remains functional for 90 days
Timeline	90-day migration window from release date; enforcement on Day 90
Impact	Affects enterprise deployments using federation `deploy-pull` operations
Telemetry	Migration progress tracked via `federation.pull.legacy_auth_count` metric

Identify Legacy Tokens¶

Via SkillMeat Web UI¶

Navigate to Settings → Personal Access Tokens
Locate any PATs with scope materialization:write
Note the token name and creation date

Via API (Programmatic)¶

# List all PATs and their scopes
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-skillmeat-instance/api/v1/users/me/pats

Look for any entries where scopes contains "materialization:write".

Via CLI¶

# Check configured enterprise PAT (if set)
skillmeat config get pats --enterprise

# Token scope is not directly visible via CLI; use web UI or API

Create New PAT with `project:deploy`¶

Web UI Method¶

Go to Settings → Personal Access Tokens → New Token
Enter a token name (e.g., federation-deploy-2026)
Select scope: project:deploy (do NOT select materialization:write)
Set expiration (recommended: 90 days or per your org policy)
Click Create and copy the token immediately (not viewable again)

API Method¶

# Create a new PAT with project:deploy scope
curl -X POST https://your-skillmeat-instance/api/v1/users/me/pats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "federation-deploy-2026",
    "scopes": ["project:deploy"],
    "expires_in_days": 90
  }'

# Response includes the token value (copy immediately)

CLI Method¶

# Mint a new PAT (web UI redirect for manual scope selection)
skillmeat auth pats create --name federation-deploy-2026 --scope project:deploy

Update Deployment Environments¶

SkillMeat CLI Configuration¶

# Update enterprise instance with new token
skillmeat config set pats.enterprise "skillmeat-pat-xxx..."

# Verify
skillmeat config get pats.enterprise

Environment Variables¶

Update any scripts or CI/CD pipelines:

# Before
export SKILLMEAT_ENTERPRISE_PAT="skillmeat-pat-old-materialization-write..."

# After
export SKILLMEAT_ENTERPRISE_PAT="skillmeat-pat-new-project-deploy..."

GitHub Actions / CI Integration¶

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy with new PAT scope
        env:
          SKILLMEAT_ENTERPRISE_PAT: ${{ secrets.SKILLMEAT_PAT_NEW }}  # project:deploy scope
        run: |
          skillmeat deploy-pull --auto-create-branch

Scope Comparison¶

Operation	`materialization:write`	`project:deploy`
Deploy to project	✓ Allowed	✓ Allowed
Federation pull	✓ Allowed	✓ Allowed
Create branch	✓ Allowed	✓ Allowed
Delete project	✗ Not allowed	✗ Not allowed
Modify ACL	✗ Not allowed	✗ Not allowed

Both scopes have identical permissions for deployment operations.

Timeline¶

Phase	Date	Action
Released	2026-05-20	`project:deploy` scope available; legacy scope still active
Migration Window	2026-05-20 — 2026-08-18	Both scopes work; telemetry collected
Enforcement	2026-08-18	`materialization:write` disabled; only `project:deploy` accepted
Cleanup	Post-enforcement	Ops team removes legacy PAT entries

Migration Checklist¶

[ ] Identify all legacy materialization:write tokens (see Identify Legacy Tokens section)
[ ] Create replacement tokens with project:deploy scope
[ ] Update environment variables in local configs
[ ] Update CI/CD pipeline secrets with new token
[ ] Update GitHub Actions / Terraform / IaC with new PAT
[ ] Test skillmeat deploy-pull with new token
[ ] Revoke old token(s) once new ones are verified
[ ] Confirm new token works in production before Day 90

What Happens at Day 90 (Enforcement)¶

Before Day 90: - Legacy materialization:write PATs continue to work - API responses include X-Deprecated-Auth header warning - CLI emits deprecation warnings on each invocation

At Day 90: - materialization:write scope disabled - New requests with legacy tokens receive HTTP 401 Unauthorized - Error message directs you to this guide - Ops team begins cleanup of orphaned legacy tokens

Impact on workflows: - Deployments using legacy tokens will fail - skillmeat deploy-pull commands will return 401 - CI/CD pipelines must have been updated beforehand

Troubleshooting¶

"Invalid scope: project:deploy"¶

Cause: You're running an outdated version of SkillMeat without the project:deploy scope.

Solution: Upgrade to v0.49.0 or later.

"authentication failed" on deploy-pull¶

Cause: Token has expired or uses wrong scope.

Solution: 1. Check token expiration in web UI 2. Verify token scope is project:deploy (not materialization:write) 3. Create a fresh token if needed

Deployment succeeds but shows "Deprecated authentication"¶

Cause: Token is still using legacy materialization:write scope.

Action: Create a new token with project:deploy scope and update your environment.

Support¶

If you encounter issues during migration:

Check the troubleshooting section above
Review the Authentication Setup Guide for general auth configuration
Contact your SkillMeat admin or support team with:
The error message from skillmeat deploy-pull (redact actual token)
Your SkillMeat version (skillmeat --version)
When you created your PAT