S3 Files (launched Nov/2025) is the new AWS NFS file system backed by S3 buckets. Instead of testing with a “hello world”, I picked a useful case from the start: an SFTP server on EC2 with /home/sftp mounted via S3 Files — every partner upload lands straight in the bucket, no agent, no worker, no cron.

The full setup runs at ~$14/month (t4g.small + EBS + bucket + S3 Files). As a market reference, Transfer Family has a fixed ~$216/month, but the comparison isn’t the focus here — the focus is understanding the new service by building something real on top of it.

Tested on AL2023 + amazon-efs-utils 3.1.0, May/2026.

TL;DR — the four lessons:

1. The IAM principal is elasticfilesystem.amazonaws.com, not s3files.*
2. mount -t efs fails silently; you need -t s3files
3. The helper needs botocore AND elasticfilesystem:DescribeMountTargets (not in any managed policy)
4. Versioning is mandatory → rm creates a delete marker; without lifecycle, cost grows forever

This post is the walkthrough of what worked + the literal errors that came up. It’s not a mechanical tutorial (“run these commands”); it’s the actual sequence with the decisions I had to make.

What S3 Files is

In one sentence: you mount a local directory on an EC2 instance and anything you write there shows up in S3 within seconds, with the bucket as source of truth (versioning, lifecycle, replication).

Architecture

        Internet
           │
        :22 TCP
           │
     ┌─────▼─────┐
     │ EC2 AL2023│
     │   ARM     │
     │           │
     │  sshd +   │
     │  chroot   │
     │  fail2ban │
     └──┬─────┬──┘
        │     │
   :2049│     │ EBS gp3
   NFS  │     │ (OS + host keys)
        ▼
  ┌──────────────┐
  │ S3 Files     │
  │ /home/sftp   │
  └──────┬───────┘
         │ auto sync
         ▼
   ┌─────────┐
   │ Bucket  │
   │  S3     │
   └─────────┘

EC2 t4g.small running Amazon Linux 2023, minimal IAM, IMDSv2 required, SG with restricted egress. Provisioned via AWS CDK (Python).

Lesson 1: the IAM principal is called elasticfilesystem, not s3files

S3 Files needs a service role that the service assumes to read/write your bucket. The first question I had to answer was: which service principal is correct?

The prerequisites page (s3-files-prereq-policies.html) answers it in the very first trust policy block — and the answer is less obvious than the service name suggests:

assumed_by=iam.PrincipalWithConditions(
    iam.ServicePrincipal("elasticfilesystem.amazonaws.com"),
    conditions={
        "StringEquals": {"aws:SourceAccount": self.account},
        "ArnLike": {
            "aws:SourceArn": f"arn:aws:s3files:{self.region}:{self.account}:file-system/*"
        },
    },
)

Two details worth highlighting:

1. The principal is elasticfilesystem.amazonaws.com, not s3files.*. S3 Files reuses the EFS control plane behind the scenes. Trusting the service name to guess the principal lands you on Invalid principal in policy: "SERVICE":"s3files.amazonaws.com".

2. The aws:SourceAccount and aws:SourceArn conditions are the confused deputy countermeasure — they close the gap where another file system, possibly from another account, could trick the EFS principal into assuming your role. The docs ship them ready to use; keep them in your code.

Lesson: for any new AWS service, opening the IAM/prerequisites page before writing code saves a broken deploy.

Lesson 2: the mount type is s3files, not efs

The docs list amazon-efs-utils (≥ 3.0.0) as a prerequisite and describe a “mount helper”. The instinct, coming from someone who has used EFS, is to mount with -t efs:

echo "$FS_ID:/ /home/sftp efs _netdev,tls,noatime 0 0" >> /etc/fstab
mount -a -t efs

And nothing happens. The log at /var/log/amazon/efs/mount.log shows:

Failed to resolve fs-XXX.efs.us-east-1.amazonaws.com

The helper, with -t efs, looks for an EFS endpoint — which doesn’t exist for an S3 Files file system. The correct command lives in Step 3 of the Getting Started tutorial:

sudo mount -t s3files <file-system-id>:/ /mnt/s3files

And in fstab:

fs-XXXXXXXXXXXXXXXXX:/  /home/sftp  s3files  _netdev,noatime  0 0

The maturity here is realizing amazon-efs-utils has become an umbrella package: the same binary responds to two configs (/etc/amazon/efs/efs-utils.conf and /etc/amazon/efs/s3files-utils.conf) depending on the mount type declared. With -t s3files, the helper opens a local stunnel TLS at 127.0.0.1:<random-port> and tunnels NFS to that endpoint:

$ mount | grep sftp
127.0.0.1:/ on /home/sftp type nfs4 (rw,noatime,vers=4.2,...,port=20423,...)

Lesson: for services that reuse existing packages/infrastructure (amazon-efs-utils, elasticfilesystem principal), the Getting Started tutorial usually carries the detail the prerequisites page omits. Worth reading both before you implement.

Lesson 3: amazon-efs-utils doesn’t pull botocore, and needs an extra IAM permission

Even with -t s3files correct, two errors show up in sequence. Both share a root cause: mount.s3files needs to discover the mount target IP at runtime, and to do that it makes an API call with boto3.

Error 1: botocore missing

ERROR - Failed to import botocore, please install botocore first.

The docs do warn about this in a whole section (Step 2: Install botocore). What’s worth recording: on Amazon Linux 2023 the amazon-efs-utils package does not declare python3-botocore as a dependency — dnf install amazon-efs-utils alone won’t resolve it. Definitive fix in user-data:

dnf install -y amazon-efs-utils python3-botocore

Error 2: missing IAM permission

After fixing botocore, the next error:

User: ... is not authorized to perform:
  elasticfilesystem:DescribeMountTargets on the specified resource

This part is worth highlighting: efs-utils 3.1.0 calls the EFS API to discover the mount target IP, even when the file system is S3 Files. The IAM role for attaching your file system section recommends either the managed policy AmazonS3FilesClientFullAccess or granular s3files:ClientMount + s3files:ClientWrite. Neither includes elasticfilesystem:*. Solution:

iam.PolicyStatement(
    sid="EfsUtilsMountTargetLookup",
    actions=[
        "elasticfilesystem:DescribeMountTargets",
        "elasticfilesystem:DescribeFileSystems",
    ],
    resources=["*"],
)

I added it as an explicit statement for two reasons: it makes visible why that permission exists (efs-utils, not the service), and it survives a future package update that may not need it anymore.

The docs mention the AmazonElasticFileSystemUtils managed policy in another context (CloudWatch). I haven’t tested, but it likely covers these two actions already — possible simplification.

Lesson: when an SDK/client is shared between services, always look at the APIs it calls internally, not just the target service’s. The mount helper’s log tells you exactly which call failed — that’s the fastest path to correct IAM.

Lesson 4: versioning is mandatory — and that changes what “delete” means

S3 Files requires versioning enabled on the bucket. The docs state it plainly in the AWS account and compute setup section:

Your S3 bucket has versioning enabled. S3 Files requires S3 Versioning to synchronize changes between your file system and your S3 bucket.

Without it, file system creation fails. The operational consequence is non-trivial:

• When an SFTP user runs rm file.txt inside the chroot, S3 Files passes it to the bucket. Since the bucket is versioned, there is no real delete: a delete marker is created and the original version is preserved.
• aws s3 ls (lists visible objects) shows the object gone, but aws s3api list-object-versions keeps showing both: the old version and the delete marker hiding it.
• Without a lifecycle policy, those versions stay forever in the bucket, paying storage.

I lived through this when removing a test user:

userdel testuser
rm -rf /home/sftp/testuser

aws s3 ls showed the bucket “clean”. But list-object-versions revealed three versions + three delete markers for testuser/upload/teste.txt. For a real purge:

import json, subprocess
v = json.loads(subprocess.run([
    "aws", "s3api", "list-object-versions",
    "--bucket", BUCKET, "--prefix", "testuser/", "--region", REGION,
    "--output", "json"], capture_output=True, text=True).stdout)
objs = [{'Key': x['Key'], 'VersionId': x['VersionId']}
        for x in (v.get('Versions') or []) + (v.get('DeleteMarkers') or [])]

Then send the batch to delete-objects. The structural fix is to always add a lifecycle policy when creating the bucket:

bucket = s3.Bucket(self, "SftpBucket",
    versioned=True,  # S3 Files requirement
    lifecycle_rules=[
        s3.LifecycleRule(
            id="DeleteOldVersions",
            noncurrent_version_expiration=Duration.days(90),
        ),
        s3.LifecycleRule(
            id="CleanupDeleteMarkers",
            expired_object_delete_marker=True,
        ),
    ],
)

Without this, cost grows linearly with file movement and it’s easy to forget.

Lesson: when a service requires versioning, lifecycle isn’t optimization — it’s part of the design. Treating it as a mandatory bucket feature (same construct, same PR) prevents it from becoming operational debt.

When S3 Files makes sense

For a low-to-medium volume SFTP (a few GB/month) the full setup runs at ~$14/month: t4g.small + EBS + bucket + S3 Files cost. As a market reference, Transfer Family has a fixed ~$216/month before the first byte transferred — that’s when S3 Files starts to make a lot of sense for teams comfortable maintaining an EC2.

The breakeven vs Transfer Family sits around 4.3 TB/month of traffic — above that, S3 Files cache cost ($0.06/GB stored in cache + $0.03/GB sync) grows past the fixed Transfer Family cost. For most partner-SFTP cases (a few files per day), you stay far from that limit.

What S3 Files does not ship out of the box (that managed services do):

• Centralized SSH user and key management.
• AS2 and FTPS support.
• Zero-touch operation — you still have an EC2 to patch and monitor.

Where it earns a spot as a new tool in the kit:

• Pipelines where the bucket must be source of truth (lifecycle, replication, Object Lock).
• Legacy workloads that speak NFS but the team already has S3 tooling (Glue, Athena, Lambda).
• Replacing EFS in write-once/read-many scenarios, where S3 storage ($0.023/GB) beats EFS ($0.30/GB).

References

