Choose a starting point

The standalone example is restricted to reviewed, non-synthetic development clips which are not made for kids. Its category/audience declarations are not suitable defaults for arbitrary videos. Change them only with accurate owner-reviewed content declarations and corresponding tests.

Record these choices before creating persistent access:

Google project:       <GOOGLE_PROJECT_ID>
Owning Google account:<OWNER_ACCOUNT>              (keep private)
Channel:              <CHANNEL_HANDLE> / <CHANNEL_ID>
Repository:           <OWNER>/<REPOSITORY>
Default branch:       <DEFAULT_BRANCH>
Protected environment:<ENVIRONMENT>, e.g. youtube-upload
Required reviewer:    <OWNER_GITHUB_LOGIN>
Visibility policy:    unlisted OR public, explicitly approved

An unlisted link can be shared by anyone who has it. Public uploads are also discoverable. Pin the selected privacy policy in trusted code/approval; do not allow an untrusted artifact to choose it. Do not change older videos' visibility.

1. Prepare and pin the dependency

In your consumer repository , create a separate project directory (these are Bash commands). Resolve dependencies locally, review the lock, then commit both files. No grant or upload occurs here.

mkdir -p tools/youtube
cd tools/youtube
composer init --name=example/reviewed-youtube-uploader \
  --description='Reviewed manual video uploader' --license=proprietary --no-interaction
composer config repositories.youtubephp vcs https://github.com/Valgorithms/YoutubePHP
composer config minimum-stability dev
composer config prefer-stable true
composer config allow-plugins false
composer config platform.php 8.4.0
composer require --no-interaction --no-scripts --no-plugins \
  'vzgcoders/youtubephp:dev-main#7ce9b24eb26a32af7ffcd4936d8083c06a428fb0'
composer validate

Choose the package name/license for your consumer; proprietary above is an illustrative application license, not a change to YouTubePHP's MIT license. The exact commit is the version tested in the case study, not a recommendation to ignore later fixes. Composer warns about the intentional commit-ref constraint (validate --strict therefore exits nonzero); the normal validate command still checks the schema. Review both the pinned source and the lock's resolved transitive references . Do not use global path overrides when generating a portable consumer lock. A library checkout ignores its own composer.lock ; your consumer application should commit its lock. CI installs it, never runs composer update :

composer install --working-dir=tools/youtube --no-dev --no-interaction \
  --no-scripts --no-plugins --prefer-dist --no-progress

Use PHP 8.4+, JSON and mbstring. At this pin, media is read completely into memory and sent in one multipart request ; resumable upload is not implemented. Cap clips before PHP starts; the example uses 32 MiB. Use a bounded process/job timeout and enough memory for the file and multipart copy (Civ13 uses 256 MiB).

2. Google project, consent and channel

In the approved project in Google Cloud Console:

1. Enable YouTube Data API v3 . An API key or service account does not replace the channel owner's OAuth grant.
2. Configure Google Auth Platform branding/support/contact details. For an initial owner-only test, choose External / Testing , and add the owning Google account under Test users . A pre-existing test-user entry need not be duplicated.

3. Add exactly these complete scope URLs in Data Access:

   https://www.googleapis.com/auth/youtube.upload
   https://www.googleapis.com/auth/youtube.readonly
   

   youtube.upload is the minimum insertion scope. The separate youtube.readonly scope allows channels.list(mine=true) and owner videos.list status/processing readback; upload alone is absent from those methods' allowed scope lists in API discovery. Do not silently substitute the much broader youtube , force-ssl or partner scopes. Reject a missing or expanded returned grant rather than guessing.

4. Create a Desktop app OAuth client. For an assistant-operated automated client, follow Google's AI-powered client declaration when offered; it adds no scope. Do not reuse an agent-only client for a future mixed human/agent application without reviewing Google's requirements.
5. Keep downloaded client JSON in a private local folder outside repositories, synced/shared folders and chat. Use restrictive file permissions. The local setup process must not display or log the JSON, token response or client secret.

Choose the Brand channel , if applicable, during the owner's Google sign-in. An account email, channel display name or remembered handle is not proof of the destination. Resolve and approve its immutable UC... channel ID, then require the same grant's channels.list(part:'id', mine:true) to return exactly that ID before inserting media. A wrong channel stops; never switch accounts automatically.

