O que é o GitHub Script?

8 minutos

Aqui, discutiremos como o Script do GitHub permite automatizar processos comuns do GitHub usando fluxos de trabalho do GitHub Actions.

O que é o GitHub Script?

GitHub Script é uma ação que fornece um cliente octokit autenticado e permite que o JavaScript seja escrito diretamente em um arquivo de fluxo de trabalho. É executado no Node.js, por isso tem as ferramentas avançadas dessa plataforma à sua disposição ao escrever scripts.

O que é o octokit?

O octokit é a coleção oficial de clientes da API do GitHub. Um destes clientes (rest.js) fornece acesso ao JavaScript para a interface REST do GitHub.

Você sempre foi capaz de automatizar a API do GitHub via octokit/rest.js, embora possa ser uma tarefa difícil configurar e manter corretamente. Uma das maiores vantagens na utilização do GitHub Script é que este processa toda esta sobrecarga para que o utilizador possa começar a utilizar a API de imediato. Não precisa de se preocupar com as dependências, configuração ou até a autenticação.

O que pode fazer o octokit/rest.js?

A resposta mais curta é que pode fazer virtualmente tudo o que diz respeito à automatização do GitHub. Não só tem acesso a consolidações, pedidos Pull e problema, mas também tem acesso a utilizadores, projetos e organizações. Você pode recuperar listas de arquivos comumente usados, como licenças ou .gitignore arquivos populares. Também pode compor Markdown.

Se você está construindo algo que integra o GitHub, as chances são boas de que você encontrará o que está procurando na documentação completa do octokit/rest.js.

Em que é que a utilização do GitHub Script é diferente do octokit/rest.js?

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

Por isso, em vez de:

octokit.issues.createComment({

Você usaria:

github.issues.createComment({

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

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 utiliza o GitHub Script

As ações do GitHub Script podem ser incluídas num fluxo de trabalho tal como qualquer outra ação. Assim, pode misturá-las com fluxos de trabalho existentes, como os que possa já ter configurado para CI/CD. Para ilustrar sua conveniência, agora vamos construir um fluxo de trabalho completo que usa o Script GitHub para postar automaticamente um comentário para todos os problemas recém-criados.

Começaremos com uma name cláusula e uma 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 roda no Linux com uma série de etapas.

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

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

      - 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 o GitHub Actions pode realmente ajudar a automatizar os eventos que ocorrem em seus repositórios. Imagine que um visitante do repositório abriu uma nova edição contendo informações sobre um bug crítico. Você pode querer agradecer-lhes por trazer isso à sua atenção; No entanto, esta tarefa simples pode tornar-se esmagadora à medida que o seu repositório atrai mais visitantes. Ao automatizar um comentário de problema, você pode automatizar o processo de agradecer aos visitantes todas as vezes.

Usando ações/github-script@0.8.0

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

Essa ação requer um github-token que é fornecido em tempo de execução para que as solicitações sejam autenticadas. Isto será efetuado automaticamente, para que possa utilizar o código como está.

O script parâmetro pode ser praticamente qualquer JavaScript que use o cliente octokit/rest/js armazenado no github. Neste caso, é só uma linha (dividida em múltiplas linhas para melhor legibilidade) que cria um comentário codificado.

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

Captura de tela de um fluxo de trabalho concluído usando o script GitHub.

Execução a partir de um ficheiro separado

Às vezes, você pode precisar usar um código significativo para preencher seu cenário de script do GitHub. Quando isso acontece, pode manter o script num ficheiro separado e consultá-lo a partir do fluxo de trabalho, em vez de colocar todo o script inline.

Aqui está 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}))

Veja mais exemplos do GitHub Script.

O que é o GitHub Script?