Tutorial

GitHub Actions é uma plataforma poderosa de CI/CD que permite automatizar seus fluxos de trabalho de desenvolvimento de software. Embora o GitHub ofereça runners hospedados, runners auto-hospedados fornecem maior controle e personalização para sua configuração de CI/CD. Este tutorial o guia através da configuração e conexão de um runner auto-hospedado em um Mac Mini para executar pipelines do macOS.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Um Mac Mini (registre-se no Roundfleet)
• Um repositório GitHub com direitos de administrador
• Um gerenciador de pacotes instalado (preferencialmente Homebrew)
• Git instalado em seu sistema

Passo 1: Criar uma Conta de Usuário Dedicada

Primeiro, crie uma conta de usuário dedicada para o runner do GitHub Actions:

# Criar a conta de usuário 'gh-runner'
sudo dscl . -create /Users/gh-runner
sudo dscl . -create /Users/gh-runner UserShell /bin/bash
sudo dscl . -create /Users/gh-runner RealName "GitHub runner"
sudo dscl . -create /Users/gh-runner UniqueID "1001"
sudo dscl . -create /Users/gh-runner PrimaryGroupID 20
sudo dscl . -create /Users/gh-runner NFSHomeDirectory /Users/gh-runner

# Definir a senha para o usuário
sudo dscl . -passwd /Users/gh-runner sua_senha

# Adicionar 'gh-runner' ao grupo 'admin'
sudo dscl . -append /Groups/admin GroupMembership gh-runner

Mude para a nova conta de usuário:

su gh-runner

Passo 2: Instalar Software Necessário

Instale Git e Rosetta 2 (se estiver usando Apple Silicon):

# Instalar Git se ainda não estiver instalado
brew install git

# Instalar Rosetta 2 para Macs Apple Silicon
softwareupdate --install-rosetta

Passo 3: Configurar o Runner do GitHub Actions

1. Vá para seu repositório GitHub
2. Navegue para Configurações > Actions > Runners

3. Clique em "New self-hosted runner" (https://github.com/<username>/<repository>/settings/actions/runners/new)
4. Selecione macOS como imagem do runner e ARM64 como arquitetura
5. Siga os comandos fornecidos para baixar e configurar o runner

Crie um arquivo .env no diretório _work do runner:

# arquivo _work/.env
ImageOS=macos15
XCODE_15_DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer

6. Execute o script run.sh em seu diretório do runner para completar a configuração.
7. Verifique se o runner está ativo e ouvindo por trabalhos no terminal e verifique as configurações do repositório GitHub para a associação do runner e status Idle.

Passo 4: Configurar Sudoers (Opcional)

Se suas ações requerem privilégios de root, configure o arquivo sudoers:

sudo visudo

Adicione a seguinte linha:

gh-runner ALL=(ALL) NOPASSWD: ALL

Passo 5: Usar o Runner em Fluxos de Trabalho

Configure seu fluxo de trabalho do GitHub Actions para usar o runner auto-hospedado:

name: Fluxo de trabalho de exemplo

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - name: Instalar NodeJS
        run: brew install node

O runner está autenticado em seu repositório e rotulado com self-hosted, macOS, e ARM64. Use-o em seus fluxos de trabalho especificando estes rótulos no campo runs-on:

runs-on: [self-hosted, macOS, ARM64]

Melhores Práticas

• Mantenha seu software do runner atualizado
• Monitore regularmente os logs do runner para problemas
• Use rótulos específicos para diferentes tipos de runners
• Implemente medidas de segurança adequadas
• Considere usar múltiplos runners para balanceamento de carga

Solução de Problemas

Problemas comuns e soluções:

1. Runner não conectando:

   • Verifique conectividade de rede
   • Verifique validade do token GitHub
   • Certifique-se de permissões adequadas

2. Falhas de build:

   • Verifique instalação do Xcode
   • Verifique dependências necessárias
   • Revise logs do fluxo de trabalho

3. Problemas de permissão:

   • Verifique permissões do usuário
   • Verifique configuração sudoers
   • Revise permissões do sistema de arquivos

Conclusão

Agora você tem um runner auto-hospedado do GitHub Actions configurado em seu Mac Mini. Esta configuração fornece mais controle sobre seu ambiente CI/CD e permite executar fluxos de trabalho específicos do macOS de forma eficiente.

Lembre-se de manter regularmente seu runner e mantê-lo atualizado com os patches de segurança e versões de software mais recentes.