3. Configure the protected GitHub environment

In the consumer repository's Settings → Environments, create <ENVIRONMENT> :

• Require the named human owner as reviewer. Explicitly choose whether the owner may review their own dispatch; Civ13 allows self-review, while retaining the required approval step. Confirm your GitHub plan supports the desired protections.
• Disable administrator bypass. Restrict deployment branches to only the actual default branch, using an explicit branch rule. Protect that branch.
• Store exactly YOUTUBE_CLIENT_ID , YOUTUBE_CLIENT_SECRET , YOUTUBE_REFRESH_TOKEN as environment secrets . Do not move them to repository/organization scope to fix propagation. Inspection and PR jobs must not receive them.

• Keep repository and environment variables explicitly disabled:

  YOUTUBE_UPLOAD_ENABLED=false
  YOUTUBE_UPLOAD_STOP_USE=true
  YOUTUBE_ZERO_COST_CONFIRMED=false
  

Do not enable uploads during credential setup. Store/rotation approval is separate from clip approval or source PR approval. A three-secret write is not atomic: GitHub cannot return old values for rollback. An interrupted/uncertain placement needs owner reconciliation and uploads must remain disabled. Never knowingly overwrite an existing grant as an incidental setup retry.

name: Reviewed YouTube upload
on:
  workflow_dispatch:
    inputs:
      execute_upload:
        type: boolean
        default: false
        description: Insert the separately approved clip after inspection
permissions:
  contents: read
  actions: read
  issues: read
  pull-requests: read
jobs:
  upload:
    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
    uses: ./.github/workflows/youtube-upload-worker.yml
    with:
      execute_upload: ${{ inputs.execute_upload }}
    secrets:
      YOUTUBE_CLIENT_ID: ${{ secrets.YOUTUBE_CLIENT_ID }}
      YOUTUBE_CLIENT_SECRET: ${{ secrets.YOUTUBE_CLIENT_SECRET }}
      YOUTUBE_REFRESH_TOKEN: ${{ secrets.YOUTUBE_REFRESH_TOKEN }}

name: Trusted YouTube worker
on:
  workflow_call:
    inputs:
      execute_upload:
        type: boolean
        required: true
    secrets:
      YOUTUBE_CLIENT_ID:
        required: true
      YOUTUBE_CLIENT_SECRET:
        required: true
      YOUTUBE_REFRESH_TOKEN:
        required: true
permissions:
  contents: read
  actions: read
  issues: read
  pull-requests: read
concurrency:
  group: youtube-destination-upload
  cancel-in-progress: false
jobs:
  inspect:
    if: >-
      github.event_name == 'workflow_dispatch' &&
      github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          ref: ${{ github.sha }}
          persist-credentials: false
      - uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
        with:
          php-version: '8.4'
          extensions: mbstring
          coverage: none
          tools: composer:2.9.8
      - run: php tools/youtube/repository-uploader.php inspect
        env:
          GH_TOKEN: ${{ github.token }}
  upload:
    needs: inspect
    if: >-
      inputs.execute_upload && vars.YOUTUBE_UPLOAD_ENABLED == 'true' &&
      vars.YOUTUBE_UPLOAD_STOP_USE == 'false' && vars.YOUTUBE_ZERO_COST_CONFIRMED == 'true'
    environment: youtube-upload
    runs-on: ubuntu-24.04
    timeout-minutes: 8
    # If your durable journal uses GitHub Contents, grant contents:write HERE
    # AND in the caller. A callee cannot elevate a read-only caller token.
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          ref: ${{ github.sha }}
          persist-credentials: false
      - uses: shivammathur/setup-php@db91e1a0e48e84637d325a7ee4d2677e146ceec4 # 2.36.0
        with:
          php-version: '8.4'
          extensions: mbstring
          coverage: none
          tools: composer:2.9.8
      - run: >-
          composer install --working-dir=tools/youtube --no-dev --no-interaction
          --no-scripts --no-plugins --prefer-dist --no-progress
      - name: Upload using trusted controller and protected environment
        run: php -d display_errors=0 -d memory_limit=256M tools/youtube/repository-uploader.php upload
        env:
          GH_TOKEN: ${{ github.token }}
          YOUTUBE_CLIENT_ID: ${{ secrets.YOUTUBE_CLIENT_ID }}
          YOUTUBE_CLIENT_SECRET: ${{ secrets.YOUTUBE_CLIENT_SECRET }}
          YOUTUBE_REFRESH_TOKEN: ${{ secrets.YOUTUBE_REFRESH_TOKEN }}
          YOUTUBE_UPLOAD_ENABLED: ${{ vars.YOUTUBE_UPLOAD_ENABLED }}
          YOUTUBE_UPLOAD_STOP_USE: ${{ vars.YOUTUBE_UPLOAD_STOP_USE }}
          YOUTUBE_ZERO_COST_CONFIRMED: ${{ vars.YOUTUBE_ZERO_COST_CONFIRMED }}

