Provision Access on Hire

Automatically provision department-specific application access when new employees join your organization.

---

Overview

This GitHub Action workflow automatically grants access to applications based on an employee's department when they join your organization. It supports department-based app mapping, automatic permission level detection, and comprehensive logging.

Features

• Department-based provisioning: Automatically assign apps based on job department

• Bulk access management: Grant access to multiple applications in a single operation

• Permission level detection: Automatically finds and uses appropriate permission levels

• Comprehensive logging: Detailed logs for audit and troubleshooting

• Error handling: Robust error handling with detailed error messages

Prerequisites

Repository Secrets

Configure these secrets in your GitHub repository:

• CAKEWALK_API_KEY: Your Cakewalk API key

• CAKEWALK_API_SECRET: Your Cakewalk API secret

Required Information

You'll need to gather the following IDs from your Cakewalk instance:

• WorkApp IDs: For each application you want to manage

• User IDs: For users you want to provision access for

• Permission Level IDs: For each WorkApp (or use automatic detection)

Setup Instructions

1. Create the Workflow File

Create .github/workflows/provision-new-hire.yml in your repository:

name: Provision Cakewalk Access for New Hire

on:
  workflow_dispatch:
    inputs:
      employee_email:
        description: 'New employee email'
        required: true
        type: string
      employee_name:
        description: 'New employee name'
        required: true
        type: string
      department:
        description: 'Department (engineering, sales, marketing, etc.)'
        required: true
        type: choice
        options:
          - engineering
          - sales
          - marketing
          - operations
          - finance

jobs:
  provision-access:
    runs-on: ubuntu-latest
    steps:
      - name: Get User ID
        id: get_user
        run: |
          # Fetch all users and find by email
          response=$(curl -s "https://open-api.getcakewalk.io/api/v1/Users" \
            -H "X-API-KEY: ${{ secrets.CAKEWALK_API_KEY }}" \
            -H "X-API-SECRET: ${{ secrets.CAKEWALK_API_SECRET }}")
          
          user_id=$(echo "$response" | jq -r ".data[] | select(.email == \"${{ github.event.inputs.employee_email }}\") | .id")
          
          if [ -z "$user_id" ]; then
            echo "Error: User ${{ github.event.inputs.employee_email }} not found in Cakewalk"
            exit 1
          fi
          
          echo "user_id=$user_id" >> $GITHUB_OUTPUT
          echo "✓ Found user: $user_id"

      - name: Define Apps for Department
        id: define_apps
        run: |
          # Define WorkApp IDs per department
          # IMPORTANT: Replace these UUIDs with your actual WorkApp IDs
          # Find these by calling: GET /api/v1/WorkApps
          
          case "${{ github.event.inputs.department }}" in
            engineering)
              # GitHub, AWS, Datadog, PagerDuty
              app_ids="GITHUB_WORKAPP_ID,AWS_WORKAPP_ID,DATADOG_WORKAPP_ID,PAGERDUTY_WORKAPP_ID"
              ;;
            sales)
              # Salesforce, HubSpot, Slack, Zoom
              app_ids="SALESFORCE_WORKAPP_ID,HUBSPOT_WORKAPP_ID,SLACK_WORKAPP_ID,ZOOM_WORKAPP_ID"
              ;;
            marketing)
              # HubSpot, Google Analytics, Figma, Slack
              app_ids="HUBSPOT_WORKAPP_ID,ANALYTICS_WORKAPP_ID,FIGMA_WORKAPP_ID,SLACK_WORKAPP_ID"
              ;;
            operations)
              # Slack, Zoom, Google Workspace, Atlassian
              app_ids="SLACK_WORKAPP_ID,ZOOM_WORKAPP_ID,GWORKSPACE_WORKAPP_ID,ATLASSIAN_WORKAPP_ID"
              ;;
            finance)
              # QuickBooks, Expensify, Slack, Google Workspace
              app_ids="QUICKBOOKS_WORKAPP_ID,EXPENSIFY_WORKAPP_ID,SLACK_WORKAPP_ID,GWORKSPACE_WORKAPP_ID"
              ;;
          esac
          
          echo "app_ids=$app_ids" >> $GITHUB_OUTPUT

      - name: Provision Access to Applications
        run: |
          USER_ID="${{ steps.get_user.outputs.user_id }}"
          IFS=',' read -ra APP_LIST <<< "${{ steps.define_apps.outputs.app_ids }}"
          
          # Build access grants array
          grants_json="[]"
          
          for workapp_id in "${APP_LIST[@]}"; do
            echo "Preparing access grant for WorkApp: $workapp_id"
            
            # Get permission levels for this app to find default
            perms_response=$(curl -s "https://open-api.getcakewalk.io/api/v1/WorkApps/$workapp_id/PermissionLevels" \
              -H "X-API-KEY: ${{ secrets.CAKEWALK_API_KEY }}" \
              -H "X-API-SECRET: ${{ secrets.CAKEWALK_API_SECRET }}")
            
            # Get the default permission level ID
            perm_level_id=$(echo "$perms_response" | jq -r '.data[] | select(.isDefault == true) | .id')
            
            if [ -z "$perm_level_id" ]; then
              # If no default, use first permission level
              perm_level_id=$(echo "$perms_response" | jq -r '.data[0].id')
            fi
            
            # Add to grants array
            grant="{\"workAppId\":\"$workapp_id\",\"userId\":\"$USER_ID\",\"permissionLevelId\":\"$perm_level_id\"}"
            grants_json=$(echo "$grants_json" | jq ". + [$grant]")
          done
          
          # Submit all grants in one request
          echo "Submitting access grants..."
          
          payload=$(jq -n --argjson data "$grants_json" '{data: $data}')
          
          response=$(curl -s -w "\n%{http_code}" \
            -X POST "https://open-api.getcakewalk.io/api/v1/WorkApps/Accesses" \
            -H "X-API-KEY: ${{ secrets.CAKEWALK_API_KEY }}" \
            -H "X-API-SECRET: ${{ secrets.CAKEWALK_API_SECRET }}" \
            -H "Content-Type: application/json" \
            -d "$payload")
          
          http_code=$(echo "$response" | tail -n1)
          body=$(echo "$response" | sed '$d')
          
          if [ "$http_code" -eq 201 ] || [ "$http_code" -eq 204 ]; then
            echo "✅ Successfully provisioned access to ${#APP_LIST[@]} applications"
          else
            echo "❌ Failed to provision access (HTTP $http_code)"
            echo "$body"
            exit 1
          fi

      - name: Post Summary
        run: |
          echo "## 🎉 Provisioning Complete" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Employee:** ${{ github.event.inputs.employee_name }}" >> $GITHUB_STEP_SUMMARY
          echo "**Email:** ${{ github.event.inputs.employee_email }}" >> $GITHUB_STEP_SUMMARY
          echo "**User ID:** ${{ steps.get_user.outputs.user_id }}" >> $GITHUB_STEP_SUMMARY
          echo "**Department:** ${{ github.event.inputs.department }}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "✅ Access granted to department applications" >> $GITHUB_STEP_SUMMARY

