Migrar do CircleCI para o GitHub Actions

O GitHub Actions e o CircleCI compartilham várias semelhanças em termos de configuração, o que torna a migração para o GitHub Actions relativamente fácil.

Neste artigo

Note

No momento, não há suporte para executores hospedados no GitHub no GitHub Enterprise Server. Você pode ver mais informações sobre o suporte futuro planejado no GitHub public roadmap.

Introdução

O CircleCI e GitHub Actions permitem criar fluxos de trabalho que criam, testam, publicam, lançam e implementam código automaticamente. O CircleCI e o GitHub Actions compartilham algumas semelhanças em termos de configuração do fluxo de trabalho:

  • Os arquivos de configuração do fluxo de trabalho são gravados no YAML e armazenados no repositório.
  • Os fluxos de trabalho incluem um ou mais trabalhos.
  • Os trabalhos incluem uma ou mais etapas ou comandos individuais.
  • É possível reutilizar e compartilhar novamente etapas ou tarefas com a comunidade.

Para saber mais, confira Entendendo o GitHub Actions.

Principais diferenças

Ao fazer a migração do CircleCI, considere as seguintes diferenças:

  • O paralelismo do teste automático do CircleCI agrupa automaticamente os testes de acordo com regras especificadas pelo usuário ou com informações históricas de temporização. Esta funcionalidade não foi criada em GitHub Actions.
  • As ações que são executadas em contêineres Docker são sensíveis a problemas de permissões, uma vez que os contêineres têm um mapeamento diferente de usuários. Você pode evitar muitos desses problemas não usando a instrução USER no Dockerfile. Para obter mais informações sobre o sistema de arquivos do Docker em executores hospedados pelo GitHub Enterprise Server, consulte Usar executores hospedados no GitHub.

Migrar fluxos de trabalhos e trabalhos

O CircleCI define workflows no arquivo config.yml, que permite configurar mais de um fluxo de trabalho. O GitHub Enterprise Server exige um arquivo de fluxo de trabalho por fluxo de trabalho e, consequentemente, não exige que você declare os workflows. Será necessário criar um arquivo de fluxo de trabalho para cada fluxo de trabalho configurado em config.yml.

Tanto o CircleCI quanto o GitHub Actions configuram jobs no arquivo de configuração usando uma sintaxe similar. Se você configurar qualquer dependência entre trabalhos usando requires no seu fluxo de trabalho do CircleCI, poderá usar a sintaxe needs equivalente do GitHub Actions. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.

Migrar orbes para ações

Tanto o CircleCI quanto o GitHub Actions fornecem um mecanismo para reutilizar e compartilhar tarefas em um fluxo de trabalho. O CircleCI usa um conceito chamado orbs, escrito em YAML, para fornecer tarefas que as pessoas podem reutilizar em um fluxo de trabalho. O GitHub Actions tem componentes potentes, reutilizáveis e flexíveis denominados ações, que você cria com arquivos JavaScript ou imagens Docker. Você pode criar ações gravando códigos personalizados que interajam com o seu repositório da maneira que você quiser, inclusive fazendo integrações com as APIs do GitHub Enterprise Server e qualquer API de terceiros disponível publicamente. Por exemplo, uma ação pode publicar módulos npm, enviar alertas de SMS quando problemas urgentes surgirem ou implantar o código pronto para produção. Para saber mais, confira Compartilhar automações.

O CircleCI pode reutilizar partes dos fluxos de trabalho com âncoras e aliases YAML. O GitHub Actions é compatível com a necessidade mais comum de reutilização usando matrizes. Para obter mais informações sobre matrizes, confira Executando variações de trabalhos em um fluxo de trabalho.

Usar imagens do Docker

Tanto o CircleCI quanto o GitHub Actions suportam executar etapas dentro de uma imagem do Docker.

O CircleCI fornece um conjunto de imagens pré-construídas com dependências comuns. Essas imagens têm o USER definido como circleci, o que faz com que as permissões entrem em conflito com o GitHub Actions.

Recomendamos que você se afaste das imagens pré-criadas do CircleCI, ao migrar para GitHub Actions. Em muitos casos, você pode usar ações para instalar as dependências adicionais de que você precisa.