4. Implement the trusted controller, then connect the API calls

repository-uploader.php is code you review and commit in the consumer. It must support inspect (no YouTube secrets or OAuth) and upload , with these contracts:

1. Read only a reviewed policy/manifest in the trusted default-branch revision. Validate its bounded schema, exact channel/privacy, media SHA256, title, description, audience/content declaration, tested commit and named human approval. Bind approval to those exact fields; a changed file or metadata invalidates approval. A default execute_upload=false is not content approval.
2. Prove the source run/artifact belongs to the expected repository IDs, workflow ID/path, event/branch, exact tested revision and successful attempt. Check PR association, artifact ID/name/size/digest/expiry and creation during that attempt. Never check out or execute producer/PR scripts in the secret-bearing job. Separate original recording/game revision from a later trusted packaging run.
3. Download bounded bytes using credential-free signed redirects, check archive and media hashes, reject traversal/symlinks/encrypted/extra entries, and probe MIME/header/codec/duration/dimensions without upload secrets . A hash is consistency evidence, not gameplay or publication approval. Revalidate trusted provenance/approval and identical media bytes in the upload job, without decoding media there. Use a fixed size/content policy, not artifact-provided limits.
4. Enforce disabled gates, default-branch/manual-only eligibility, destination-wide concurrency, a small daily upload cap, zero-cost budget and nonempty credentials. Treat auth/rate/quota errors as stop-use. Never print raw exceptions, auth headers, tokens, signed artifact URLs, media or OAuth response bodies.
5. Load the durable journal and block any existing destination+media SHA record across manifests, commits and one-off tools. Use a shared persistent store, not a runner file, cache or expiring artifact. Import known prior attempts first. For a small GitHub Contents journal, use a separate data-only branch and compare-and-swap the current file SHA. contents:write is repository-wide, so protect the default branch and document this privilege. It is not needed for inspection or a journal stored through a different approved mechanism.
6. Commit reserved before videos.insert . If reservation persistence is failed/uncertain, send no media. Persist returned ID as uploaded before readback; only mark verified after exact channel/privacy and successful processing. Receipt fields should contain public IDs/hashes/provenance, no auth. Do not delete dedup history to fit a cap; stop for reviewed maintenance.
7. Bound polling (for example 12 reads, ten seconds apart). If an ID exists, future attempts are verify-only , including after artifact expiry. If insert/ID persistence is uncertain, stop retries and retain the reservation. An empty uploads playlist does not prove no incomplete Studio draft exists; API inventory may not expose every draft. Reconcile with owner evidence, never another insert, credential/client switch or automated account selection.

The example's reserve(channel, sha) callback must atomically reject an existing record and confirm a persistent write before returning true . Its saveId(id) callback must confirm another persistent write. These are integration hooks, not in-memory booleans. The example does not itself mark a receipt verified.

Here is the actual library connection pattern, inside that trusted controller:

use YouTube\Auth\OAuth;
use YouTube\Examples\ReviewedUpload;
use YouTube\Examples\SingleInsertDriver;
use YouTube\Http\Drivers\React as ReactDriver;
use YouTube\YouTube;

