Por que montar esse pipeline vale o esforço

Como o pipeline funciona do início ao fim

Para quem esse sistema foi feito

Tutorial completo: configurando do zero

Passo 1 Estrutura do repositório no GitHub

Crie um repositório no GitHub (público ou privado) e organize assim:

meu-repo/
├─ render.py                       ← script principal
└─ .github/
   └─ workflows/
      └─ run_notebook.yml          ← workflow do GitHub Actions

Passo 2 Criar a Service Account no Google Cloud

A Service Account é usada para ler arquivos do Drive e acessar a planilha — ela não faz upload. Funciona como uma conta de robô sem interação humana:

1. Acesse o Google Cloud Console e crie ou selecione seu projeto.
2. Vá em APIs e Serviços → Biblioteca e ative a Google Drive API.
3. Ative também a Google Sheets API — sem ela a leitura da planilha falha com erro 403.
4. Vá em IAM → Contas de serviço → Criar conta de serviço. Dê um nome (ex: github-actions-drive).
5. Na aba Chaves, clique em Adicionar chave → JSON e salve o arquivo.
6. Compartilhe sua planilha com o email da Service Account (campo client_email no JSON) — papel Editor.
7. Compartilhe também a pasta raiz do Drive com esse mesmo email — papel Editor.

Passo 3 Criar o OAuth Client para upload no Drive

Service Accounts não têm cota de armazenamento — por isso o upload precisa usar suas credenciais pessoais via OAuth. Veja como configurar:

1. No Cloud Console → APIs e Serviços → Credenciais → Criar credencial → ID do cliente OAuth 2.0.
2. Tipo: Aplicativo de área de trabalho. Dê um nome e clique em Criar.
3. Anote o client_id e o client_secret exibidos.
4. Vá em Tela de permissão OAuth e configure o tipo como Externo.
5. Na aba Usuários de teste, clique em + Adicionar usuários e adicione seu email (ex: seuemail@gmail.com).
   
   
   ℹ️ Por que isso é necessário? Enquanto seu app OAuth estiver com status "Testando", o Google só permite que usuários explicitamente cadastrados na lista de teste consigam se autenticar. Se você pular essa etapa e tentar gerar o refresh token, vai receber um erro de acesso negado. O limite é de 100 usuários de teste — mais que suficiente para uso pessoal.

Passo 4 Gerar o refresh token com o setup_oauth.py

Rode este script uma única vez no seu computador local. Ele abre o navegador, você autoriza e ele imprime o refresh token:

pip install google-auth-oauthlib

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_ID     = "COLE_SEU_CLIENT_ID_AQUI"
CLIENT_SECRET = "COLE_SEU_CLIENT_SECRET_AQUI"

SCOPES = [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/spreadsheets",
]

client_config = {
    "installed": {
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob", "http://localhost"],
    }
}

flow  = InstalledAppFlow.from_client_config(client_config, SCOPES)
creds = flow.run_local_server(port=0)

print("OAUTH_CLIENT_ID     :", CLIENT_ID)
print("OAUTH_CLIENT_SECRET :", CLIENT_SECRET)
print("OAUTH_REFRESH_TOKEN :", creds.refresh_token)

O navegador vai abrir pedindo que você faça login com o email cadastrado como usuário de teste. Após aceitar, o terminal imprime os três valores.

Passo 5 Adicionar os Secrets no GitHub

Vá em Settings → Secrets and variables → Actions → New repository secret e adicione:

Passo 6 Workflow do GitHub Actions

Crie o arquivo .github/workflows/run_notebook.yml:

name: BVTK Render Engine

on:
  workflow_dispatch:            # botão Run workflow manual
  schedule:
    - cron: "0 * * * *"        # todo início de hora (UTC)

jobs:
  render:
    runs-on: ubuntu-latest
    timeout-minutes: 120

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Instalar ffmpeg
        run: sudo apt-get install -y ffmpeg

      - name: Instalar dependências Python
        run: |
          python -m pip install --upgrade pip
          pip install \
            gspread \
            google-api-python-client \
            google-auth \
            google-auth-oauthlib \
            google-auth-httplib2

      - name: Salvar credenciais Service Account
        run: echo '${{ secrets.GDRIVE_CREDENTIALS }}' > credentials.json

      - name: Executar render
        env:
          OAUTH_CLIENT_ID:     ${{ secrets.OAUTH_CLIENT_ID }}
          OAUTH_CLIENT_SECRET: ${{ secrets.OAUTH_CLIENT_SECRET }}
          OAUTH_REFRESH_TOKEN: ${{ secrets.OAUTH_REFRESH_TOKEN }}
        run: python render.py

      - name: Remover credenciais do disco
        if: always()
        run: rm -f credentials.json

Passo 7 Estrutura da planilha Google Sheets

A planilha tem duas abas. A aba config controla o trigger:

A aba videos lista os arquivos a processar:

Passo 8 Estrutura de pastas no Drive

pasta-raiz/                         ← FOLDER_ID no render.py
├─ videosx/                         ← assets de processamento
│    ├─ 16X9.mp4                    ← intro formato paisagem
│    ├─ 9X16.mp4                    ← intro formato retrato
│    ├─ 1X1.mp4                     ← intro formato quadrado
│    └─ WATERMARK.png               ← marca d'água (PNG com transparência)
├─ video1.mp4                       ← vídeos a processar
├─ video2.mp4
└─ video1_editado.mp4               ← resultado (criado pelo script)

Passo 9 Testando o workflow

1. Na planilha, aba config, célula B2: escreva rodar.
2. No GitHub → aba Actions → clique no workflow → Run workflow.
3. Acompanhe os logs em tempo real clicando na execução.
4. Ao terminar, os arquivos _editado.mp4 aparecem na pasta raiz do Drive e a planilha é atualizada.

Perguntas frequentes — erros que aparecem e como resolver

Esses são os erros reais que aparecem durante a configuração desse pipeline. Documentei cada um com a causa exata e a solução que funcionou.

Recursos e documentação oficial