Para saber mais sobre o sistema de arquivos do Docker, confira Usar executores hospedados no GitHub.

Para saber mais sobre as ferramentas e os pacotes disponíveis em imagens do executor hospedadas no GitHub, confira Usar executores hospedados no GitHub.

Usar variáveis e segredos

O CircleCI e GitHub Actions dão suporte à definição de variáveis no arquivo de configuração e à criação de segredos usando o CircleCI ou a interface de usuário do GitHub Enterprise Server.

Para saber mais, confira Armazenar informações em variáveis e Usar segredos em ações do GitHub.

Cache

O CircleCI e o GitHub Actions fornecem um método para armazenar arquivos de cache no arquivo de configuração manualmente.

Abaixo, há um exemplo da sintaxe para cada sistema.

Sintaxe do CircleCI para cache

- restore_cache:
    keys:
      - v1-npm-deps-{{ checksum "package-lock.json" }}
      - v1-npm-deps-

Sintaxe do GitHub Actions para cache

- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: v1-npm-deps-${{ hashFiles('**/package-lock.json') }}
    restore-keys: v1-npm-deps-

GitHub Actions não tem o equivalente ao Docker Layer Caching (DLC) do CircleCI.

Dados persistentes entre trabalhos

Tanto a CircleCI quanto a GitHub Actions fornecem mecanismos para persistir dados entre trabalhos.

Abaixo está um exemplo no CircleCI e na sintaxe de configuração do GitHub Actions.

Sintaxe do CircleCI para persistir dados entre trabalhos

- persist_to_workspace:
    root: workspace
    paths:
      - math-homework.txt

...

- attach_workspace:
    at: /tmp/workspace

Sintaxe do GitHub Actions para persistir dados entre trabalhos

- name: Upload math result for job 1
  uses: actions/upload-artifact@v3
  with:
    name: homework
    path: math-homework.txt

...

- name: Download math result for job 1
  uses: actions/download-artifact@v3
  with:
    name: homework

Para saber mais, confira Armazenando e compartilhando dados de um fluxo de trabalho.

Usar bancos de dados e contêineres de serviço

Ambos os sistemas permitem que você inclua contêineres adicionais para bases de dados, memorização ou outras dependências.

No CircleCI, a primeira imagem listada no config.yaml é a imagem principal primária usada para executar comandos. O GitHub Actions usa seções explícitas: use container para o contêiner primário e liste os contêineres adicionais em services.

Abaixo está um exemplo no CircleCI e na sintaxe de configuração do GitHub Actions.

Sintaxe do CircleCI para usar bancos de dados e contêineres de serviço

---
version: 2.1

jobs:

  ruby-26:
    docker:
      - image: circleci/ruby:2.6.3-node-browsers-legacy
        environment:
          PGHOST: localhost
          PGUSER: administrate
          RAILS_ENV: test
      - image: postgres:10.1-alpine
        environment:
          POSTGRES_USER: administrate
          POSTGRES_DB: ruby26
          POSTGRES_PASSWORD: ""

    working_directory: ~/administrate

    steps:
      - checkout

      # Bundle install dependencies
      - run: bundle install --path vendor/bundle

      # Wait for DB
      - run: dockerize -wait tcp://localhost:5432 -timeout 1m

      # Setup the environment
      - run: cp .sample.env .env

      # Setup the database
      - run: bundle exec rake db:setup

      # Run the tests
      - run: bundle exec rake

workflows:
  version: 2
  build:
    jobs:
      - ruby-26
...

- attach_workspace:
    at: /tmp/workspace

Sintaxe do GitHub Actions para usar bancos de dados e contêineres de serviço

name: Containers

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    container: circleci/ruby:2.6.3-node-browsers-legacy

    env:
      PGHOST: postgres
      PGUSER: administrate
      RAILS_ENV: test

    services:
      postgres:
        image: postgres:10.1-alpine
        env:
          POSTGRES_USER: administrate
          POSTGRES_DB: ruby25
          POSTGRES_PASSWORD: ""
        ports:
          - 5432:5432
        # Add a health check
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5

    steps:
      # This Docker file changes sets USER to circleci instead of using the default user, so we need to update file permissions for this image to work on GH Actions.
      # See https://docs.github.com/actions/using-github-hosted-runners/about-github-hosted-runners#docker-container-filesystem

      - name: Setup file system permissions
        run: sudo chmod -R 777 $GITHUB_WORKSPACE /github /__w/_temp
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: bundle install --path vendor/bundle
      - name: Setup environment configuration
        run: cp .sample.env .env
      - name: Setup database
        run: bundle exec rake db:setup
      - name: Run tests
        run: bundle exec rake