// Require tools/youtube/vendor/autoload.php and your copied ReviewedUpload.php first.
// $loop is your React event loop; all three strings were preflighted, never logged.
$driver = new SingleInsertDriver(new ReactDriver($loop, [], 120.0));
$oauth = new OAuth($clientId, $clientSecret, $driver);
$session = $oauth->refreshToken($refreshToken)->then(function (array $grant) use ($driver, $loop) {
    $scopes = $grant['scope'] ?? [];
    sort($scopes);
    if ($scopes !== ReviewedUpload::SCOPES
        || strtolower($grant['token_type'] ?? '') !== 'bearer'
        || ! is_string($grant['access_token'] ?? null) || $grant['access_token'] === '') {
        throw new RuntimeException('Unexpected grant; stop without logging the response');
    }
    return new YouTube([
        'token' => $grant['access_token'],
        'scopes' => ReviewedUpload::SCOPES,
        'driver' => $driver,
        'loop' => $loop,
        // No token_store, device_prompt, refresh_token or automatic reauthorization.
    ]);
});

OAuth::refreshToken normalizes the returned scope string into an array. Chain your promise handling from $session and run/stop the event loop with a bounded deadline. Construct new ReviewedUpload($youtube) , call insert(...) with the approved file/metadata and the durable callbacks above, then poll verified($savedId, $channelId, $privacy) ; false means still processing and true permits the controller to persist verified . Close the client in cleanup. Catch errors at the CLI boundary with a fixed sanitized diagnostic, preserving the journal for reconciliation. Do not call YouTube::run() to start a bot loop.

At the tested pin, normal library behavior retries some POST failures (503/rate limits), and a client configured with refresh credentials may replay after 401. SingleInsertDriver is an example integration policy , not a changed library default: it allows only four fixed HTTPS endpoints, converts non-2xx/transport failures into a sanitized non-retryable error and rejects a second media insert. That per-process counter is insufficient across workflow reruns; the journal is still mandatory. Never retry an ambiguous media request just because a driver returned an error. Larger/resumable uploads need a separately reviewed implementation.

5. Validate, run once, and close the gates

In this library checkout, the example has offline tests using ScriptedDriver , not Google/network access. After installing the development dependencies:

php -l examples/ReviewedUpload.php
vendor/bin/phpunit --filter=ReviewedUploadTest

In a consumer, add tests for the full controller, durable-write ordering/failures, dedup across reruns, tampered provenance/approval, file caps/paths, scope/channel mismatch and no media requests on failure. Mocked API tests do not prove a real grant, channel ownership or publication. Lint the copied YAML with actionlint; keep setup/actions pinned and review lock changes separately.

For the first live check, inspect first with execute_upload=false . Confirm standard-runner/public-repository $0 eligibility and your existing account budget; private-repository allowances and environment features may differ. Use short artifact retention (e.g. one day), bounded file size, one clip per dispatch, job timeouts and a low daily cap. Do not add larger runners, paid services or unbounded video retention.

After a fresh exact-clip approval, open the repository and environment gates only for one bounded test: enabled=true, stop-use=false, zero-cost-confirmed=true. Dispatch the default-branch caller, then have the owner personally approve the protected job. A separate bounded monitor must reset both scopes to disabled on terminal state, failure, interruption or deadline and read back the result. always() inside a job cannot guarantee cleanup after cancellation, outage or runner loss. If monitoring disconnects, independently verify shutdown before claiming gates are closed. The templates do not install a watchdog for you.

Do not call an upload successful merely because the insert returned an ID or the Actions job completed. Verify that exact ID through owner API readback:

snippet.channelId == approved immutable channel
status.privacyStatus == approved public/unlisted policy
status.uploadStatus == processed
processingDetails.processingStatus == succeeded

Then persist the verified receipt and return https://www.youtube.com/watch?v=<ID> . A public/embeddable page or oEmbed response alone does not distinguish public from unlisted. notifySubscribers=false is an explicit request parameter, not a status field you can read back. Failed/mismatched/pending processing is not success and never authorizes a second insert.

Current Google limits and troubleshooting

Official documentation checked 2026-10-20 : videos.insert uses a separate Video Uploads bucket of 100 calls/day, at one unit per call, and says unverified API projects are not restricted to private viewing. Older guidance about 1,600 units/private-only uploads should not be copied as a current rule. Creator account settings, OAuth consent verification and actual project/account restrictions remain separate: always recheck current official docs and returned privacy. If Google returns private instead of the approved public/unlisted value, stop and resolve the applicable restriction with the owner; do not change clients or claim publication succeeded.

For the precise fixes behind the tested integration, see the Civ13 case study.