O que é o GitHub Script?

8 minutos

Aqui, discutimos como o GitHub Script permite automatizar processos comuns do GitHub com os fluxos de trabalho do GitHub Actions.

O que é o GitHub Script?

GitHub Script é uma ação que fornece um cliente octokit autenticado e permite escrever em JavaScript diretamente em um arquivo de fluxo de trabalho. Ele é executado no Node.js, então você pode usar a eficiência dessa plataforma ao escrever scripts.

O que é o octokit?

O octokit é a coleção oficial de clientes para a API do GitHub. Um desses clientes, rest.js, dá acesso JavaScript à interface REST do GitHub.

Você sempre conseguiu automatizar a API do GitHub via octokit/rest.js, embora possa ser uma tarefa difícil configurar e manter corretamente. Uma das grandes vantagens de usar o GitHub Script é que ele processa toda essa sobrecarga para que você possa começar a usar a API imediatamente. Você não precisa se preocupar com dependências, configurações ou até mesmo autenticação.

O que o octokit/rest.js faz?

A resposta mais simples é "praticamente qualquer coisa em relação à automação do GitHub". Você não só tem acesso a confirmações, solicitações de pull e problemas, mas também tem acesso a usuários, projetos e organizações. É possível recuperar listas de arquivos comumente usados, como licenças populares ou arquivos .gitignore. Você pode até mesmo renderizar o Markdown.

Se estiver criando algo que se integra ao GitHub, você terá boas chances de encontrar o que precisa na documentação completa do octokit/rest.js.

O uso do GitHub Script é diferente do octokit/rest.js?

A principal diferença de uso é que o GitHub Script fornece um cliente octokit/rest.js pré-autenticado de nome github.

Então, em vez de:

octokit.issues.createComment({

Você usaria:

github.issues.createComment({

Além da variável github, as seguintes variáveis também são fornecidas:

context é um objeto que contém o contexto da execução do fluxo de trabalho.
core é uma referência ao pacote @actions/core.
io é uma referência ao pacote @actions/io.

Criar um fluxo de trabalho que usa o GitHub Script

As ações do GitHub Script se encaixam em um fluxo de trabalho como qualquer outra ação. Como resultado, você pode até mesmo combiná-los com fluxos de trabalho existentes, como aqueles que você já configurou para CI/CD. Para ilustrar essa praticidade, agora criaremos um fluxo de trabalho completo que usa o GitHub Script para postar automaticamente um comentário em todos os problemas recém-criados.

Vamos começar com um name e uma cláusula on que especifica que esse fluxo de trabalho é executado quando os problemas são abertos.

name: Learning GitHub Script

on:
  issues:
    types: [opened]

Em seguida, definiremos um trabalho chamado comment que é executado no Linux com uma série de etapas.

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:

Nesse caso, há apenas uma etapa: a ação do GitHub Script.

      - uses: actions/github-script@0.8.0
        with:
          github-token: ${{secrets.GITHUB_TOKEN}}
          script: |
            github.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: "🎉 You've created this issue comment using GitHub Script!!!"
            })

Usar GitHub Actions realmente pode ajudar a automatizar os eventos que ocorrem em seus repositórios. Imagine que um visitante do repositório abriu um novo problema contendo informações sobre um bug crítico. Pode ser interessante agradecer por isso ter sido trazido à sua atenção; no entanto, essa tarefa simples pode se tornar insuportável à medida que o repositório atraia mais visitantes. Ao automatizar um comentário de problema, você pode automatizar o processo de agradecimento de visitantes todas as vezes.

Usando actions/github-script@0.8.0

A ação actions/github-script@0.8.0, também conhecida como GitHub Script, faz todo o trabalho pesado para a integração com a API do GitHub.

Essa ação requer um github-token fornecido no runtime para que as solicitações sejam autenticadas. Isso é feito automaticamente para que você possa usar esse código no estado em que se encontra.

O parâmetro script pode ser praticamente qualquer JavaScript que usa o cliente octokit/rest/js armazenado em github. Nesse caso, é apenas uma linha (dividida em várias linhas para facilitar a leitura) que cria um comentário codificado.

Depois que o fluxo de trabalho é executado, o GitHub Script registra o código executado para revisão na guia Ações.

Captura de tela de um fluxo de trabalho concluído com o GitHub Script.

Executar em um arquivo separado

Às vezes pode ser necessário usar um código significativo para atender ao cenário do GitHub Script. Quando isso acontece, você pode manter o script em um arquivo separado e fazer referência a ele no fluxo de trabalho em vez de colocar todo o script embutido.

Veja um exemplo de um fluxo de trabalho simples que faz isso:

on: push

jobs:
  echo-input:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/github-script@v2
        with:
          script: |
            const path = require('path')
            const scriptPath = path.resolve('./path/to/script.js')
            console.log(require(scriptPath)({context}))

Confira mais exemplos do GitHub Script.

O que é o GitHub Script?