Para saber mais, confira Sobre os contêineres de serviço.

Exemplo completo

Abaixo, há um exemplo concreto. O lado esquerdo mostra o config.yml real do CircleCI para o repositório thoughtbot/administrator. O lado direito mostra o equivalente GitHub Actions.

Exemplo completo do CircleCI

---
version: 2.1

commands:
  shared_steps:
    steps:
      - checkout

      # Restore Cached Dependencies
      - restore_cache:
          name: Restore bundle cache
          key: administrate-{{ checksum "Gemfile.lock" }}

      # Bundle install dependencies
      - run: bundle install --path vendor/bundle

      # Cache Dependencies
      - save_cache:
          name: Store bundle cache
          key: administrate-{{ checksum "Gemfile.lock" }}
          paths:
            - vendor/bundle

      # Wait for DB
      - run: dockerize -wait tcp://localhost:5432 -timeout 1m

      # Setup the environment
      - run: cp .sample.env .env

      # Setup the database
      - run: bundle exec rake db:setup

      # Run the tests
      - run: bundle exec rake

default_job: &default_job
  working_directory: ~/administrate
  steps:
    - shared_steps
    # Run the tests against multiple versions of Rails
    - run: bundle exec appraisal install
    - run: bundle exec appraisal rake

jobs:
  ruby-25:
    <<: *default_job
    docker:
      - image: circleci/ruby:2.5.0-node-browsers
        environment:
          PGHOST: localhost
          PGUSER: administrate
          RAILS_ENV: test
      - image: postgres:10.1-alpine
        environment:
          POSTGRES_USER: administrate
          POSTGRES_DB: ruby25
          POSTGRES_PASSWORD: ""

  ruby-26:
    <<: *default_job
    docker:
      - image: circleci/ruby:2.6.3-node-browsers-legacy
        environment:
          PGHOST: localhost
          PGUSER: administrate
          RAILS_ENV: test
      - image: postgres:10.1-alpine
        environment:
          POSTGRES_USER: administrate
          POSTGRES_DB: ruby26
          POSTGRES_PASSWORD: ""

workflows:
  version: 2
  multiple-rubies:
    jobs:
      - ruby-26
      - ruby-25

Exemplo completo do GitHub Actions

# Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.

# O GitHub recomenda fixar ações em um SHA de commit.
# Para obter uma versão mais recente, você precisará atualizar o SHA.
# Você também pode fazer referência a uma marca ou branch, mas a ação pode ser alterada sem aviso.

name: Containers

on: [push]

jobs:
  build:

    strategy:
      matrix:
        ruby: ['2.5', '2.6.3']

    runs-on: ubuntu-latest

    env:
      PGHOST: localhost
      PGUSER: administrate
      RAILS_ENV: test

    services:
      postgres:
        image: postgres:10.1-alpine
        env:
          POSTGRES_USER: administrate
          POSTGRES_DB: ruby25
          POSTGRES_PASSWORD: ""
        ports:
          - 5432:5432
        # Add a health check
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5

    steps:
      - uses: actions/checkout@v4
      - name: Setup Ruby
        uses: eregon/use-ruby-action@ec02537da5712d66d4d50a0f33b7eb52773b5ed1
        with:
          ruby-version: ${{ matrix.ruby }}
      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: vendor/bundle
          key: administrate-${{ matrix.image }}-${{ hashFiles('Gemfile.lock') }}
      - name: Install postgres headers
        run: |
          sudo apt-get update
          sudo apt-get install libpq-dev
      - name: Install dependencies
        run: bundle install --path vendor/bundle
      - name: Setup environment configuration
        run: cp .sample.env .env
      - name: Setup database
        run: bundle exec rake db:setup
      - name: Run tests
        run: bundle exec rake
      - name: Install appraisal
        run: bundle exec appraisal install
      - name: Run appraisal
        run: bundle exec appraisal rake