Criar uma ação JavaScript

Neste guia, você aprenderá como criar uma ação JavaScript usando o conjunto de ferramentas de ações.

GitHub Actions está disponível com GitHub Free, GitHub Pro, GitHub Free para organizações, GitHub Team, GitHub Enterprise Cloud e GitHub AE. GitHub Actions não está disponível para repositórios privados pertencentes a contas usando os planos de legado por repositório.

Observação: Executores hospedados em GitHub não são atualmente compatíveis com GitHub Enterprise Server. Você pode ver mais informações sobre suporte futuro planejado no Itinerário público do GitHub.

Introdução

Neste guia, você aprenderá os componentes básicos necessários para criar e usar uma ação JavaScript empacotada. Para manter o foco deste guia nos componentes necessários para empacotar a ação, a funcionalidade do código da ação é mínima. A ação imprime "Olá, mundo" nos registros ou "Olá, [who-to-greet]", se você fornecer um nome personalizado.

Este guia usa o módulo Node.js do kit de ferramentas GitHub Actions para acelerar o desenvolvimento. Para obter mais informações, consulte o repositório ações/conjuntos de ferramentas.

Ao terminar esse projeto, você entenderá como criar sua própria ação JavaScript e poderá testá-la em um fluxo de trabalho.

Para garantir que suas ações de JavaScript sejam compatíveis com todos os executores hospedados no GitHub (Ubuntu, Windows e macOS), o código JavaScript empacotado que você escreve deve ser JavaScript puro e não depender de outros binários. As ações JavaScript são realizadas diretamente no executor e usam binários que já existem no ambiente virtual.

Warning: When creating workflows and actions, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see "Understanding the risk of script injections."

Pré-requisitos

Before you begin, you'll need to download Node.js and create a public GitHub repository.

  1. Baixe e instale o Node.js, que inclui npm.

    https://nodejs.org/en/download/current/

  2. Create a new public repository on sua instância do GitHub Enterprise Server and call it "hello-world-javascript-action". Para obter mais informações, consulte "Criar um repositório novo".

  3. Clone o repositório para seu computador. Para obter mais informações, consulte "Clonar um repositório".

  4. No seu terminal, mude os diretórios para seu novo repositório.

    cd hello-world-javascript-action
  5. From your terminal, initialize the directory with npm to generate a package.json file.

    npm init -y

Criar um arquivo de metadados de ação

Create a new file named action.yml in the hello-world-javascript-action directory with the following example code. Para obter mais informações, consulte "Sintaxe dos metadados para GitHub Actions}."

name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id da entrada
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id da saída
    description: 'The time we greeted you'
runs:
  using: 'node12'
  main: 'index.js'

Esse arquivo define a entrada who-to-greet e a saída time. O arquivo também diz ao executor da ação como começar a executar essa ação JavaScript.

Adicionar pacotes do kit de ferramenta de ações

O conjunto de ferramentas de ações é uma coleção de pacotes Node.js que permite a rápida criação de ações JavaScript com mais consistência.

O pacote do kit de ferramentas @actions/core fornece uma interface com os comandos do fluxo de trabalho, variáveis de entrada e saída, status de saída e mensagens de depuração.

O conjunto de ferramentas também oferece um pacote @actions/github que retorna um cliente REST Octokit autenticado e acesso aos contexto do GitHub Actions.

O conjunto de ferramentas oferece mais do que pacotes core and github. Para obter mais informações, consulte o repositório ações/conjuntos de ferramentas.

No seu terminal, instale os pacotes de conjunto de ferramentas de ações core e github.

npm install @actions/core
npm install @actions/github

Você pode ver agora um diretório node_modules com três módulos recém-instalados e um arquivo package-lock.json com as dependências do módulo instalado e as versões de cada módulo instalado.

Gravar um código de ação

Esta ação usa o conjunto de ferramentas para obter a variável de entrada obrigatória who-to-greet no arquivo de metadados da ação e imprime "Hello [who-to-greet]" em uma mensagem de depuração no log. Na sequência, o script obtém a hora atual e a configura como uma variável de saída que pode ser usada pelas ações executadas posteriormente em um trabalho.

O GitHub Actions fornece informações de contexto sobre o evento webhook, Git refs, fluxo de trabalho, ação e a pessoa que acionou o fluxo de trabalho. Para acessar as informações de contexto, você pode usar o pacote github. A ação que você vai escrever imprimirá a carga do evento webhook no log.

Adicione um arquivo novo denominado index.js, com o seguinte código:

