elevanaltd ===VERCEL_PREVIEW=== META: TYPE::SKILL VERSION::1.0 STATUS::ACTIVE COMPRESSION_TIER::AGGRESSIVE DOMAIN::HEPHAESTUS[tool_crafting]⊕HERMES[automation]
§1::PURPOSE
Enable automated access to Vercel protected preview deployments for CI/CD, UI validation, and E2E testing
§2::PROTECTION_BYPASS_PATTERN
METHOD::Protection_Bypass_for_Automation
SECRET_NAME::VERCEL_AUTOMATION_BYPASS_SECRET
SECRET_LOCATIONS::[
vercel_dashboard::"Project Settings -> Deployment Protection -> Auto-injected",
github_secrets::"Repository Settings -> Secrets -> Actions",
local_dev::".env.local[GITIGNORED]"
]
ACCESS_METHODS::[
HTTP_HEADER::"x-vercel-protection-bypass: ${VERCEL_AUTOMATION_BYPASS_SECRET}",
QUERY_PARAM::"?x-vercel-protection-bypass=${VERCEL_AUTOMATION_BYPASS_SECRET}"
]
§3::CI_WORKFLOW_INTEGRATION
§4::GITHUB_ACTIONS_PATTERN
# .github/workflows/ci.yml
jobs:
integration-tests:
runs-on: ubuntu-latest
steps:
- name: Wait for Vercel Preview
uses: patrickedqvist/wait-for-vercel-preview@v1.3.1
id: vercel
with:
token: ${{ secrets.GITHUB_TOKEN }}
max_timeout: 300
- name: Run E2E Tests
env:
VERCEL_PREVIEW_URL: ${{ steps.vercel.outputs.url }}
VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
run: npm run test:e2e
§5::PLAYWRIGHT_CONFIGURATION
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
baseURL: process.env.VERCEL_PREVIEW_URL,
extraHTTPHeaders: {
'x-vercel-protection-bypass': process.env.VERCEL_AUTOMATION_BYPASS_SECRET || '',
},
},
});
§6::CHROME_DEVTOOLS_MCP_ACCESS
CHROME_DEVTOOLS_PATTERN::[
// Navigate with bypass query param
mcp__chrome-devtools__navigate_page(
url: "${VERCEL_PREVIEW_URL}?x-vercel-protection-bypass=${SECRET}"
),
// OR set header via evaluate_script before navigation
mcp__chrome-devtools__evaluate_script(
function: "() => { /* custom fetch with header */ }"
)
]
§7::SETUP_CHECKLIST
PREREQUISITES::[
1::vercel_pro_plan_or_higher[automation_bypass_is_paid_feature],
2::deployment_protection_enabled[Project_Settings->Deployment_Protection],
3::automation_bypass_generated[generates_VERCEL_AUTOMATION_BYPASS_SECRET]
]
CONFIGURATION::[
1::add_to_github_secrets[repository_settings->secrets->actions],
2::add_to_local_env[.env.local_for_local_testing],
3::update_ci_workflow[pass_secret_to_test_steps],
4::configure_playwright[extraHTTPHeaders_or_query_param],
5::verify_access[curl_with_header_returns_200]
]
VERIFICATION_COMMAND::
curl -I -H "x-vercel-protection-bypass: $VERCEL_AUTOMATION_BYPASS_SECRET" \
https://your-preview-url.vercel.app
# Should return 200, not 401/403
§8::SECURITY_CONSIDERATIONS
NEVER::[
commit_secret_to_git,
log_secret_in_CI_output,
share_secret_in_documentation,
use_secret_in_client_side_code
]
ALWAYS::[
use_github_secrets_for_CI,
use_gitignored_.env.local_for_local,
rotate_if_exposed,
limit_to_preview_deployments[not_production]
]
ROTATION::[
location::"Vercel Dashboard -> Project -> Settings -> Deployment Protection",
action::"Regenerate secret",
update::"GitHub Secrets + local .env.local"
]
§9::TROUBLESHOOTING
ISSUE::401_Unauthorized_despite_bypass[
CHECK::[
secret_correct_and_not_stale,
header_name_exact["x-vercel-protection-bypass"],
secret_passed_to_env_in_CI,
not_trying_production_URL[bypass_for_previews_only]
]
]
ISSUE::Preview_not_found[
CHECK::[
PR_created_and_pushed,
vercel_integration_enabled,
wait_for_deployment_complete[use_wait-for-vercel-preview_action]
]
]
ISSUE::Bypass_not_available[
CHECK::[
vercel_plan[Pro_or_higher_required],
deployment_protection_enabled_first,
feature_may_require_team_admin
]
]
§10::AGENT_INTEGRATION
UI_VALIDATOR_USAGE::[
RECEIVES::[preview_url, acceptance_criteria],
ACCESSES::preview_via_bypass_header,
VALIDATES::visual+functional_requirements,
RETURNS::PASS/FAIL+evidence
]
CI_PIPELINE_USAGE::[
TIER_1::quality_gates[no_preview_needed],
TIER_2::preview_integration[uses_bypass_for_E2E],
PATTERN::wait_for_preview->export_url->run_tests_with_bypass
]
§11::INTEGRATION
RELATED_SKILLS::[test-ci-pipeline, test-infrastructure, supabase-test-harness] WISDOMS::[ "Automation_bypass_enables_E2E_testing_without_manual_intervention", "Gradual_skip_prevents_false_failures_on_missing_previews", "Secrets_must_never_leak_into_logs_or_code" ]
===END===