• Prerequisites for S3 Files — IAM, SG, botocore and versioning (source of lessons #1, #3 and #4)
• Tutorial: Getting started with S3 Files — where mount -t s3files finally appears
• AWS::S3Files::FileSystem CFN — resource properties
• AWS S3 Files just made Transfer Family SFTP obsolete — original post that motivated the experiment

S3 Files (lançado nov/2025) é o novo NFS da AWS lastreado por bucket S3. Em vez de testar com um “hello world”, escolhi um caso útil de primeira: servidor SFTP em EC2 com /home/sftp montado via S3 Files — cada upload de parceiro cai direto no bucket, sem agente, sem worker, sem cron.

Saiu por ~$14/mês (t4g.small + EBS + bucket + S3 Files). Como referência de mercado, Transfer Family tem fixo de ~$216/mês, mas a comparação não é o foco aqui — o foco é entender o serviço novo construindo algo de verdade em cima dele.

Testado em AL2023 + amazon-efs-utils 3.1.0, maio/2026.

TL;DR — os quatro aprendizados:

1. O principal IAM é elasticfilesystem.amazonaws.com, não s3files.*
2. mount -t efs falha silenciosamente; precisa ser -t s3files
3. O helper precisa de botocore E de elasticfilesystem:DescribeMountTargets (não está em nenhuma managed policy)
4. Versionamento é obrigatório → rm cria delete marker; sem lifecycle vira custo eterno

O post é o passo a passo do que funcionou + os erros literais que apareceram. Não é tutorial mecânico (“execute esses comandos”); é a sequência real, com as decisões que tive que tomar.

O que é S3 Files

Em uma frase: você monta um diretório local em uma EC2 e tudo o que escrever lá aparece no S3 em segundos, mantendo o bucket como fonte da verdade (com versionamento, lifecycle e replicação).

Arquitetura do experimento

        Internet
           │
        :22 TCP
           │
     ┌─────▼─────┐
     │ EC2 AL2023│
     │   ARM     │
     │           │
     │  sshd +   │
     │  chroot   │
     │  fail2ban │
     └──┬─────┬──┘
        │     │
   :2049│     │ EBS gp3
   NFS  │     │ (SO + host keys)
        ▼
  ┌──────────────┐
  │ S3 Files     │
  │ /home/sftp   │
  └──────┬───────┘
         │ sync auto
         ▼
   ┌─────────┐
   │ Bucket  │
   │  S3     │
   └─────────┘

EC2 t4g.small com Amazon Linux 2023, IAM minimal, IMDSv2 obrigatório, SG com egress restrito. Tudo provisionado via AWS CDK (Python).

Aprendizado 1: o principal IAM se chama elasticfilesystem, não s3files

S3 Files exige uma service role que o serviço assume para ler e escrever no seu bucket. A primeira pergunta que precisei responder foi: qual é o service principal correto?

A doc de pré-requisitos (s3-files-prereq-policies.html) responde já no primeiro bloco de trust policy — e a resposta é menos óbvia do que parece pelo nome do serviço:

assumed_by=iam.PrincipalWithConditions(
    iam.ServicePrincipal("elasticfilesystem.amazonaws.com"),
    conditions={
        "StringEquals": {"aws:SourceAccount": self.account},
        "ArnLike": {
            "aws:SourceArn": f"arn:aws:s3files:{self.region}:{self.account}:file-system/*"
        },
    },
)

Dois detalhes valem destaque:

1. O principal é elasticfilesystem.amazonaws.com, não s3files.*. S3 Files reaproveita a infra de controle do EFS por trás dos panos. Confiar no nome do serviço pra adivinhar o principal te leva pro erro Invalid principal in policy: "SERVICE":"s3files.amazonaws.com".

2. As condições aws:SourceAccount e aws:SourceArn são contra-medida ao confused deputy — fecham a brecha em que outro file system, possivelmente de outra conta, poderia induzir o principal EFS a assumir sua role. A doc traz isso pronto; manter no código.

Lição: pra serviço novo da AWS, abrir a página de IAM/pré-requisitos antes de escrever código economiza um deploy quebrado.

Aprendizado 2: o tipo do mount é s3files, não efs

A doc lista amazon-efs-utils (≥ 3.0.0) como pré-requisito e descreve um “mount helper”. O instinto, vindo de quem já usou EFS, é montar com -t efs:

echo "$FS_ID:/ /home/sftp efs _netdev,tls,noatime 0 0" >> /etc/fstab
mount -a -t efs

E nada acontece. O log em /var/log/amazon/efs/mount.log mostra:

Failed to resolve fs-XXX.efs.us-east-1.amazonaws.com

O helper, com -t efs, busca um endpoint EFS — que não existe para um file system S3 Files. O comando correto está no Step 3 do tutorial Getting Started:

sudo mount -t s3files <file-system-id>:/ /mnt/s3files

E no fstab:

fs-XXXXXXXXXXXXXXXXX:/  /home/sftp  s3files  _netdev,noatime  0 0

A maturidade aqui é entender que amazon-efs-utils virou um pacote guarda-chuva: o mesmo binário responde a duas configs (/etc/amazon/efs/efs-utils.conf e /etc/amazon/efs/s3files-utils.conf) dependendo do tipo declarado no mount. Com -t s3files, o helper abre um stunnel TLS local em 127.0.0.1:<porta-aleatória> e tunela NFS pra esse endpoint:

$ mount | grep sftp
127.0.0.1:/ on /home/sftp type nfs4 (rw,noatime,vers=4.2,...,port=20423,...)

Lição: para serviços que reusam pacotes/infraestrutura existentes (amazon-efs-utils, principal elasticfilesystem), o tutorial Getting Started costuma trazer o detalhe que o pré-requisitos omite. Vale ler os dois antes de implementar.

Aprendizado 3: o pacote amazon-efs-utils não puxa botocore e exige uma permissão IAM extra

Mesmo com -t s3files correto, dois erros aparecem em sequência. Os dois têm raiz comum: o mount.s3files precisa descobrir o IP do mount target em runtime, e pra isso ele faz uma chamada de API com boto3.

Erro 1: botocore ausente

ERROR - Failed to import botocore, please install botocore first.

A doc avisa numa seção inteira (Step 2: Install botocore). O detalhe que vale registrar é que no Amazon Linux 2023 o pacote amazon-efs-utils não declara python3-botocore como dependência — dnf install amazon-efs-utils sozinho não resolve. Fix definitivo no user-data:

dnf install -y amazon-efs-utils python3-botocore

Erro 2: permissão IAM ausente

Resolvido o botocore, o próximo erro:

User: ... is not authorized to perform:
  elasticfilesystem:DescribeMountTargets on the specified resource

Essa parte vale o destaque: o efs-utils 3.1.0 chama a API do EFS para descobrir o IP do mount target, mesmo quando o file system é S3 Files. A doc de IAM role for attaching your file system recomenda a managed policy AmazonS3FilesClientFullAccess ou as ações granulares s3files:ClientMount + s3files:ClientWrite. Nenhuma delas inclui elasticfilesystem:*. Solução:

iam.PolicyStatement(
    sid="EfsUtilsMountTargetLookup",
    actions=[
        "elasticfilesystem:DescribeMountTargets",
        "elasticfilesystem:DescribeFileSystems",
    ],
    resources=["*"],
)

Adicionei como statement explícito por dois motivos: deixa visível por que essa permissão existe (referência ao efs-utils, não ao serviço), e sobrevive a uma futura atualização do pacote que talvez nem precise mais dela.

A doc menciona a managed policy AmazonElasticFileSystemUtils em outro contexto (CloudWatch). Não testei, mas é provável que ela já cubra essas duas ações — fica como possível simplificação.

Lição: quando um SDK/cliente é compartilhado entre serviços, sempre olhe as APIs que ele chama internamente, não só as do serviço-alvo. O log do mount helper diz exatamente qual chamada falhou — esse é o caminho mais rápido pra IAM correto.

Aprendizado 4: bucket versionado é obrigatório — e isso muda o significado de “deletar”

O S3 Files exige versionamento ligado no bucket. Está explícito na seção AWS account and compute setup da doc:

Your S3 bucket has versioning enabled. S3 Files requires S3 Versioning to synchronize changes between your file system and your S3 bucket.

Sem isso, a criação do file system falha. A consequência operacional não é trivial:

• Quando um usuário SFTP roda rm arquivo.txt no chroot, o S3 Files repassa para o bucket. Como o bucket é versionado, não há delete de fato: cria-se um delete marker e a versão original fica preservada.
• aws s3 ls (lista as visíveis) mostra o objeto sumido, mas aws s3api list-object-versions continua mostrando ambos: a versão antiga e o delete marker que a esconde.
• Sem lifecycle policy, essas versões ficam indefinidamente no bucket pagando armazenamento.

Eu vivenciei isso ao apagar um usuário de teste:

userdel testuser
rm -rf /home/sftp/testuser

aws s3 ls apresentou o bucket “limpo”. Mas list-object-versions revelou três versões + três delete markers do testuser/upload/teste.txt. Para purge real:

import json, subprocess
v = json.loads(subprocess.run([
    "aws", "s3api", "list-object-versions",
    "--bucket", BUCKET, "--prefix", "testuser/", "--region", REGION,
    "--output", "json"], capture_output=True, text=True).stdout)
objs = [{'Key': x['Key'], 'VersionId': x['VersionId']}
        for x in (v.get('Versions') or []) + (v.get('DeleteMarkers') or [])]

E enviar o lote ao delete-objects. A solução estrutural é sempre adicionar uma lifecycle policy ao criar o bucket:

bucket = s3.Bucket(self, "SftpBucket",
    versioned=True,  # exigência do S3 Files
    lifecycle_rules=[
        s3.LifecycleRule(
            id="DeleteOldVersions",
            noncurrent_version_expiration=Duration.days(90),
        ),
        s3.LifecycleRule(
            id="CleanupDeleteMarkers",
            expired_object_delete_marker=True,
        ),
    ],
)

Sem isso, o custo cresce linearmente com a movimentação de arquivos e fica fácil esquecer.

Lição: quando o serviço exige versionamento, lifecycle não é otimização — é parte do desenho. Tratar como recurso obrigatório do bucket (no mesmo construct, no mesmo PR) evita que vire dívida operacional.

Quando faz sentido usar S3 Files

Para um SFTP de volume baixo a médio (alguns GB/mês) o setup completo sai por ~$14/mês: t4g.small + EBS + bucket + custo do S3 Files. Como referência de mercado, o Transfer Family tem fixo de ~$216/mês antes do primeiro byte transferido — aí o S3 Files começa a fazer muito sentido para times que topam manter uma EC2.

O breakeven com Transfer Family sai por volta de 4,3 TB/mês de tráfego — acima disso o custo de cache do S3 Files ($0,06/GB armazenado em cache + $0,03/GB sync) cresce além do fixo do Transfer Family. Para a maioria dos casos de SFTP de parceiros (alguns arquivos por dia), você fica muito longe desse limite.

O que o S3 Files não entrega de fábrica (e que serviços managed entregam):

• Gerência centralizada de usuários e chaves SSH.
• Suporte a AS2 e FTPS.
• Operação zero-touch — você ainda tem uma EC2 pra patchar e monitorar.

E onde ele entra como ferramenta nova no toolkit:

• Pipelines em que o bucket precisa ser fonte da verdade (lifecycle, replicação, Object Lock).
• Workloads legadas que falam NFS mas o time já tem todo o ferramental S3 (Glue, Athena, Lambda).
• Substituir EFS em cenários de mais escrita-uma-vez/leitura-muitas, onde o custo do S3 ($0,023/GB) supera o do EFS ($0,30/GB).

Referências

• Prerequisites for S3 Files — IAM, SG, botocore e versionamento (fonte dos aprendizados #1, #3 e #4)
• Tutorial: Getting started with S3 Files — onde finalmente aparece mount -t s3files
• AWS::S3Files::FileSystem CFN — propriedades do recurso
• AWS S3 Files just made Transfer Family SFTP obsolete — post original que motivou o experimento

Sexta-feira, 17h. Você termina aquela feature, roda um git add . satisfeito, commit, push. Vai pegar um cafe. No caminho de volta pro computador, aquele frio na barriga: “espera… o .env estava no staged?”. Abre o GitHub, confere o commit e la esta — AWS_SECRET_ACCESS_KEY em texto plano, publicado para o mundo. O resto da sexta vira um incidente de seguranca: revogar chaves, rotacionar credenciais, avisar o time, rezar para ninguem ter visto.

Se voce ja viveu isso (ou vive com medo de viver), o SOPS e para voce. Ele permite commitar seus arquivos de secrets criptografados direto no repositorio. Sem medo. Sem incidente. Sem sexta-feira arruinada.

O Problema

Toda aplicacao tem secrets: tokens de API, credenciais de banco, chaves privadas. O desafio e como compartilha-las com o time sem:

• Commitar .env em texto plano no repositorio
• Depender de alguem mandar credenciais por Slack/email
• Perder acesso quando alguem sai do time
• Manter um vault complexo para projetos pequenos/medios

O SOPS (Secrets OPerationS) resolve isso: ele criptografa apenas os valores dos seus arquivos de secrets, mantendo as chaves legiveis. Combinado com um KMS (AWS, GCP, Azure) ou GPG, qualquer pessoa autorizada pode decriptar — sem compartilhar senha.

TL;DR

# Instalar SOPS
# https://github.com/getsops/sops/releases

# Configurar a chave KMS
export SOPS_KMS_ARN="arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sua-chave"

# Criptografar um arquivo existente
sops encrypt .env > .env.enc

# Editar secrets (decripta, abre editor, re-criptografa ao salvar)
sops edit .env

# Usar secrets como variáveis de ambiente (sem arquivo decriptado em disco)
sops exec-env .env "helm install ..."

Indice

• O que e SOPS
• Instalacao
• Configuracao Inicial
• Workflow no Dia a Dia
• Formatos Suportados
• Backends de Criptografia
• Usando com Helm e Kubernetes
• Boas Praticas
• Conclusao

O que é SOPS

SOPS é uma ferramenta da Mozilla (agora mantida pela CNCF) que criptografa arquivos de configuração. O diferencial:

# Arquivo original (.env)
GITHUB_PAT=ghp_abc123xyz789
AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCY
DB_PASSWORD=super-secret-123

# Após criptografar com SOPS
GITHUB_PAT=ENC[AES256_GCM,data:k8vM2n...,type:str]
AWS_SECRET_KEY=ENC[AES256_GCM,data:pQ7xR...,type:str]
DB_PASSWORD=ENC[AES256_GCM,data:mN3kL...,type:str]

As chaves (GITHUB_PAT, AWS_SECRET_KEY) continuam legíveis — você sabe o que o arquivo contém sem decriptar. Apenas os valores são criptografados.

Isso significa que:

• O arquivo pode ser commitado no repositório com segurança
• Code review consegue ver quais secrets foram adicionadas/removidas
• git diff mostra mudanças estruturais sem expor valores

Por que usar um KMS (Key Management Service)

O SOPS suporta vários backends. Os cloud KMS (AWS, GCP, Azure) compartilham vantagens sobre GPG/age:

• Controle via IAM — quem pode decriptar é controlado por políticas do cloud provider
• Auditoria — cada uso da chave é registrado (CloudTrail, Cloud Audit Logs)
• Rotação automática — o provider rotaciona a chave sem quebrar arquivos existentes
• Sem segredo compartilhado — não precisa distribuir uma chave privada entre o time

Se você não usa nenhum cloud provider, GPG e age funcionam perfeitamente — só exigem mais gestão manual de chaves.

Instalação

SOPS

Baixe o binário da página de releases:

# Linux (amd64)
curl -LO https://github.com/getsops/sops/releases/download/v3.9.4/sops-v3.9.4.linux.amd64
mv sops-v3.9.4.linux.amd64 /usr/local/bin/sops
chmod +x /usr/local/bin/sops

# macOS (via Homebrew)
brew install sops

# Verificar
sops --version

AWS CLI

Você precisa do AWS CLI configurado com credenciais que tenham acesso à chave KMS:

aws sts get-caller-identity  # Verifica se está autenticado

Configuração Inicial

1. Criar (ou identificar) a chave KMS

Se você já tem uma chave KMS, pegue o ARN ou alias. Se não:

aws kms create-key --description "SOPS encryption key"

# Criar um alias para facilitar
aws kms create-alias \
    --alias-name alias/sops-key \
    --target-key-id <key-id-retornado>

2. Exportar o ARN

export SOPS_KMS_ARN="arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"

3. Criar o arquivo .sops.yaml (opcional, recomendado)

Na raiz do projeto, crie um .sops.yaml para não precisar passar o ARN toda vez:

creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"
  - path_regex: secrets\.ya?ml$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"

Com isso, qualquer arquivo .env ou secrets.yml será automaticamente criptografado com a chave correta.

Workflow no Dia a Dia

Criptografar um arquivo pela primeira vez

# Se tem .sops.yaml configurado:
sops encrypt .env > .env.enc
mv .env.enc .env

# Ou especificando a chave manualmente:
sops encrypt --kms "arn:aws:kms:..." .env > .env.enc

Editar secrets

O comando mais usado. Decripta, abre no editor, re-criptografa ao salvar:

sops edit .env

Usa o editor definido em $EDITOR (vim, nano, code, etc).

Usar secrets sem arquivo em disco

O exec-env injeta as secrets como variáveis de ambiente em um subprocesso — nada fica em texto plano no disco:

# Abre um shell com todas as variáveis disponíveis
sops exec-env .env "bash"

# Executa um comando específico
sops exec-env .env "helm upgrade --set token=\$GITHUB_PAT ..."

Decriptar para stdout (debug)

sops decrypt .env

Ver diff entre versões

Como as chaves são legíveis, git diff funciona normalmente para mostrar quais secrets foram adicionadas ou removidas.

Formatos Suportados

O SOPS funciona com múltiplos formatos:

Exemplo com YAML

# secrets.yml (após SOPS encrypt)
database:
    host: ENC[AES256_GCM,data:mQ2x...,type:str]
    password: ENC[AES256_GCM,data:k9Lp...,type:str]
    port: 5432  # valores não-sensíveis podem ser excluídos da criptografia
sops:
    kms:
        - arn: arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key
    version: 3.9.4

Criptografar apenas alguns campos

Use --encrypted-regex para criptografar apenas campos que contenham “password”, “secret”, “token”, etc:

sops encrypt --encrypted-regex '^(password|secret|token)$' config.yml

Usando com Helm e Kubernetes

O caso de uso mais comum: passar secrets para helm install sem expô-las.

Padrão com exec-env

# .env criptografado contém GITHUB_PAT=ghp_xxx
sops exec-env .env "helm install runner \
    --set githubConfigSecret.github_token=\$GITHUB_PAT \
    --namespace arc-runners \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set"

Padrão com script

#!/bin/bash
# update-runners.sh — executar via: sops exec-env .env "./update-runners.sh"

helm upgrade --install runner \
    --namespace arc-runners \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

sops exec-env .env "./update-runners.sh"

Valores sensíveis em um values file

Se preferir manter tudo em YAML:

# Criar values-secrets.yml com tokens
sops edit values-secrets.yml

# Usar decriptado inline com helm
sops decrypt values-secrets.yml | helm install runner \
    --namespace arc-runners \
    -f - \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Boas Práticas

1. Commite o arquivo criptografado

# .gitignore
# NÃO ignore o .env se ele está criptografado com SOPS
# Ignore apenas se for texto plano:
# .env

O ponto central do SOPS é poder versionar secrets com segurança. Se o arquivo está criptografado, ele deve estar no repositório.

2. Use .sops.yaml no projeto

Evita que alguém esqueça de especificar a chave e criptografe com o backend errado.

3. Controle acesso via IAM

{
  "Effect": "Allow",
  "Action": ["kms:Decrypt", "kms:DescribeKey"],
  "Resource": "arn:aws:kms:us-east-1:xxxxxxxxxxxx:key/key-id"
}

Apenas quem precisa decriptar recebe kms:Decrypt. Outros podem ver a estrutura do arquivo sem acessar os valores.

4. Nunca decripte para um arquivo

# Ruim — cria arquivo em texto plano no disco
sops decrypt .env > .env.plain

# Bom — usa em memória apenas
sops exec-env .env "comando"

5. Adicione múltiplas chaves KMS

Para redundância ou acesso cross-account:

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key,arn:aws:kms:us-east-1:yyyyyyyyyyyy:alias/sops-backup"

Qualquer uma das chaves pode decriptar o arquivo.

Backends de Criptografia

O SOPS não é exclusivo da AWS. Ele suporta múltiplos backends — escolha o que faz sentido para sua infraestrutura:

AWS KMS

Ideal se seu time já está na AWS. Controle de acesso via IAM, auditoria via CloudTrail.

export SOPS_KMS_ARN="arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"
sops encrypt .env

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"

GCP Cloud KMS

Mesmo conceito, para times no Google Cloud. Controle via IAM do GCP.

# Criar keyring e chave (uma vez)
gcloud kms keyrings create sops --location global
gcloud kms keys create sops-key \
    --location global \
    --keyring sops \
    --purpose encryption

# Criptografar
sops encrypt \
    --gcp-kms "projects/meu-projeto/locations/global/keyRings/sops/cryptoKeys/sops-key" \
    .env

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    gcp_kms: "projects/meu-projeto/locations/global/keyRings/sops/cryptoKeys/sops-key"

Para decriptar, basta ter gcloud auth application-default login configurado com permissão cloudkms.cryptoKeyVersions.useToDecrypt.

Azure Key Vault

Para times no Azure:

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    azure_keyvault: "https://meu-vault.vault.azure.net/keys/sops-key/version-id"

GPG/PGP

Funciona sem nenhum cloud provider. Cada membro do time tem sua chave GPG, e você criptografa para múltiplos destinatários:

# Listar chaves disponíveis
gpg --list-keys

# Criptografar para um ou mais fingerprints
sops encrypt \
    --pgp "FP_PESSOA_1,FP_PESSOA_2,FP_PESSOA_3" \
    .env

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    pgp: "FP_PESSOA_1,FP_PESSOA_2,FP_PESSOA_3"

Quando alguém entra ou sai do time, você adiciona/remove o fingerprint e re-criptografa:

# Adicionar novo membro
sops updatekeys .env

Vantagem: zero dependência de cloud. Desvantagem: gestão manual de chaves e distribuição.

age (moderno, simples)

Substituto moderno do GPG, mais simples de usar:

# Gerar chave
age-keygen -o key.txt
# Output: public key: age1xxxxxxx...

# Criptografar
sops encrypt --age "age1xxxxxxx..." .env

# Decriptar
export SOPS_AGE_KEY_FILE=key.txt
sops decrypt .env

Recomendado para projetos pessoais ou times pequenos que não querem a complexidade do GPG.

Múltiplos backends simultaneamente

Você pode combinar backends — útil para times distribuídos entre clouds ou para redundância:

# .sops.yaml — qualquer uma das chaves pode decriptar
creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"
    gcp_kms: "projects/meu-projeto/locations/global/keyRings/sops/cryptoKeys/sops-key"
    pgp: "FP_DO_ADMIN"

Isso garante que se um provider ficar indisponível, você ainda tem acesso via outro backend.

Qual escolher?

Conclusão

O SOPS com KMS resolve o problema de secrets com um workflow simples:

1. Criptografe — sops encrypt .env
2. Commite — o arquivo criptografado vai para o repositório
3. Edite — sops edit .env quando precisar alterar
4. Use — sops exec-env .env "comando" para injetar sem expor

Sem servidores extras, sem vault para manter, sem senhas compartilhadas. Quem tem acesso IAM à chave KMS consegue trabalhar. Quem não tem, vê apenas valores criptografados.

Para projetos que já estão na AWS, é a forma mais simples de sair do .env em texto plano para algo seguro e auditável.

Referências

• SOPS - GitHub
• SOPS Documentation
• AWS KMS Developer Guide
• age encryption

The Problem

GitHub Actions managed runners work fine for small projects, but in production scenarios you hit limitations:

• Fixed hardware — standard Linux runners offer only 4 vCPUs and 16GB RAM. If your workflow builds heavy images, runs integration tests in parallel or needs more memory for compilation, you’re stuck with what GitHub offers
• High cost with execution minutes on private repositories
• Lack of control over the environment (tool versions, internal dependencies)
• Latency when pulling heavy images from private registries
• Security — jobs running on shared infrastructure without access to your VPC

With self-hosted runners on EKS, you choose the machine. Need CPU for compilation? Use c6i.2xlarge. Memory-heavy workflow? Use r6i.xlarge. And with node groups separated by workload type, each pipeline runs on ideal hardware without paying for idle resources.

The solution: run your own runners inside the Kubernetes cluster on AWS, with autoscaling based on real job demand.

TL;DR (Architecture Summary)

GitHub Actions (webhook) → ARC Controller → Scale Set → Runner Pods (EKS)
                                                              ↓
                                                    Custom image (ECR)
                                                              ↓
                                                    CronJob renews ECR credentials every 5h

Stack:

• EKS — Kubernetes cluster on AWS
• ARC — Actions Runner Controller (native autoscaling)
• ECR — Private registry for custom runner image
• Helm — release management
• SOPS — secrets encryption with KMS

Table of Contents

• Prerequisites
• Architecture
• Step 1: Custom Runner Image
• Step 2: Push to ECR
• Step 3: Install the ARC Controller
• Step 4: Configure the Runner Scale Set
• Step 5: Automatic ECR Credential Renewal
• Step 6: Automation with Script
• Using the Runners in Workflows
• Troubleshooting
• Conclusion

Prerequisites

Before starting, you need:

• EKS cluster running with kubectl configured
• Helm 3 installed
• AWS CLI authenticated with ECR permissions
• GitHub PAT (Personal Access Token) with admin:org or repo scope
• SOPS configured with KMS to manage secrets (optional, but recommended)

# Verify cluster connection
kubectl get nodes

# If connection error, update kubeconfig
aws eks update-kubeconfig --region us-east-1 --name your-eks-cluster

Architecture

┌─────────────────────────────────────────────────────────┐
│                        AWS (EKS)                        │
│                                                         │
│  ┌──────────────────┐    ┌───────────────────────────┐  │
│  │  arc-systems ns  │    │     arc-runners ns        │  │
│  │                  │    │                           │  │
│  │  ARC Controller  │───▶│  Runner Scale Set        │  │
│  │  (manages pods)  │    │  ├─ runner-repo-1        │  │
│  │                  │    │  ├─ runner-repo-2        │  │
│  └──────────────────┘    │  └─ runner-org           │  │
│                          │                           │  │
│                          │  CronJob ECR (5h)        │  │
│                          │  (renews docker secret)   │  │
│                          └───────────────────────────┘  │
│                                                         │
│  ┌──────────────────┐                                   │
│  │       ECR        │                                   │
│  │ my-app-github-     │◀── Custom image                   │
│  │ action:latest    │    (tools + dependencies)         │
│  └──────────────────┘                                   │
└─────────────────────────────────────────────────────────┘
         ▲
         │ webhooks (job queued/completed)
         │
┌────────┴────────┐
│  GitHub Actions  │
│  (your repos)    │
└─────────────────┘

The flow works like this:

1. A workflow is triggered on GitHub
2. GitHub sends a webhook to the ARC Controller
3. The Controller scales the Runner Scale Set (creates pods)
4. The pod runs the job using the custom ECR image
5. When finished, the pod is destroyed (scale to zero)

Step 1: Custom Runner Image

The base GitHub Actions Runner image is minimal. To run your pipelines, you probably need additional tools.

Dockerfile

FROM ghcr.io/actions/actions-runner:latest
USER root

RUN apt-get update && apt-get install -y \
    git gcc make wget curl jq netcat-openbsd

RUN chown root:runner -R /opt/ && chmod g+w /opt

# Install the same toolset used in GitHub hosted runners (Ubuntu 24.04)
RUN wget https://raw.githubusercontent.com/actions/runner-images/main/images/ubuntu/toolsets/toolset-2404.json
RUN APT_PACKAGES=$(cat toolset-2404.json | jq -r \
    '.apt | [.vital_packages[], .common_packages[], .cmd_packages[]] | del(.[] | select(. == "lib32z1" or . == "netcat")) | join(" ")') \
    && apt-get update && apt-get install -y --no-install-recommends ${APT_PACKAGES}

USER runner

The strategy here is to reuse the official toolset from GitHub for Ubuntu 24.04 runners. This ensures compatibility with most Actions that expect pre-installed tools (like zip, unzip, python3, etc).

Local build to test

docker build -t my-github-runner --pull --no-cache .

Step 2: Push to ECR

Publish the image to your private registry:

# Variables
ECR_REGISTRY="xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com"
ECR_REPOSITORY="my-github-runner"

# Authenticate with ECR
aws ecr get-login-password --region us-east-1 | \
    docker login --username AWS --password-stdin $ECR_REGISTRY

# Tag and push
docker tag my-github-runner:latest $ECR_REGISTRY/$ECR_REPOSITORY:latest
docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest

If the ECR repository doesn’t exist yet:

aws ecr create-repository \
    --repository-name my-github-runner \
    --region us-east-1

Step 3: Install the ARC Controller

The ARC Controller is the central component that receives webhooks from GitHub and manages the runner pod lifecycle.

NAMESPACE="arc-systems"
INSTALLATION_NAME="arc"

helm install $INSTALLATION_NAME \
    --namespace $NAMESPACE \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

Verify the controller is running:

kubectl get pods -n arc-systems

Expected output:

NAME                                     READY   STATUS    RESTARTS   AGE
arc-gha-runner-scale-set-controller-xxx  1/1     Running   0          30s

Step 4: Configure the Runner Scale Set

This is where we configure the runners that will execute jobs. Each Scale Set can be associated with a repository or organization.

Values file (values.yml) — relevant parts

The complete file with all available options is in the official chart documentation. Here I highlight the essentials:

githubConfigUrl: "https://github.com/your-org/your-repo"
githubConfigSecret:
  github_token: ""

maxRunners: 10
minRunners: 0

containerMode:
  type: "dind"

The most important part is the pod template, where you define image, node placement and ECR access:

template:
  spec:
    activeDeadlineSeconds: 3000
    nodeSelector:
      intent: "ci-jobs"
    tolerations:
      - key: "ci-xlarge"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"
    containers:
      - name: runner
        image: xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/my-github-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
    imagePullSecrets:
      - name: ecr-registry-credentials

Key configuration points

Install the Runner Scale Set

INSTALLATION_NAME="runner-your-repo"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/your-org/your-repo"

helm install "$INSTALLATION_NAME" \
    --namespace "$NAMESPACE" \
    --create-namespace \
    --values values.yml \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Tip: To avoid leaving GITHUB_PAT in plain text, use SOPS with AWS KMS to encrypt your secret files.

Step 5: Automatic ECR Credential Renewal

ECR tokens expire every 12 hours. Without automatic renewal, your runners will fail when trying to pull the image.

The solution is a CronJob that runs every 5 hours and recreates the docker-registry secret:

The CronJob — the central piece

The job uses alpine/k8s (which already has aws CLI and kubectl) to obtain a new token and recreate the secret:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: ecr-registry-helper
  namespace: arc-runners
spec:
  schedule: "0 */5 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: sa-health-check
          containers:
          - name: ecr-registry-helper
            image: alpine/k8s:1.27.15
            envFrom:
              - secretRef:
                  name: ecr-registry-helper-secrets
              - configMapRef:
                  name: ecr-registry-helper-cm
            command:
              - /bin/bash
              - -c
              - |-
                ECR_TOKEN=$(aws ecr get-login-password --region ${AWS_REGION})
                kubectl delete secret --ignore-not-found $DOCKER_SECRET_NAME -n arc-runners
                kubectl create secret docker-registry $DOCKER_SECRET_NAME \
                  --docker-server=https://${AWS_ACCOUNT}.dkr.ecr.${AWS_REGION}.amazonaws.com \
                  --docker-username=AWS \
                  --docker-password="${ECR_TOKEN}" \
                  --namespace=arc-runners
          restartPolicy: Never

The CronJob needs a ServiceAccount with minimal permission to delete and create the specific secret:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: arc-runners
  name: role-ecr-secret-renewal
rules:
- apiGroups: [""]
  resources: ["secrets"]
  resourceNames: ["ecr-registry-credentials"]
  verbs: ["delete"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["create"]

AWS credentials are stored in a separate Secret (ecr-registry-helper-secrets) with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_ACCOUNT.

Apply and verify

# Apply all resources
kubectl apply -f cronjob.yaml

# Verify the CronJob
kubectl get cronjob -n arc-runners

# Test manually (without waiting for the schedule)
kubectl create job --from=cronjob/ecr-registry-helper ecr-test -n arc-runners

# View logs
kubectl logs -n arc-runners -l job-name=ecr-test -f

Why the RBAC is minimal

The Role grants only delete on the specific secret ecr-registry-credentials and generic create — the bare minimum needed for the delete/create cycle. No extra permissions.

Step 6: Automation with Script

When you have multiple runners (one per repository), manually updating each one is impractical. This script automates the entire flow:

#!/bin/bash
set -e

ECR_REGISTRY="xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com"
ECR_REPOSITORY="my-github-runner"
IMAGE_TAG="latest"
AWS_REGION="us-east-1"
NAMESPACE="arc-runners"

# 1. Authenticate with ECR
echo "Authenticating with ECR..."
aws ecr get-login-password --region $AWS_REGION | \
    docker login --username AWS --password-stdin $ECR_REGISTRY

# 2. Build and push image
echo "Building Docker image..."
docker build -t my-github-runner --pull --no-cache .
docker tag my-github-runner:latest $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

# 3. Update ARC controller
echo "Updating ARC controller..."
helm upgrade --install arc \
    --namespace arc-systems \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

# 4. Update all runners
RELEASES=$(helm list -n "$NAMESPACE" --short)

for RELEASE in $RELEASES; do
    echo "  → Updating release: $RELEASE"
    helm upgrade --install "$RELEASE" \
        --namespace "$NAMESPACE" \
        --reuse-values \
        --set githubConfigSecret.github_token="${GITHUB_PAT}" \
        oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
done

# 5. Summary
echo ""
echo "Summary:"
helm list -n arc-runners -o json | \
    jq -r '["NAME","REVISION","APP_VERSION"], (.[] | [.name, (.revision|tostring), .app_version]) | @tsv' | \
    column -t

Execute with secrets via SOPS:

sops exec-env .env "./update-all-runners.sh"

Using the Runners in Workflows

After everything is configured, usage is simple. In your workflow, reference the runner scale set name:

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: runner-your-repo  # helm release name
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: |
          docker build -t app .
          docker run app npm test

The runs-on must match the Helm installation name (the INSTALLATION_NAME used in helm install).

Runner per organization vs per repository

For organizations, the PAT needs the admin:org scope.

Troubleshooting

Error: kubernetes cluster unreachable

Error: kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp 127.0.0.1:8080: connect: connection refused

Solution: Update kubeconfig:

aws eks update-kubeconfig --region us-east-1 --name your-eks-cluster

Runners not showing up on GitHub

# Verify controller is running
kubectl get pods -n arc-systems

# Check controller logs
kubectl logs -n arc-systems -l app.kubernetes.io/name=gha-runner-scale-set-controller

# Verify listener is active
kubectl get pods -n arc-runners

Pods with ImagePullBackOff

The ECR secret probably expired:

# Force manual renewal
kubectl create job --from=cronjob/ecr-registry-helper ecr-renew-now -n arc-runners

# Verify secret exists
kubectl get secret ecr-registry-credentials -n arc-runners

Stuck jobs

The activeDeadlineSeconds: 3000 in the template kills pods after 50 minutes. To clean up manually:

# List old pods
kubectl get pods -n arc-runners --sort-by=.metadata.creationTimestamp

# Delete stuck pods
kubectl delete pod <pod-name> -n arc-runners

Check Helm releases

helm list -n arc-systems   # controller
helm list -n arc-runners   # runners

Costs: Self-Hosted vs Managed

For teams with high CI/CD volume (>5000 min/month) or workflows requiring specific hardware, self-hosted on EKS is generally cheaper and faster.

Choosing instance type by workload

The big advantage is being able to direct each job type to appropriate hardware using nodeSelector and tolerations:

On EKS, you create separate node groups with labels and taints, and each runner scale set points to the ideal node group:

# Runner for heavy builds (CPU)
template:
  spec:
    nodeSelector:
      intent: "ci-cpu-heavy"
    tolerations:
      - key: "ci-cpu-heavy"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"

# Runner for database tests (memory)
template:
  spec:
    nodeSelector:
      intent: "ci-memory"
    tolerations:
      - key: "ci-memory"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"

This way, a heavy docker build doesn’t compete for resources with integration tests, and you don’t pay for 32GB of RAM on jobs that only need CPU.

Conclusion

With this architecture you have:

• Scale to zero — no costs when no jobs are running
• Autoscaling — ARC creates pods on demand based on job queue
• Custom image — all tools your pipelines need, pre-installed
• Security — runners inside the VPC, with access to internal resources
• Automation — ECR credentials automatically renewed, batch updates via script

The initial setup has moderate complexity, but once running, maintenance is minimal. The update script and credentials CronJob cover the two points that cause the most day-to-day issues.

Next step: Clone this setup, adapt the variables for your environment and start with a runner for a test repository. Then just replicate for the rest.

References

• Actions Runner Controller (ARC)
• ARC Helm Charts
• GitHub Actions Self-Hosted Runners
• Amazon EKS Documentation
• SOPS - Secrets OPerationS

O Problema

Os runners managed do GitHub Actions funcionam bem para projetos pequenos, mas em cenários de produção você esbarra em limitações:

• Hardware fixo — runners Linux padrão oferecem apenas 4 vCPUs e 16GB RAM. Se seu workflow faz build de imagens pesadas, roda testes de integração em paralelo ou precisa de mais memória para compilação, você fica refém do que o GitHub oferece
• Custo elevado com minutos de execução em repositórios privados
• Falta de controle sobre o ambiente (versões de ferramentas, dependências internas)
• Latência ao baixar imagens pesadas de registries privados
• Segurança — jobs rodando em infraestrutura compartilhada sem acesso à sua VPC

Com self-hosted runners no EKS, você escolhe a máquina. Precisa de CPU para compilação? Use c6i.2xlarge. Workflow pesado em memória? Use r6i.xlarge. E com node groups separados por tipo de workload, cada pipeline roda no hardware ideal sem pagar por recursos ociosos.

A solução: rodar seus próprios runners dentro do cluster Kubernetes na AWS, com autoscaling baseado na demanda real de jobs.

TL;DR (Arquitetura Resumida)

GitHub Actions (webhook) → ARC Controller → Scale Set → Runner Pods (EKS)
                                                              ↓
                                                    Imagem customizada (ECR)
                                                              ↓
                                                    CronJob renova credenciais ECR a cada 5h

Stack:

• EKS — cluster Kubernetes na AWS
• ARC — Actions Runner Controller (autoscaling nativo)
• ECR — Registry privado para imagem customizada dos runners
• Helm — gerenciamento de releases
• SOPS — criptografia de secrets com KMS

Índice

• Pré-requisitos
• Arquitetura
• Passo 1: Imagem Customizada do Runner
• Passo 2: Push para o ECR
• Passo 3: Instalar o ARC Controller
• Passo 4: Configurar o Runner Scale Set
• Passo 5: Renovação Automática de Credenciais ECR
• Passo 6: Automação com Script
• Usando os Runners nos Workflows
• Troubleshooting
• Conclusão

Pré-requisitos

Antes de começar, você precisa ter:

• Cluster EKS rodando com kubectl configurado
• Helm 3 instalado
• AWS CLI autenticada com permissões para ECR
• GitHub PAT (Personal Access Token) com scope admin:org ou repo
• SOPS configurado com KMS para gerenciar secrets (opcional, mas recomendado)

# Verificar conexão com o cluster
kubectl get nodes

# Se der erro de conexão, atualize o kubeconfig
aws eks update-kubeconfig --region us-east-1 --name seu-cluster-eks

Arquitetura

┌─────────────────────────────────────────────────────────┐
│                        AWS (EKS)                        │
│                                                         │
│  ┌──────────────────┐    ┌───────────────────────────┐  │
│  │  arc-systems ns  │    │     arc-runners ns        │  │
│  │                  │    │                           │  │
│  │  ARC Controller  │───▶│  Runner Scale Set        │  │
│  │  (gerencia pods) │    │  ├─ runner-repo-1        │  │
│  │                  │    │  ├─ runner-repo-2        │  │
│  └──────────────────┘    │  └─ runner-org           │  │
│                          │                           │  │
│                          │  CronJob ECR (5h)        │  │
│                          │  (renova docker secret)   │  │
│                          └───────────────────────────┘  │
│                                                         │
│  ┌──────────────────┐                                   │
│  │       ECR        │                                   │
│  │ my-app-github-     │◀── Imagem customizada             │
│  │ action:latest    │    (tools + dependências)         │
│  └──────────────────┘                                   │
└─────────────────────────────────────────────────────────┘
         ▲
         │ webhooks (job queued/completed)
         │
┌────────┴────────┐
│  GitHub Actions  │
│  (seus repos)    │
└─────────────────┘

O fluxo funciona assim:

1. Um workflow é disparado no GitHub
2. O GitHub envia um webhook para o ARC Controller
3. O Controller escala o Runner Scale Set (cria pods)
4. O pod roda o job usando a imagem customizada do ECR
5. Ao terminar, o pod é destruído (scale to zero)

Passo 1: Imagem Customizada do Runner

A imagem base do GitHub Actions Runner é mínima. Para rodar seus pipelines, você provavelmente precisa de ferramentas adicionais.

Dockerfile

FROM ghcr.io/actions/actions-runner:latest
USER root

RUN apt-get update && apt-get install -y \
    git gcc make wget curl jq netcat-openbsd

RUN chown root:runner -R /opt/ && chmod g+w /opt

# Instala o mesmo toolset usado nos runners hosted do GitHub (Ubuntu 24.04)
RUN wget https://raw.githubusercontent.com/actions/runner-images/main/images/ubuntu/toolsets/toolset-2404.json
RUN APT_PACKAGES=$(cat toolset-2404.json | jq -r \
    '.apt | [.vital_packages[], .common_packages[], .cmd_packages[]] | del(.[] | select(. == "lib32z1" or . == "netcat")) | join(" ")') \
    && apt-get update && apt-get install -y --no-install-recommends ${APT_PACKAGES}

USER runner

A estratégia aqui é reutilizar o toolset oficial do GitHub para runners Ubuntu 24.04. Isso garante compatibilidade com a maioria dos Actions que esperam ferramentas pré-instaladas (como zip, unzip, python3, etc).

Build local para testar

docker build -t my-github-runner --pull --no-cache .

Passo 2: Push para o ECR

Publique a imagem no seu registry privado:

# Variáveis
ECR_REGISTRY="xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com"
ECR_REPOSITORY="my-github-runner"

# Autenticar no ECR
aws ecr get-login-password --region us-east-1 | \
    docker login --username AWS --password-stdin $ECR_REGISTRY

# Tag e push
docker tag my-github-runner:latest $ECR_REGISTRY/$ECR_REPOSITORY:latest
docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest

Se o repositório ECR ainda não existir:

aws ecr create-repository \
    --repository-name my-github-runner \
    --region us-east-1

Passo 3: Instalar o ARC Controller

O ARC Controller é o componente central que recebe webhooks do GitHub e gerencia o ciclo de vida dos runner pods.

NAMESPACE="arc-systems"
INSTALLATION_NAME="arc"

helm install $INSTALLATION_NAME \
    --namespace $NAMESPACE \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

Verifique se o controller está rodando:

kubectl get pods -n arc-systems

Saída esperada:

NAME                                     READY   STATUS    RESTARTS   AGE
arc-gha-runner-scale-set-controller-xxx  1/1     Running   0          30s

Passo 4: Configurar o Runner Scale Set

Aqui é onde configuramos os runners que vão executar os jobs. Cada Scale Set pode ser associado a um repositório ou organização.

Arquivo de valores (values.yml) — partes relevantes

O arquivo completo com todas as opções disponíveis está na documentação oficial do chart. Aqui destaco o essencial:

githubConfigUrl: "https://github.com/sua-org/seu-repo"
githubConfigSecret:
  github_token: ""

maxRunners: 10
minRunners: 0

containerMode:
  type: "dind"

A parte mais importante é o template do pod, onde você define imagem, node placement e acesso ao ECR:

template:
  spec:
    activeDeadlineSeconds: 3000
    nodeSelector:
      intent: "ci-jobs"
    tolerations:
      - key: "ci-xlarge"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"
    containers:
      - name: runner
        image: xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/my-github-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
    imagePullSecrets:
      - name: ecr-registry-credentials

Pontos importantes da configuração

Instalar o Runner Scale Set

INSTALLATION_NAME="runner-seu-repo"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/sua-org/seu-repo"

helm install "$INSTALLATION_NAME" \
    --namespace "$NAMESPACE" \
    --create-namespace \
    --values values.yml \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Dica: Para não deixar o GITHUB_PAT em texto plano, use SOPS com AWS KMS para criptografar seus arquivos de secrets.

Passo 5: Renovação Automática de Credenciais ECR

Os tokens do ECR expiram a cada 12 horas. Sem renovação automática, seus runners vão falhar ao tentar fazer pull da imagem.

A solução é um CronJob que roda a cada 5 horas e recria o secret docker-registry:

O CronJob — a parte central

O job usa alpine/k8s (que já tem aws CLI e kubectl) para obter um novo token e recriar o secret:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: ecr-registry-helper
  namespace: arc-runners
spec:
  schedule: "0 */5 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: sa-health-check
          containers:
          - name: ecr-registry-helper
            image: alpine/k8s:1.27.15
            envFrom:
              - secretRef:
                  name: ecr-registry-helper-secrets
              - configMapRef:
                  name: ecr-registry-helper-cm
            command:
              - /bin/bash
              - -c
              - |-
                ECR_TOKEN=$(aws ecr get-login-password --region ${AWS_REGION})
                kubectl delete secret --ignore-not-found $DOCKER_SECRET_NAME -n arc-runners
                kubectl create secret docker-registry $DOCKER_SECRET_NAME \
                  --docker-server=https://${AWS_ACCOUNT}.dkr.ecr.${AWS_REGION}.amazonaws.com \
                  --docker-username=AWS \
                  --docker-password="${ECR_TOKEN}" \
                  --namespace=arc-runners
          restartPolicy: Never

O CronJob precisa de um ServiceAccount com permissão mínima para deletar e criar o secret específico:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: arc-runners
  name: role-ecr-secret-renewal
rules:
- apiGroups: [""]
  resources: ["secrets"]
  resourceNames: ["ecr-registry-credentials"]
  verbs: ["delete"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["create"]

As credenciais AWS ficam em um Secret separado (ecr-registry-helper-secrets) com AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_ACCOUNT.

Aplicar e verificar

# Aplicar todos os recursos
kubectl apply -f cronjob.yaml

# Verificar o CronJob
kubectl get cronjob -n arc-runners

# Testar manualmente (sem esperar o schedule)
kubectl create job --from=cronjob/ecr-registry-helper ecr-test -n arc-runners

# Ver logs
kubectl logs -n arc-runners -l job-name=ecr-test -f

Por que o RBAC é mínimo

O Role concede apenas delete no secret específico ecr-registry-credentials e create genérico — o mínimo necessário para o ciclo delete/create. Nenhuma permissão extra.

Passo 6: Automação com Script

Quando você tem múltiplos runners (um por repositório), atualizar manualmente cada um é inviável. Este script automatiza todo o fluxo:

#!/bin/bash
set -e

ECR_REGISTRY="xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com"
ECR_REPOSITORY="my-github-runner"
IMAGE_TAG="latest"
AWS_REGION="us-east-1"
NAMESPACE="arc-runners"

# 1. Autenticar no ECR
echo "Authenticating with ECR..."
aws ecr get-login-password --region $AWS_REGION | \
    docker login --username AWS --password-stdin $ECR_REGISTRY

# 2. Build e push da imagem
echo "Building Docker image..."
docker build -t my-github-runner --pull --no-cache .
docker tag my-github-runner:latest $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

# 3. Atualizar ARC controller
echo "Updating ARC controller..."
helm upgrade --install arc \
    --namespace arc-systems \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

# 4. Atualizar todos os runners
RELEASES=$(helm list -n "$NAMESPACE" --short)

for RELEASE in $RELEASES; do
    echo "  → Updating release: $RELEASE"
    helm upgrade --install "$RELEASE" \
        --namespace "$NAMESPACE" \
        --reuse-values \
        --set githubConfigSecret.github_token="${GITHUB_PAT}" \
        oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
done

# 5. Resumo
echo ""
echo "Summary:"
helm list -n arc-runners -o json | \
    jq -r '["NAME","REVISION","APP_VERSION"], (.[] | [.name, (.revision|tostring), .app_version]) | @tsv' | \
    column -t

Execute com secrets via SOPS:

sops exec-env .env "./update-all-runners.sh"

Usando os Runners nos Workflows

Depois de tudo configurado, usar é simples. No seu workflow, referencie o nome do runner scale set:

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: runner-seu-repo  # nome do helm release
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: |
          docker build -t app .
          docker run app npm test

O runs-on deve corresponder ao nome da instalação Helm (o INSTALLATION_NAME usado no helm install).

Runner por organização vs por repositório

Para organizações, o PAT precisa do scope admin:org.

Troubleshooting

Erro: kubernetes cluster unreachable

Error: kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp 127.0.0.1:8080: connect: connection refused

Solução: Atualize o kubeconfig:

aws eks update-kubeconfig --region us-east-1 --name seu-cluster-eks

Runners não aparecem no GitHub

# Verificar se o controller está rodando
kubectl get pods -n arc-systems

# Verificar logs do controller
kubectl logs -n arc-systems -l app.kubernetes.io/name=gha-runner-scale-set-controller

# Verificar se o listener está ativo
kubectl get pods -n arc-runners

Pods com ImagePullBackOff

O secret do ECR provavelmente expirou:

# Forçar renovação manual
kubectl create job --from=cronjob/ecr-registry-helper ecr-renew-now -n arc-runners

# Verificar se o secret existe
kubectl get secret ecr-registry-credentials -n arc-runners

Jobs travados (stuck)

O activeDeadlineSeconds: 3000 no template mata pods após 50 minutos. Para limpar manualmente:

# Listar pods antigos
kubectl get pods -n arc-runners --sort-by=.metadata.creationTimestamp

# Deletar pods travados
kubectl delete pod <pod-name> -n arc-runners

Verificar releases Helm

helm list -n arc-systems   # controller
helm list -n arc-runners   # runners

Custos: Self-Hosted vs Managed

Para times com alto volume de CI/CD (>5000 min/mês) ou workflows que exigem hardware específico, self-hosted no EKS geralmente sai mais barato e mais rápido.

Escolhendo o tipo de instância por workload

A grande vantagem é poder direcionar cada tipo de job para o hardware adequado usando nodeSelector e tolerations:

No EKS, você cria node groups separados com labels e taints, e cada runner scale set aponta para o node group ideal:

# Runner para builds pesados (CPU)
template:
  spec:
    nodeSelector:
      intent: "ci-cpu-heavy"
    tolerations:
      - key: "ci-cpu-heavy"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"

# Runner para testes com banco (memória)
template:
  spec:
    nodeSelector:
      intent: "ci-memory"
    tolerations:
      - key: "ci-memory"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"

Assim, um docker build pesado não compete por recursos com testes de integração, e você não paga por 32GB de RAM em jobs que só precisam de CPU.

Conclusão

Com essa arquitetura você tem:

• Scale to zero — sem custos quando não há jobs rodando
• Autoscaling — o ARC cria pods sob demanda baseado na fila de jobs
• Imagem customizada — todas as ferramentas que seus pipelines precisam, pré-instaladas
• Segurança — runners dentro da VPC, com acesso a recursos internos
• Automação — credenciais ECR renovadas automaticamente, updates em batch via script

O setup inicial tem complexidade moderada, mas uma vez rodando, a manutenção é mínima. O script de update e o CronJob de credenciais cobrem os dois pontos que mais causam problemas no dia a dia.

Próximo passo: Clone este setup, adapte as variáveis para seu ambiente e comece com um runner para um repositório de teste. Depois é só replicar para os demais.

Referências

• Actions Runner Controller (ARC)
• ARC Helm Charts
• GitHub Actions Self-Hosted Runners
• Amazon EKS Documentation
• SOPS - Secrets OPerationS

Friday, 5 PM. You finish that feature, run a satisfying git add ., commit, push. Go grab a coffee. On the way back to your computer, that sinking feeling: “wait… was the .env in staged?”. You open GitHub, check the commit and there it is — AWS_SECRET_ACCESS_KEY in plain text, published to the world. The rest of Friday becomes a security incident: revoke keys, rotate credentials, notify the team, pray no one saw it.

If you’ve lived through this (or live in fear of it), SOPS is for you. It lets you commit your secret files encrypted directly into the repository. No fear. No incident. No ruined Friday.

The Problem

Every application has secrets: API tokens, database credentials, private keys. The challenge is how to share them with the team without:

• Committing .env in plain text to the repository
• Relying on someone sending credentials via Slack/email
• Losing access when someone leaves the team
• Maintaining a complex vault for small/medium projects

SOPS (Secrets OPerationS) solves this: it encrypts only the values in your secret files, keeping the keys readable. Combined with a KMS (AWS, GCP, Azure) or GPG, anyone authorized can decrypt — without sharing passwords.

TL;DR

# Install SOPS
# https://github.com/getsops/sops/releases

# Configure the KMS key
export SOPS_KMS_ARN="arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/your-key"

# Encrypt an existing file
sops encrypt .env > .env.enc

# Edit secrets (decrypts, opens editor, re-encrypts on save)
sops edit .env

# Use secrets as environment variables (no decrypted file on disk)
sops exec-env .env "helm install ..."

Table of Contents

• What is SOPS
• Installation
• Initial Configuration
• Daily Workflow
• Supported Formats
• Encryption Backends
• Using with Helm and Kubernetes
• Best Practices
• Conclusion

What is SOPS

SOPS is a tool originally from Mozilla (now maintained by the CNCF) that encrypts configuration files. The differentiator:

# Original file (.env)
GITHUB_PAT=ghp_abc123xyz789
AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCY
DB_PASSWORD=super-secret-123

# After encrypting with SOPS
GITHUB_PAT=ENC[AES256_GCM,data:k8vM2n...,type:str]
AWS_SECRET_KEY=ENC[AES256_GCM,data:pQ7xR...,type:str]
DB_PASSWORD=ENC[AES256_GCM,data:mN3kL...,type:str]

The keys (GITHUB_PAT, AWS_SECRET_KEY) remain readable — you know what the file contains without decrypting. Only the values are encrypted.

This means:

• The file can be safely committed to the repository
• Code review can see which secrets were added/removed
• git diff shows structural changes without exposing values

Why Use a KMS (Key Management Service)

SOPS supports several backends. Cloud KMS services (AWS, GCP, Azure) share advantages over GPG/age:

• IAM-based access control — who can decrypt is controlled by cloud provider policies
• Auditing — every key usage is logged (CloudTrail, Cloud Audit Logs)
• Automatic rotation — the provider rotates the key without breaking existing files
• No shared secret — no need to distribute a private key across the team

If you don’t use any cloud provider, GPG and age work perfectly — they just require more manual key management.

Installation

SOPS

Download the binary from the releases page:

# Linux (amd64)
curl -LO https://github.com/getsops/sops/releases/download/v3.9.4/sops-v3.9.4.linux.amd64
mv sops-v3.9.4.linux.amd64 /usr/local/bin/sops
chmod +x /usr/local/bin/sops

# macOS (via Homebrew)
brew install sops

# Verify
sops --version

AWS CLI

You need the AWS CLI configured with credentials that have access to the KMS key:

aws sts get-caller-identity  # Verify authentication

Initial Configuration

1. Create (or identify) the KMS key

If you already have a KMS key, get the ARN or alias. If not:

aws kms create-key --description "SOPS encryption key"

# Create an alias for convenience
aws kms create-alias \
    --alias-name alias/sops-key \
    --target-key-id <returned-key-id>

2. Export the ARN

export SOPS_KMS_ARN="arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"

3. Create the .sops.yaml file (optional, recommended)

At the project root, create a .sops.yaml so you don’t need to pass the ARN every time:

creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"
  - path_regex: secrets\.ya?ml$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"

With this, any .env or secrets.yml file will automatically be encrypted with the correct key.

Daily Workflow

Encrypt a file for the first time

# If .sops.yaml is configured:
sops encrypt .env > .env.enc
mv .env.enc .env

# Or specifying the key manually:
sops encrypt --kms "arn:aws:kms:..." .env > .env.enc

Edit secrets

The most used command. Decrypts, opens in editor, re-encrypts on save:

sops edit .env

Uses the editor defined in $EDITOR (vim, nano, code, etc).

Use secrets without a file on disk

exec-env injects secrets as environment variables in a subprocess — nothing stays in plain text on disk:

# Open a shell with all variables available
sops exec-env .env "bash"

# Execute a specific command
sops exec-env .env "helm upgrade --set token=\$GITHUB_PAT ..."

Decrypt to stdout (debug)

sops decrypt .env

View diff between versions

Since keys are readable, git diff works normally to show which secrets were added or removed.

Supported Formats

SOPS works with multiple formats:

YAML Example

# secrets.yml (after SOPS encrypt)
database:
    host: ENC[AES256_GCM,data:mQ2x...,type:str]
    password: ENC[AES256_GCM,data:k9Lp...,type:str]
    port: 5432  # non-sensitive values can be excluded from encryption
sops:
    kms:
        - arn: arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key
    version: 3.9.4

Encrypt only specific fields

Use --encrypted-regex to encrypt only fields containing “password”, “secret”, “token”, etc:

sops encrypt --encrypted-regex '^(password|secret|token)$' config.yml

Using with Helm and Kubernetes

The most common use case: pass secrets to helm install without exposing them.

Pattern with exec-env

# Encrypted .env contains GITHUB_PAT=ghp_xxx
sops exec-env .env "helm install runner \
    --set githubConfigSecret.github_token=\$GITHUB_PAT \
    --namespace arc-runners \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set"

Pattern with script

#!/bin/bash
# update-runners.sh — run via: sops exec-env .env "./update-runners.sh"

helm upgrade --install runner \
    --namespace arc-runners \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

sops exec-env .env "./update-runners.sh"

Sensitive values in a values file

If you prefer keeping everything in YAML:

# Create values-secrets.yml with tokens
sops edit values-secrets.yml

# Use decrypted inline with helm
sops decrypt values-secrets.yml | helm install runner \
    --namespace arc-runners \
    -f - \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Best Practices

1. Commit the encrypted file

# .gitignore
# DON'T ignore .env if it's encrypted with SOPS
# Only ignore if it's plain text:
# .env

The whole point of SOPS is being able to version secrets safely. If the file is encrypted, it should be in the repository.

2. Use .sops.yaml in the project

Prevents someone from forgetting to specify the key and encrypting with the wrong backend.

3. Control access via IAM

{
  "Effect": "Allow",
  "Action": ["kms:Decrypt", "kms:DescribeKey"],
  "Resource": "arn:aws:kms:us-east-1:xxxxxxxxxxxx:key/key-id"
}

Only those who need to decrypt receive kms:Decrypt. Others can see the file structure without accessing the values.

4. Never decrypt to a file

# Bad — creates plain text file on disk
sops decrypt .env > .env.plain

# Good — uses in memory only
sops exec-env .env "command"

5. Add multiple KMS keys

For redundancy or cross-account access:

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key,arn:aws:kms:us-east-1:yyyyyyyyyyyy:alias/sops-backup"

Any of the keys can decrypt the file.

Encryption Backends

SOPS isn’t exclusive to AWS. It supports multiple backends — choose what makes sense for your infrastructure:

AWS KMS

Ideal if your team is already on AWS. Access control via IAM, auditing via CloudTrail.

export SOPS_KMS_ARN="arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"
sops encrypt .env

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"

GCP Cloud KMS

Same concept, for teams on Google Cloud. Control via GCP IAM.

# Create keyring and key (once)
gcloud kms keyrings create sops --location global
gcloud kms keys create sops-key \
    --location global \
    --keyring sops \
    --purpose encryption

# Encrypt
sops encrypt \
    --gcp-kms "projects/my-project/locations/global/keyRings/sops/cryptoKeys/sops-key" \
    .env

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    gcp_kms: "projects/my-project/locations/global/keyRings/sops/cryptoKeys/sops-key"

To decrypt, just have gcloud auth application-default login configured with cloudkms.cryptoKeyVersions.useToDecrypt permission.

Azure Key Vault

For teams on Azure:

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    azure_keyvault: "https://my-vault.vault.azure.net/keys/sops-key/version-id"

GPG/PGP

Works without any cloud provider. Each team member has their GPG key, and you encrypt for multiple recipients:

# List available keys
gpg --list-keys

# Encrypt for one or more fingerprints
sops encrypt \
    --pgp "FP_PERSON_1,FP_PERSON_2,FP_PERSON_3" \
    .env

# .sops.yaml
creation_rules:
  - path_regex: \.env$
    pgp: "FP_PERSON_1,FP_PERSON_2,FP_PERSON_3"

When someone joins or leaves the team, you add/remove the fingerprint and re-encrypt:

# Add new member
sops updatekeys .env

Advantage: zero cloud dependency. Disadvantage: manual key management and distribution.

age (modern, simple)

Modern GPG replacement, simpler to use:

# Generate key
age-keygen -o key.txt
# Output: public key: age1xxxxxxx...

# Encrypt
sops encrypt --age "age1xxxxxxx..." .env

# Decrypt
export SOPS_AGE_KEY_FILE=key.txt
sops decrypt .env

Recommended for personal projects or small teams that don’t want GPG complexity.

Multiple backends simultaneously

You can combine backends — useful for teams distributed across clouds or for redundancy:

# .sops.yaml — any of the keys can decrypt
creation_rules:
  - path_regex: \.env$
    kms: "arn:aws:kms:us-east-1:xxxxxxxxxxxx:alias/sops-key"
    gcp_kms: "projects/my-project/locations/global/keyRings/sops/cryptoKeys/sops-key"
    pgp: "FP_OF_ADMIN"

This ensures that if one provider becomes unavailable, you still have access via another backend.

Which one to choose?

Conclusion

SOPS with KMS solves the secrets problem with a simple workflow:

1. Encrypt — sops encrypt .env
2. Commit — the encrypted file goes to the repository
3. Edit — sops edit .env when you need to change
4. Use — sops exec-env .env "command" to inject without exposing

No extra servers, no vault to maintain, no shared passwords. Whoever has IAM access to the KMS key can work. Whoever doesn’t, sees only encrypted values.

For projects already on AWS, it’s the simplest way to move from plain text .env to something secure and auditable.

References

• SOPS - GitHub
• SOPS Documentation
• AWS KMS Developer Guide
• age encryption

O Problema

Você está debugando código e encontra um bug na linha 42 de um arquivo. As perguntas surgem imediatamente:

• 🤔 Quando essa linha foi modificada pela última vez?
• 👤 Quem fez a mudança?
• 📝 Por que foi alterada (contexto da mudança)?
• 🔍 Qual Pull Request introduziu o problema?

Este guia mostra o workflow simples de investigação, combinando Git e GitHub CLI para rastrear bugs desde a linha problemática até o PR responsável.

TL;DR (Workflow em 3 Passos)

# PASSO 1: Encontrar quando a linha foi modificada
git log -L 42,42:app/models/user.rb

# PASSO 2: Ver detalhes completos do commit suspeito
git show abc1234 --stat

# PASSO 3: Encontrar o PR que contém esse commit
gh pr list --search "abc1234" --state all
# ou se souber que está merged:
gh pr list --search "abc1234" --state merged

💡 Esse workflow permite identificar a origem de bugs em aplicações e entender o contexto completo da mudança.

Índice

• Workflow: Da Linha ao PR
• Passo 1: Rastrear Histórico da Linha
• Passo 2: Analisar o Commit
• Passo 3: Encontrar o Pull Request
• Comandos Complementares de Investigação
• Busca Avançada com git grep
• Boas Práticas
• Aliases Úteis
• Conclusão

Workflow Completo: Da Linha ao PR

Vamos seguir um caso em uma aplicação Rails. Imagine que você encontrou um bug nesta linha do modelo User:

# app/models/user.rb:42
class User < ApplicationRecord
  # ...

  validates :email, format: { with: /@/ }  # Bug: validação muito simplista!

  # ...
end

Essa validação de email só verifica se tem o símbolo @, permitindo emails inválidos como "teste@" ou "@exemplo". Vamos investigar quando e por que foi introduzido.

Cenário

• Arquivo: app/models/user.rb
• Linha: 42
• Problema: Validação de email aceita formatos inválidos
• Impacto: Usuários podem cadastrar emails inválidos no sistema
• Objetivo: Encontrar o PR que introduziu essa validação fraca

Passo 1: Rastrear Histórico da Linha

O comando mais poderoso para investigar uma linha específica é o git log -L. Ele mostra todo o histórico de uma linha, incluindo o código antes e depois de cada mudança.

Comando Principal

git log -L 42,42:app/models/user.rb

O que esse comando faz:

• Mostra todos os commits que modificaram a linha 42 do modelo User
• Exibe o diff (antes/depois) de cada mudança
• Lista autor, data e mensagem do commit

Saída Exemplo

commit abc1234567890
Author: João Silva <joao@example.com>
Date:   Mon Jan 20 14:30:00 2026

    feat: simplifica validação de email no User

diff --git a/app/models/user.rb b/app/models/user.rb
--- a/app/models/user.rb
+++ b/app/models/user.rb
@@ -42,1 +42,1 @@
-  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :email, format: { with: /@/ }  # Simplificado para melhorar performance

🎯 Achamos o culpado! O commit abc1234 substituiu a validação robusta do Rails (URI::MailTo::EMAIL_REGEXP) por uma regex simples que só verifica @.

Variação com Formato Compacto

Para ver apenas os hashes e mensagens:

git log -L 42,42:app/models/user.rb --oneline

Saída:

abc1234 feat: simplifica validação de email no User
def5678 refactor: adiciona validações customizadas

Rastrear Range de Linhas

Se o bug afeta múltiplas linhas próximas (por exemplo, validações relacionadas):

git log -L 40,50:app/models/user.rb

Isso mostra mudanças nas linhas 40 a 50, útil para ver todas as validações do modelo.

Passo 2: Analisar o Commit

Agora que identificamos o commit abc1234, vamos analisar todo o contexto dessa mudança para entender o que foi modificado.

Ver Resumo das Mudanças

git show --stat abc1234

Saída exemplo:

commit abc1234567890
Author: João Silva <joao@example.com>
Date:   Mon Jan 20 14:30:00 2026

    feat: simplifica validação de email no User

 app/models/user.rb           |  2 +-
 app/controllers/users_controller.rb  |  3 +--
 spec/models/user_spec.rb     | 18 ------------------
 3 files changed, 2 insertions(+), 21 deletions(-)

⚠️ Red flags detectados:

• Removeu 18 linhas de specs (spec/models/user_spec.rb)
• Modificou controller também (escopo maior que esperado)
• Mensagem diz “simplifica” (pode ter removido validações importantes)

Ver Diff Completo

Para ver todas as mudanças linha por linha:

git show abc1234

Isso mostra o diff completo de todos os arquivos modificados.

Ver Apenas Arquivos Modificados

git show --name-only abc1234

Saída:

app/models/user.rb
app/controllers/users_controller.rb
spec/models/user_spec.rb

Ver Informações do Autor

git show --format="%an (%ae)%nData: %ad%nMensagem: %s%n%b" --no-patch abc1234

Saída:

João Silva (joao@example.com)
Data: Mon Jan 20 14:30:00 2026
Mensagem: feat: simplifica validação de email no User

Substitui URI::MailTo::EMAIL_REGEXP por validação simples
para melhorar performance do save. Issue #123 reportou
lentidão ao criar usuários em batch.

Benchmarks mostram melhoria de 40% no throughput.

💡 Contexto importante: A mudança foi feita por motivo de performance em operações batch, mas sacrificou a validação correta de emails individuais.

Passo 3: Encontrar o Pull Request

Agora vem a parte crucial: descobrir qual PR contém esse commit. Isso nos dá:

• Discussões da code review
• Contexto completo da mudança
• Outros commits relacionados
• Quem aprovou o PR

Método 1: Buscar PR por Hash do Commit

O GitHub CLI permite buscar PRs que contêm um commit específico:

gh pr list --search "abc1234" --state all

Saída exemplo:

#127  feat: otimiza validação de email no User  feature/faster-validations  MERGED

🎯 Encontramos! O commit está no PR #127.

Método 2: Buscar Apenas PRs Mergeados

Se você sabe que o código já está em produção:

gh pr list --search "abc1234" --state merged

Ver Detalhes Completos do PR

gh pr view 127

Saída exemplo:

feat: otimiza validação de email no User #127
Merged • feature/faster-validations merged into main

  Melhora performance na criação de usuários em batch

  Mudanças:
  - Substitui URI::MailTo::EMAIL_REGEXP por validação simples
  - Remove specs redundantes de formato de email
  - Atualiza UsersController para usar validação client-side

  Performance:
  - Batch create de 1000 users: 45s → 27s (40% mais rápido)
  - Benchmarks no PR comment

  Fixes #123

───────────────────────────────────────
View this pull request on GitHub: https://github.com/empresa/projeto/pull/127

Ver Informações Específicas em JSON

Para análise programática:

gh pr view 127 --json number,title,author,createdAt,mergedAt,reviews,url

Saída JSON:

{
  "number": 127,
  "title": "feat: otimiza validação de email no User",
  "author": "joaosilva",
  "createdAt": "2026-01-20T14:00:00Z",
  "mergedAt": "2026-01-20T16:30:00Z",
  "reviews": [
    {
      "author": "mariasilva",
      "state": "APPROVED"
    }
  ],
  "url": "https://github.com/empresa/projeto/pull/127"
}

Ver Comentários do PR no Terminal

gh pr view 127 --comments

Isso mostra toda a discussão da code review, onde você pode encontrar:

• Questionamentos sobre a mudança
• Decisões tomadas
• Possíveis avisos ignorados

Método Alternativo: Verificar Branches

Se gh não estiver disponível, use Git puro:

# Ver em quais branches o commit está
git branch -a --contains abc1234

# Ver se está na main/master
git branch --contains abc1234 | grep -E "main|master"

Saída:

  main
  remotes/origin/main

Depois busque manualmente no GitHub por commits recentes merged na main.

Resumo do Workflow Completo

Juntando tudo, aqui está o fluxo de investigação de ponta a ponta:

# 1️⃣ DESCOBRIR: Encontrar o commit que modificou a linha
git log -L 42,42:app/models/user.rb --oneline

# Saída: abc1234 feat: otimiza validação de email no User

# 2️⃣ ANALISAR: Ver o que foi alterado no commit
git show --stat abc1234

# Revisar: models, specs, controllers modificados

# 3️⃣ INVESTIGAR: Encontrar o PR que contém o commit
gh pr list --search "abc1234" --state merged

# Saída: #127 feat: otimiza validação de email no User

# 4️⃣ CONTEXTO: Ver detalhes completos do PR
gh pr view 127 --comments

# Ler discussões da code review, benchmarks, trade-offs

O que Você Ganhou

✅ Hash do commit: abc1234 ✅ Autor: João Silva ✅ Data: 20 de janeiro de 2026 ✅ Motivo: Otimizar performance em batch creates (Issue #123) ✅ PR: #127 ✅ Reviewer: Maria Silva (aprovou) ✅ Trade-off: Sacrificou validação robusta por performance ✅ Impacto: Batch de 1000 users 40% mais rápido, mas emails inválidos aceitos

Com essas informações, você pode:

• Reverter o commit se necessário
• Discutir com o autor sobre a decisão
• Criar um PR de fix referenciando o problema original
• Aprender com o erro para futuras code reviews

Comandos Complementares de Investigação

Além do workflow principal, estes comandos são úteis para investigações mais complexas.

Buscar Commits por Mensagem

Encontre commits por palavras-chave:

git log --all --oneline --grep="validation"

# Case-insensitive
git log --all --oneline --grep="validation" -i

# Com regex
git log --all --oneline --grep="^feat:"

Ver Histórico Completo de um Arquivo

Útil para entender a evolução de um model ou controller:

git log --format="%h - %an - %ar: %s" -- app/models/user.rb

Buscar por Código Adicionado/Removido

Encontre quando um método específico foi adicionado ou removido:

git log -S "def email_valid?" --oneline -- app/models/

Isso mostra todos os commits que adicionaram ou removeram o método email_valid? nos models.

Buscar Mudanças em Associations

git log -S "has_many :posts" --oneline -- app/models/user.rb

Rastrear Mudanças em Migrations

git log --oneline -- db/migrate/*users*.rb

Instalando o GitHub CLI

Para usar o workflow completo, você precisa ter o GitHub CLI instalado.

Instalação

# Ubuntu/Debian
sudo apt install gh

# macOS
brew install gh

# Arch Linux
sudo pacman -S github-cli

# Windows (com Chocolatey)
choco install gh

Primeira Configuração

# Fazer login
gh auth login

# Verificar se está autenticado
gh auth status

Comandos Adicionais Úteis do GitHub CLI

# Listar PRs abertos
gh pr list

# Ver status de checks/CI do PR
gh pr checks 127

# Fazer checkout de um PR localmente
gh pr checkout 127

# Ver diff do PR
gh pr diff 127

# Abrir PR no navegador
gh pr view 127 --web

# Criar novo PR
gh pr create --title "fix: corrige validação" --body "Descrição"

# Mergear PR
gh pr merge 127 --squash

Busca Avançada com git grep

O git grep é mais rápido que grep normal pois busca apenas em arquivos rastreados pelo Git. Muito útil para encontrar padrões em aplicações Rails.

Buscar Validações em Models

git grep "validates" -- "app/models/*.rb"

Buscar Uso de uma Gem Específica

git grep "require.*sidekiq" -- "*.rb"

Buscar com Contexto

Para ver linhas ao redor do resultado (útil para ver toda a validação ou método):

git grep -C 5 "validates :email" -- app/models/user.rb

Opções de contexto:

• -A 5: Mostra 5 linhas depois (útil para ver o corpo de um método)
• -B 5: Mostra 5 linhas antes
• -C 5: Mostra 5 linhas antes e depois

Buscar Callbacks em Models

git grep -n "before_save\|after_save" -- "app/models/*.rb"

Buscar TODOs no Código

git grep -i "TODO\|FIXME" -- "*.rb"

Buscar Configurações Sensíveis

git grep -i "password\|secret\|key" -- "config/*.yml"

Agora que você conhece os principais comandos de investigação e busca, vamos ver como aplicá-los seguindo boas práticas que manterão seu repositório organizado e profissional.

Boas Práticas

✅ Commits Atômicos

Cada commit deve representar uma mudança lógica:

❌ Ruim:

feat: adiciona login, corrige bug no header e atualiza README

✅ Bom:

feat(auth): adiciona formulário de login
fix(header): corrige alinhamento do logo
docs: atualiza instruções de instalação

✅ Mensagens Descritivas

❌ Ruim:

fix bug
update code
changes
WIP

✅ Bom:

fix(auth): previne login com campos vazios
refactor(api): extrai lógica de validação para função separada
test(checkout): adiciona testes para fluxo de pagamento

✅ Commits Frequentes

Faça commits pequenos e frequentes em vez de grandes commits:

• Facilita code review
• Mais fácil de fazer revert
• Histórico mais claro
• Reduz conflitos de merge

✅ Use Branches Descritivas

❌ Ruim:

feature1
new-stuff
test

✅ Bom:

feature/user-authentication
fix/header-alignment
refactor/api-validation

Para tornar seu trabalho ainda mais eficiente, você pode criar aliases que transformam comandos longos em atalhos rápidos.

Aliases Úteis

Adicione ao seu ~/.gitconfig:

[alias]
    # Status resumido
    st = status --short

    # Log formatado
    lg = log --graph --oneline --decorate --all

    # Ver últimos commits
    last = log -1 HEAD --stat

    # Desfazer último commit mantendo mudanças
    undo = reset HEAD~1 --soft

    # Branches recentes
    recent = branch --sort=-committerdate

    # Amend sem editar mensagem
    amend = commit --amend --no-edit

    # Ver branches que contêm um commit
    contains = branch -a --contains

    # Limpar branches já mergeadas
    cleanup = "!git branch --merged | grep -v '\\*\\|main\\|master\\|develop' | xargs -n 1 git branch -d"

    # Aliases específicos para Rails
    # Ver histórico de models
    models = log --oneline -- app/models/

    # Ver histórico de migrations
    migrations = log --oneline -- db/migrate/

    # Buscar validações
    validations = grep "validates" -- "app/models/*.rb"

    # Ver mudanças em routes
    routes = log -p -- config/routes.rb

Uso:

# Aliases gerais
git st              # em vez de git status --short
git lg              # log visual bonito
git last            # ver último commit
git undo            # desfazer último commit
git recent          # ver branches recentes
git amend           # amend rápido
git contains abc123 # ver branches com commit
git cleanup         # limpar branches mergeadas

# Aliases específicos Rails
git models          # ver histórico de mudanças em models
git migrations      # ver histórico de migrations
git validations     # listar todas as validações em models
git routes          # ver mudanças em routes com diff

Para facilitar a consulta rápida, aqui está uma tabela resumindo os comandos mais importantes abordados neste guia:

Resumo dos Comandos Mais Úteis

Conclusão

Rastrear bugs de forma eficiente é uma habilidade essencial para todo desenvolvedor. Com o workflow apresentado neste guia, você pode:

🔍 Identificar rapidamente quando e onde um problema foi introduzido 🧠 Entender o contexto completo por trás de uma mudança 💬 Acessar discussões que levaram à decisão ⚡ Agir com conhecimento para corrigir ou reverter mudanças problemáticas

O Workflow em 3 Passos

1. git log -L → Encontrar o commit que modificou a linha
2. git show → Analisar o que foi alterado
3. gh pr list → Descobrir o PR responsável

Dica Final

Não tente decorar todos os comandos. Salve este guia e use como referência. Com o tempo, o workflow se tornará automático:

1. Bug em um model? → git log -L <linha>,<linha>:app/models/<model>.rb
2. Pegou o hash? → git show <hash> --stat
3. Quer o contexto? → gh pr list --search "<hash>"

Dominar esse workflow vai economizar horas de investigação e tornar você muito mais eficiente em debugging e code review!

Próximo passo: Comece usando o workflow hoje mesmo no próximo bug que você encontrar no seu projeto. A prática leva à perfeição!

Referências

• Git Documentation
• GitHub CLI Manual
• Conventional Commits
• Pro Git Book (gratuito)
• Git Flight Rules - Guia prático para situações específicas

Sobre Este Guia

Este workflow foi desenvolvido com base em experiência real de debugging em projetos Rails de produção. Todos os comandos foram testados e validados em situações reais de investigação.

Tem alguma dúvida ou sugestão de melhoria para o workflow? Compartilhe nos comentários!

TL;DR (Resumo Rápido)

Commitou arquivos errados? Use este processo:

# 1. Identifique o commit anterior ao problemático
git log --oneline -5

# 2. Inicie rebase interativo marcando para edição
GIT_SEQUENCE_EDITOR="sed -i 's/^pick <hash>/edit <hash>/'" git rebase -i <hash-anterior>

# 3. Remova os arquivos indesejados
git reset HEAD^ -- arquivo1.txt arquivo2.txt

# 4. Refaça o commit sem os arquivos
git commit --amend --no-edit

# 5. Finalize o rebase
git rebase --continue

⚠️ Atenção: Só faça isso se ainda não deu push, ou esteja preparado para usar git push --force.

Índice

• O Problema
• Como Identificar o Problema
• A Solução: Git Rebase Interativo
• Cuidados Importantes
• Alternativa Mais Simples para o Último Commit
• Comandos Úteis Relacionados
• Resumo do Processo Completo

O Problema

Você já passou por aquela situação onde fez um git add . apressado, commitou as mudanças e depois percebeu que incluiu arquivos que não deveriam estar naquele commit? Talvez foram notas pessoais, arquivos de configuração, ou até documentação que deveria estar em um commit separado?

Pois é, isso acontece com frequência, especialmente quando trabalhamos em múltiplas funcionalidades simultaneamente e esquecemos de revisar o que realmente está sendo commitado.

Neste artigo, vou mostrar como resolvi exatamente esse problema: remover arquivos específicos de um commit mantendo as outras alterações intactas.

Um Exemplo Prático

Imagine que você tinha um commit chamado “fix: corrige validação de formulário” que deveria conter apenas 3 arquivos relacionados à correção:

• src/components/LoginForm.tsx
• src/components/RegisterForm.tsx
• src/utils/validation.ts

Porém, ao verificar o commit, você descobre que incluiu acidentalmente mais 4 arquivos:

• CHANGELOG.md
• TODO.md
• docs/README.md
• scripts/test-data.js

Esses arquivos não tinham nada a ver com a correção de validação e poluem o histórico do commit.

Como Identificar o Problema

Primeiro, verifique o conteúdo do commit problemático:

git show --name-status <hash-do-commit>

Ou veja o histórico recente:

git log --oneline -10

No nosso exemplo, vamos supor que identificamos que o commit abc1234 tinha arquivos extras que não deveriam estar lá.

A Solução: Git Rebase Interativo

A ferramenta mais poderosa para reescrever o histórico do Git é o rebase interativo. Ele permite editar, reordenar, combinar ou até excluir commits.

Passo 1: Identificar o Commit Base

Você precisa iniciar o rebase a partir do commit anterior ao que deseja editar. Se seu commit problemático é abc1234, você deve iniciar o rebase no commit imediatamente anterior a ele.

No nosso exemplo, o commit anterior era def5678:

git log --oneline -5
# 9ab0def feat: adiciona modo escuro
# 7cd8e91 docs: atualiza documentação da API
# abc1234 fix: corrige validação de formulário  ← Este que queremos editar
# def5678 refactor: reorganiza estrutura de pastas  ← Iniciamos o rebase aqui
# 1234abc feat: adiciona autenticação de usuários

Passo 2: Iniciar o Rebase Interativo

Execute o rebase interativo marcando o commit para edição:

GIT_SEQUENCE_EDITOR="sed -i 's/^pick abc1234/edit abc1234/'" git rebase -i def5678

Explicação do comando:

• GIT_SEQUENCE_EDITOR: Define um editor automático que substitui pick por edit no commit específico
• git rebase -i: Inicia o rebase interativo
• def5678: O commit base (anterior ao que queremos editar)

Você verá uma mensagem como:

Stopped at abc1234... fix: corrige validação de formulário
You can amend the commit now, with

  git commit --amend

Once you are satisfied with your changes, run

  git rebase --continue

Passo 3: Remover os Arquivos Indesejados

Agora que o rebase parou no commit que queremos editar, podemos remover os arquivos indesejados da staging area:

git reset HEAD^ -- CHANGELOG.md TODO.md docs/README.md scripts/test-data.js

Explicação do comando:

• git reset HEAD^: Remove arquivos do commit atual
• --: Separador entre opções e nomes de arquivos
• Lista de arquivos: Os arquivos específicos que queremos remover

Passo 4: Refazer o Commit

Agora refaça o commit sem os arquivos indesejados:

git commit --amend --no-edit

Explicação:

• --amend: Modifica o último commit
• --no-edit: Mantém a mensagem de commit original

Você verá a confirmação:

[detached HEAD 4f7a9b2] fix: corrige validação de formulário
 3 files changed, 12 insertions(+), 8 deletions(-)

Perfeito! Agora o commit tem apenas os 3 arquivos que deveriam estar lá.

Passo 5: Continuar o Rebase

Finalize o rebase para aplicar as mudanças:

git rebase --continue

O Git automaticamente atualizará os commits subsequentes e você verá:

Successfully rebased and updated refs/heads/main.

Passo 6: Verificar o Resultado

Confirme que tudo está correto:

git show --name-status 4f7a9b2

E verifique o status dos arquivos removidos:

git status

Os arquivos removidos do commit agora aparecem como untracked (não rastreados):

Arquivos não monitorados:
  CHANGELOG.md
  TODO.md
  docs/README.md
  scripts/test-data.js

Eles continuam no seu diretório de trabalho, mas não estão mais no histórico do Git. Você pode commitá-los separadamente quando quiser ou adicioná-los ao .gitignore.

Forma Alternativa: Sem Usar sed

Se você preferir uma abordagem mais manual, pode fazer o rebase interativo tradicional:

git rebase -i def5678

Isso abrirá seu editor padrão (vim, nano, etc.) mostrando:

pick abc1234 fix: corrige validação de formulário
pick 7cd8e91 docs: atualiza documentação da API
pick 9ab0def feat: adiciona modo escuro

Altere manualmente pick para edit na linha do commit que deseja modificar:

edit abc1234 fix: corrige validação de formulário
pick 7cd8e91 docs: atualiza documentação da API
pick 9ab0def feat: adiciona modo escuro

Salve e feche o editor. O resto do processo é idêntico aos passos 3-6 acima.

⚠️ Cuidados Importantes

1. 🚨 Nunca reescreva histórico público

Se você já fez git push do commit para um repositório compartilhado (GitHub, GitLab, etc.), não reescreva o histórico a menos que:

• Você esteja trabalhando sozinho no branch
• Todos os colaboradores estejam cientes e concordem
• Você esteja disposto a fazer um git push --force

Reescrever histórico público pode causar problemas sérios para outros desenvolvedores que já baixaram seu código.

2. 💾 Faça backup antes

Antes de fazer rebase, sempre é bom criar um branch de backup:

git branch backup-antes-rebase

Assim, se algo der errado, você pode voltar:

git reset --hard backup-antes-rebase

3. 🔄 Commits posteriores serão reescritos

Quando você edita um commit no meio do histórico, todos os commits posteriores terão seus hashes SHA-1 alterados. Isso é normal e esperado, pois o hash é calculado com base no conteúdo do commit e seu histórico.

No nosso exemplo:

• Antes: abc1234 → 7cd8e91 → 9ab0def
• Depois: 4f7a9b2 → a3b2c1d → e5f6g7h

4. ⚔️ Conflitos podem acontecer

Se houver conflitos durante o rebase, o Git pausará e pedirá para você resolvê-los:

# Resolver conflitos manualmente
git add <arquivos-resolvidos>
git rebase --continue

Se quiser desistir do rebase:

git rebase --abort

Alternativa Mais Simples para o Último Commit

Se o commit que você quer editar é o último commit (HEAD), o processo é muito mais simples:

# Remover arquivos do último commit
git reset HEAD^ -- arquivo1.txt arquivo2.txt

# Refazer o commit
git commit --amend --no-edit

# Ou com nova mensagem
git commit --amend -m "Nova mensagem"

Não precisa de rebase nesse caso!

Comandos Úteis Relacionados

Ver diferenças entre commits

git diff <commit1> <commit2>

Ver apenas nomes dos arquivos modificados

git diff --name-only <commit1> <commit2>

Ver histórico de um arquivo específico

git log --follow -- caminho/do/arquivo.rb

Desfazer último commit mantendo as mudanças

git reset --soft HEAD^

Desfazer último commit descartando as mudanças

git reset --hard HEAD^

Quando Usar Cada Abordagem

Resumo do Processo Completo

# 1. Identificar o problema
git log --oneline -10
git show --name-status <hash-do-commit>

# 2. Iniciar rebase marcando commit para edição
GIT_SEQUENCE_EDITOR="sed -i 's/^pick <hash>/edit <hash>/'" git rebase -i <commit-anterior>

# 3. Remover arquivos indesejados
git reset HEAD^ -- arquivo1.txt arquivo2.txt arquivo3.txt

# 4. Refazer commit
git commit --amend --no-edit

# 5. Continuar rebase
git rebase --continue

# 6. Verificar resultado
git log --oneline -5
git status

Conclusão

O git rebase -i é uma ferramenta poderosa para manter seu histórico de commits limpo e organizado. Lembre-se dos pontos principais:

• ✅ Use git rebase -i para editar commits no meio do histórico
• ✅ Combine com git reset HEAD^ para remover arquivos específicos sem perder outras mudanças
• ⚠️ Nunca reescreva histórico já compartilhado (a menos que todos concordem)
• 💡 Faça backup antes com git branch backup-antes-rebase

Dominar essas técnicas permite que cada commit represente uma mudança lógica e coerente, facilitando code review, debugging e colaboração em equipe.

Dica final: Antes de dar git push, sempre revise o que está sendo commitado com git show ou git diff --staged. Prevenir é melhor que remediar!

Referências:

• Git Rebase Docs
• Git Reset Docs
• Atlassian Git Rebase Tutorial

Sobre Este Tutorial

Este artigo foi escrito com base em casos reais de desenvolvimento. Todos os comandos e processos foram testados e validados em projetos de produção. Os exemplos foram generalizados para aplicar a qualquer tipo de projeto.

Se você encontrou este artigo útil, considere compartilhá-lo com outros desenvolvedores que possam se beneficiar. Tem alguma dúvida ou sugestão? Deixe um comentário ou abra uma issue no GitHub!

UMA BREVE INTRODUÇÃO

O trabalho foi realizado no Brasil, onde muitas residências têm chuveiros elétricos. O chuveiro elétrico não é nada mais chuveiro à qual possui uma resistência elétrica, onde água transita para se aquecer e cair na nossa cabeça (meio doido isso de imaginar). Durante o curso eu sempre ouvia que o chuveiro era um vilão para sistema de energia, pois ele, mais consumia energia numa residência. Para além disso, esse consumo ocorria no período onde a demanda da rede já era grande. Como sempre fui curioso (e teimoso), resolvi entender esse bicho e ajudar na causa.

Resolvi unir duas áreas que gosto, Energia e TI, trazendo o IOT (Internet das coisas) para o chuveiro e transformando o vilão num bom mocinho (não foi bem assim kkk, na realidade apenas rolou espionagem do vilão). Antes de apresentar o dispositivo desenvolvido e o sistema de espionagem, vamos entender um pouco sobre o chuveiro elétrico. Vou trazer citação que coloquei no TCC de Pinheiro e Sangoi.

O chuveiro elétrico é uma tecnologia brasileira, desenvolvida no fim dos anos 40, que, devido à sua difusão, modificou os hábitos de banho do povo brasileiro. Se num primeiro instante, a sua difusão permitiu uma melhoria na qualidade de vida, hoje se tornou um problema do ponto de vista energético (PINHEIRO, 2006; SANGOI, 2015).

Os primeiros chuveiros elétricos industriais desenvolvidos no Brasil eram de metal, bagulho doido véi, juntar água + Metal + Energia elétrica e tomar banho, o inventor com certeza tinha falta parafusos (para ser um bom inventor é necessário).

Na figura, apresento o princípio de funcionamento do chuveiro elétrico, com um pouco de conhecimento sobre elétrica é algo simples de se entender. A corrente elétrica quando passa pela resistência, gera calor e esse calor é transferido para a água que aumentando a temperatura.

Depois dos primeiros modelos, que chamo de tradicionais no trabalho, vieram outros até chegar nos mais difundidos até o momento (2022), os eletrônicos.

O que eu fiz no trabalho, foi pegar um desses chuveiros eletrônicos e alguns sensores e mostrar para o usuário, chamei de inteligente, isso foi feito acoplando um dispositivo extra que desenvolvi para monitorar e controlar ele remotamente ( a inteligência lklkkl ).

SISTEMA PROPOSTO

A ideia do sistema é apresentada na figura abaixo, onde um usuário pode controlar o chuveiro diretamente durante o banho ou remotamente pelo serviço provido na “nuvem” (um pc velho). A “inteligência” que tem no título seria os sensores de coleta de dados que o dispositivo tem , que trabalham em conjunto com o servidor, enviando os dados para ele e serem apresentados ao usuário.

Na figura 15 apresento o modelo de comunicação do sistema e na figura 16 o modelo do hardware do dispositivo que desenvolvi.

O dispositivo foi desenvolvido utilizando um esp32 e e alguns sensores e o código deixei no github (sempre precisa de melhorias, mas compriu seu propósito).

MATERIAIS UTILIZADOS

Na tabela 1 apresento os componentes utilizados para montar o hardware

Na tabela 2 os softwares utilizados para criar todo sistema.

Alguns testes que realizei conforme eu ia montando o dispositivo ficam na figura abaixo.

No final saiu esse Frankenstein aí, não era bonito mas funcional.

RESULTADO

Na figura abaixo tem meu chuveiro e dispositivo (sim, testei no meu chuveiro, meio doido kkk) acoplados. O dispositivo foi feito de modo a ser não invasivo, podendo ser acoplado a qualquer chuveiro elétrico. O dispositivo coleta informações de corrente, tensão e temperatura, que são utilizados para poder saber o consumo do chuveiro em tempo real. Além disso, ele controla a potência entregue ao chuveiro e com isso a temperatura de saída.

Essas informações coletadas são mostradas ao usuário em tempo real num dashboard, apresentado na figura abaixo.

Os dados são guardados num banco de dados de séries temporais. Os dados armazenados poderam ser utilizados em futuras análises de dados.

Em suma,o trabalho realizado foi interessante , pois consegui percorrer vários campos de conhecimento indo desde da programação de microcontrolador, montagem de hardware, deploy de sistemas e comunicação IoT e no final entregar um produto minimamente viável.

Para saber mais sobre o trabalho podes ler o arquivo final aqui.

2022 chegou e com ele novos desafios à vista, ainda estamos em janeiro e muitas coisas estão acontecendo (omicron está a solta). Estamos a dois anos em pandemia e cada dia surge uma nova variante do covid19, então resolvi começar o ano com um hand on e este blog é uma das coisas que pretendo colocar em prática. Bora ver até quando dura meu entusiasmo (normalmente não dura muito kkkk).

Ao longo desse ano pretendo realizar vários projetos e um que já está em execução é o de programação, onde irei realizar um desafio do beecrowd por dia. Estou colocando as resoluções num repo no github confere aqui.

Abraço até o próximo post.