const core = require('@actions/core');
const github = require('@actions/github');

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);
  // Get the JSON webhook payload for the event that triggered the workflow
  const payload = JSON.stringify(github.context.payload, undefined, 2)
  console.log(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

Se um erro for lançado no exemplo index.js acima, core.setFailed(error.message); usará o pacote do conjunto de ferramentas de ações @actions/core para registrar uma mensagem em log e definir um código de saída de falha. Para obter mais informações, consulte "Definindo os códigos de saída para as ações".

Criar README

Para que as pessoas saibam como usar sua ação, você pode criar um arquivo README. Um arquivo README é útil quando você planeja compartilhar publicamente sua ação, mas também é uma ótima maneira de lembrá-lo ou sua equipe sobre como usar a ação.

No diretório hello-world-javascript-action, crie um arquivo README.md que especifica as seguintes informações:

  • Descrição detalhada do que a ação faz;
  • Argumentos obrigatórios de entrada e saída;
  • Argumentos opcionais de entrada e saída;
  • Segredos usados pela ação;
  • Variáveis de ambiente usadas pela ação;
  • Um exemplo de uso da ação no fluxo de trabalho.
# Hello world javascript action

Esta ação imprime "Hello World" ou "Hello" + o nome de uma pessoa a ser cumprimentada no log.

## Inputs

### `who-to-greet`

**Obrigatório** O nome da pessoa a quem cumprimentar. Padrão `"World"`.

## Outputs

### `time`

Horário que cumprimentamos você.

## Exemplo de uso

usa: ações/hello-world-javascript-action@v1.1
com:
  quem cumprimentar: 'Mona, a Octocat'

Commit, tag e push de ação para o GitHub

O GitHub Enterprise Server faz o download de cada ação executada em um fluxo de trabalho durante o tempo de execução e executa-a como um pacote completo do código antes de você poder usar os comandos do fluxo de trabalho como, por exemplo, executar para interagir com a máquina executora. Isso significa que você deve incluir quaisquer dependências de pacotes necessárias para executar o código JavaScript. Você precisará verificar os pacotes de conjuntos de ferramentas core e github no repositório de ação.

No seu terminal, faça commit dos arquivos action.yml, index.js, node_modules, package.json, package-lock.json e README.md. Se você adicionar um arquivo .gitignore que lista node_modules, será necessário remover essa linha para fazer commit do diretório node_modules.

Adicionar uma tag da versão para versões da sua ação é considerada uma prática recomendada. Para obter mais informações sobre versões da sua ação, consulte "Sobre ações".

git add action.yml index.js node_modules/* package.json package-lock.json README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1.1
git push --follow-tags

Verificar seu diretório node_modules pode causar problemas. Como alternativa, você pode usar uma ferramenta denominada @vercel/ncc para compilar o seu código e módulos em um arquivo usado para distribuição.

  1. Instale o vercel/ncc executando este comando no seu terminal. npm i -g @vercel/ncc

  2. Compile seu arquivo index.js. ncc build index.js --license licenses.txt

    Você verá um novo arquivo dist/index.js com seu código e os módulos compilados. Você também verá um arquivo que acompanha dist/licenses.txt e contém todas as licenças dos node_modules que você está usando.

  3. Altere a palavra-chave main (principal) no arquivo action.yml para usar o novo arquivo dist/index.js. main: 'dist/index.js'

  4. Se você já verificou o diretório node_modules, remova-o. rm -rf node_modules/*

  5. No seu terminal, faça commit das atualizações para os arquivos action.yml, dist/index.js e node_modules.

    git add action.yml dist/index.js node_modules/*
    git commit -m "Use vercel/ncc"
    git tag -a -m "My first action release" v1.1
    git push --follow-tags

Testar sua ação em um fluxo de trabalho

Agora você está pronto para testar sua ação em um fluxo de trabalho. Quando uma ação está em um repositório privado, a ação somente pode ser usada em fluxos de trabalho no mesmo repositório. Ações públicas podem ser usadas por fluxos de trabalho em qualquer repositório.

Observação: GitHub Actions em sua instância do GitHub Enterprise Server pode ter acesso limitado a ações em GitHub.com ou GitHub Marketplace. Para obter mais informações, consulte "Comunicação entre os executores auto-hospedados e GitHub".

Exemplo usando uma ação pública

This example demonstrates how your new public action can be run from within an external repository.

Copy the following YAML into a new file at .github/workflows/main.yml, and update the uses: octocat/hello-world-javascript-action@v1.1 line with your username and the name of the public repository you created above. Você também pode substituir a entrada who-to-greet pelo seu nome.

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - name: Hello world action step
        id: hello
        uses: octocat/hello-world-javascript-action@v1.1
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

When this workflow is triggered, the runner will download the hello-world-javascript-action action from your public repository and then execute it.

Exemplo usando uma ação privada

Copie o código do fluxo de trabalho em um arquivo .github/workflows/main.yml no repositório da ação. Você também pode substituir a entrada who-to-greet pelo seu nome.

.github/workflows/main.yml

em: [push]

trabalhos:
  hello_world_job:
    runs-on: ubuntu-latest
    nome: Um trabalho para dizer "Olá"
    etapas:
      # Para usar a ação privada desse repositório,
      # você deve verificar o repositório
      - nome: Checkout
        usa: actions/checkout@v2
      - nome: Etapa da ação "Olá, mundo"
        usa: ./ # Usa uma ação no diretório-raiz
        id: olá
        com:
          who-to-greet: 'Mona the Octocat'
      # Usa a saída da etapa `hello`
      - nome: Obtém o tempo de saída
        executar: echo "O tempo foi ${{ steps.hello.outputs.time }}"

No seu repositório, clique na aba Ações e selecione a última execução do fluxo de trabalho. Você deverá ver "Hello Mona the Octocat" ou o nome que você usou como entrada em who-to-greet e o horário impresso no log.

Uma captura de tela de sua ação em um fluxo de trabalho

Esse documento ajudou você?Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.