Managing complex workflows

This guide shows you how to use the advanced features of GitHub Actions, with secret management, dependent jobs, caching, build matrices, environments, and labels.


This article describes some of the advanced features of GitHub Actions that help you create more complex workflows.

Storing secrets

If your workflows use sensitive data, such as passwords or certificates, you can save these in GitHub as secrets and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow.

This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.

    runs-on: ubuntu-latest
      - name: Retrieve secret
          super_secret: ${{ secrets.SUPERSECRET }}
        run: |
          example-command "$super_secret"

For more information, see "Creating and storing encrypted secrets."

Creating dependent jobs

By default, the jobs in your workflow all run in parallel at the same time. So if you have a job that must only run after another job has completed, you can use the needs keyword to create this dependency. If one of the jobs fails, all dependent jobs are skipped; however, if you need the jobs to continue, you can define this using the if conditional statement.

In this example, the setup, build, and test jobs run in series, with build and test being dependent on the successful completion of the job that precedes them:

    runs-on: ubuntu-latest
      - run: ./
    needs: setup
    runs-on: ubuntu-latest
      - run: ./
    needs: build
    runs-on: ubuntu-latest
      - run: ./

For more information, see jobs.<job_id>.needs.

Using a build matrix

You can use a build matrix if you want your workflow to run tests across multiple combinations of operating systems, platforms, and languages. The build matrix is created using the strategy keyword, which receives the build options as an array. For example, this build matrix will run the job multiple times, using different versions of Node.js:

    runs-on: ubuntu-latest
        node: [6, 8, 10]
      - uses: actions/setup-node@v2
          node-version: ${{ matrix.node }}

For more information, see jobs.<job_id>.strategy.matrix.

Caching dependencies

GitHub-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.

This example demonstrates how to cache the ~/.npm directory:

      - name: Cache node modules
        uses: actions/cache@v2
          cache-name: cache-node-modules
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-

For more information, see "Caching dependencies to speed up workflows."

Using databases and service containers

If your job requires a database or cache service, you can use the services keyword to create an ephemeral container to host the service; the resulting container is then available to all steps in that job and is removed when the job has completed. This example demonstrates how a job can use services to create a postgres container, and then use node to connect to the service.

    runs-on: ubuntu-latest
    container: node:10.18-jessie
        image: postgres
      - name: Check out repository code
        uses: actions/checkout@v2
      - name: Install dependencies
        run: npm ci
      - name: Connect to PostgreSQL
        run: node client.js
          POSTGRES_HOST: postgres
          POSTGRES_PORT: 5432

For more information, see "Using databases and service containers."

Using labels to route workflows

This feature helps you assign jobs to a specific hosted runner. If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner in addition to their default label of self-hosted. Then, you can refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way. GitHub-hosted runners have predefined labels assigned.

This example shows how a workflow can use labels to specify the required runner:

    runs-on: [self-hosted, linux, x64, gpu]

A workflow will only run on a runner that has all the labels in the runs-on array. The job will preferentially go to an idle self-hosted runner with the specified labels. If none are available and a GitHub-hosted runner with the specified labels exists, the job will go to a GitHub-hosted runner.

To learn more about self-hosted runner labels, see "Using labels with self-hosted runners." To learn more about GitHub-hosted runner labels, see "Supported runners and hardware resources".

Reutilizando fluxos de trabalho

Você pode chamar um fluxo de trabalho de dentro de outro fluxo de trabalho. Isso permite a reutilização de fluxos de trabalho, evitando duplicação e tornando seus fluxos de trabalho mais fáceis de manter. Para obter mais informações, consulte "Reutilizando fluxos de trabalho".

Using environments

You can configure environments with protection rules and secrets. Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. For more information, see "Using environments for deployment."

Using a workflow template

GitHub fornece modelos de fluxo de trabalho pré-configurados que você pode personalizar para criar o seu próprio fluxo de trabalho de integração contínua. GitHub analisa seu código e mostra modelos de CI que podem ser úteis para o seu repositório. Por exemplo, se o seu repositório contiver o código Node.js, você verá sugestões para projetos Node.js. Você pode usar os modelos do fluxo de trabalho como um ponto de partida para criar o fluxo de trabalho personalizado ou usá-los como se apresentam.

Você pode navegar pela lista completa dos modelos de fluxo de trabalho no repositório actions/starter-workflows .

  1. No, navegue até a página principal do repositório.
  2. No nome do seu repositório, clique em Ações. Aba Ações na navegação principal do repositório
  3. If your repository already has existing workflows: In the upper-left corner, click New workflow. Create a new workflow
  4. Under the name of the template you'd like to use, click Set up this workflow. Set up this workflow

Next steps

To continue learning about GitHub Actions, see "Sharing workflows, secrets, and runners with your organization."

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.