2. Find Your WorkApp IDs

# List all WorkApps
curl https://open-api.getcakewalk.io/api/v1/WorkApps \
  -H "X-API-KEY: $CAKEWALK_API_KEY" \
  -H "X-API-SECRET: $CAKEWALK_API_SECRET" | jq '.data[] | {id, name}'

3. Update WorkApp IDs

Replace the placeholder IDs in the workflow with your actual WorkApp UUIDs:

case "${{ github.event.inputs.department }}" in
  engineering)
    app_ids="your-github-workapp-id,your-aws-workapp-id,your-datadog-workapp-id"
    ;;
  # ... other departments
esac

4. Test the Workflow

1. Go to your repository's Actions tab

2. Select Provision Cakewalk Access for New Hire

3. Click Run workflow

4. Fill in the required inputs:

   • Employee email

   • Employee name

   • Department

5. Click Run workflow

Customization

Adding New Departments

To add a new department, update the workflow:

case "${{ github.event.inputs.department }}" in
  # ... existing departments
  customer_success)
    app_ids="ZENDESK_WORKAPP_ID,INTERCOM_WORKAPP_ID,SLACK_WORKAPP_ID"
    ;;
esac

Adding Approval Step

For sensitive departments, add an approval step:

jobs:
  request-approval:
    runs-on: ubuntu-latest
    steps:
      - uses: trstringer/manual-approval@v1
        with:
          approvers: security-team,hr-team
          minimum-approvals: 1
          
  provision-access:
    needs: request-approval
    # ... rest of job

Custom Permission Levels

To use specific permission levels instead of defaults:

# Replace automatic detection with specific IDs
case "${{ github.event.inputs.department }}" in
  engineering)
    app_ids="GITHUB_WORKAPP_ID:AWS_WORKAPP_ID"
    perm_levels="GITHUB_DEVELOPER_PERM_ID:AWS_DEVELOPER_PERM_ID"
    ;;
esac

Monitoring & Troubleshooting

Workflow Logs

• Check the Actions tab for detailed execution logs

• Look for error messages in the step outputs

• Review the summary report for success/failure details

Common Issues

"User not found" Error:

• Verify the user exists in Cakewalk

• Check email spelling and case sensitivity

• Ensure the user has been invited to your organization

"401 Unauthorized" Error:

• Verify API key and secret are correct

• Check that credentials haven't expired

• Ensure proper header formatting

"Permission level not found" Error:

• Verify the WorkApp has permission levels configured

• Check that the permission level is active

• Ensure the WorkApp ID is correct

Security Considerations

• API Credentials: Store as repository secrets, never in code

• Access Review: Regularly review who has access to what

• Audit Logging: All access grants are logged for audit purposes

• Testing: Always test with non-production data first

Next Steps

• Set up monitoring: Configure alerts for failed workflows

• Add notifications: Integrate with Slack or email for workflow results

• Scale up: Once confident, expand to more departments and applications

• Automate further: Consider triggering from HR systems or other tools