Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

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 is available with GitHub Free, GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub One. GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. For more information, see "GitHub's products."

Neste artigo

Introdução

In this guide, you'll learn about the basic components needed to create and use a packaged JavaScript action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name.

This guide uses the GitHub Actions Toolkit Node.js module to speed up development. 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.

To ensure your JavaScript actions are compatible with all GitHub-hosted runners (Ubuntu, Windows, and macOS), the packaged JavaScript code you write should be pure JavaScript and not rely on other binaries. JavaScript actions run directly on the runner and use binaries that already exist in the virtual environment.

Self-hosted runners must have Node.js installed to run JavaScript actions. For more information about the requirements of self-hosted runners, see "About self-hosted runners."

Pré-requisitos

Antes de começar, você precisa baixar o Node.js e criar um repositório GitHub.

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

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

  2. Crie um repositório novo no GitHub. Você pode escolher qualquer nome para o repositório ou usar "hello-world-javascript-action", como nesse exemplo. É possível adicionar esses arquivos após push do projeto no GitHub. 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. No terminal, inicialize o diretório com um arquivo package.json.

    npm init -y

Criar um arquivo de metadados de ação

Crie um arquivo action.yml no diretório hello-world-javascript-action com o código de exemplo a seguir.

action.yml

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 de conjuntos de ferramentas 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.

The toolkit @actions/core package provides an interface to the workflow commands, input and output variables, exit statuses, and debug messages.

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.

Escrever o código da 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:

index.js

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. For more information, see "Setting exit codes for actions."

Criar um LEIAME

Para que as pessoas saibam como usar sua ação, você pode criar um arquivo LEIAME. Um arquivo LEIAME é ú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.

README.md

# 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

uses: actions/hello-world-javascript-action@v1
with:
  who-to-greet: 'Mona the Octocat'

Commit, tag, and push your action to GitHub

GitHub downloads each action run in a workflow during runtime and executes it as a complete package of code before you can use workflow commands like run to interact with the runner machine. 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.

It's best practice to also add a version tag for releases of your action. For more information on versioning your action, see "About actions."

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
git push --follow-tags

Como uma alternativa para a verificação do diretório node_modules, você pode usar uma ferramenta chamada zeit/ncc para compilar seu código e módulos em um único arquivo usado para distribuição.

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

  2. Compile seu arquivo index.js. ncc build index.js

    Você verá um novo arquivo dist/index.js com seu código e os módulos compilados.

  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 zeit/ncc"
    git tag -a -m "My first action release" v1
    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.

Exemplo usando uma ação pública

O fluxo de trabalho a seguir usa a ação completa "hello world" no repositório actions/hello-world-javascript-action. Copie o código do fluxo de trabalho em um arquivo .github/workflows/main.yml, mas substitua o repositório actions/hello-world-javascript-action pelo repositório que você criou. Você também pode substituir a entrada who-to-greet pelo seu nome.

.github/workflows/main.yml

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: actions/hello-world-javascript-action@v1
      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 }}"

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

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      # To use this repository's private action, you must check out the repository
      - name: Checkout
        uses: actions/checkout@v2
      - name: Hello world action step
        uses: ./ # Uses an action in the root directory
        id: hello
        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 }}"

From your repository, click the Actions tab, and select the latest workflow run. 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

Pergunte a uma pessoa

Não consegue encontrar o que procura?

Entrar em contato