Add return_token input to enable sharing rotated tokens across jobs

Closes #4 (closed)

Summary

This MR adds a return_token boolean input to all token rotation components, allowing tokens to be returned via dotenv artifacts for use in downstream jobs. This enables platform project owners to rotate a token once and update multiple CI/CD variables across different projects.

Changes

• Add return_token boolean input (default: false) to all three components:
  • rotate-pat
  • rotate-project-access-token
  • rotate-group-access-token
• Create dotenv artifact with NEW_TOKEN when return_token: true
• Add verify-new-token test job to validate token availability in downstream jobs
• Update test-name-based job to use return_token: true
• Add comprehensive usage example to README showing multi-project updates

Implementation Details

When return_token: true, the component:

1. Rotates the token as usual
2. Updates the specified CI/CD variable (existing behavior)
3. Creates a token.env artifact containing NEW_TOKEN=<rotated_token>
4. Downstream jobs can access $NEW_TOKEN via GitLab's dotenv artifact feature

Testing

• Updated existing test to use return_token: true
• Added new verification job that checks:
  • $NEW_TOKEN variable is set
  • Token has correct format (starts with glpat-)
  • Token length is reasonable

Use Case Example

stages:
  - rotate
  - update-vars

include:
  - component: .../rotate-pat@1.0.0
    inputs:
      token_name: shared-deployment-token
      return_token: true
      # ... other inputs

update-project-a:
  stage: update-vars
  needs: [rotation-job]
  script:
    - # Use $NEW_TOKEN to update Project A

update-project-b:
  stage: update-vars
  needs: [rotation-job]
  script:
    - # Use $NEW_TOKEN to update Project B

This eliminates the workaround of needing one token per CI/CD variable.