Hub documentation
Contas de serviço
Contas de serviço
Este recurso faz parte dos planos Enterprise e Enterprise Plus.
Contas de serviço são identidades pertencentes à organização, projetadas para acesso programático aos recursos da sua organização, como pipelines de CI/CD, scripts de automação e integrações de backend. Diferente de uma conta de membro pessoal, uma conta de serviço não está vinculada a uma pessoa específica: ela pertence à organização e é gerenciada por seus administradores.
Como uma conta de serviço é desacoplada de qualquer indivíduo, ela mantém os fluxos de trabalho automatizados em execução, mesmo quando pessoas entram ou saem da organização, e permite que você delimite e rotacione credenciais sem afetar os tokens pessoais de nenhum membro.
Criando uma Conta de Serviço
Como administrador da organização, acesse a seção Service Accounts nas configurações da sua organização para criar e gerenciar contas de serviço.

Ao criar uma conta de serviço, você fornece:
- Um name para identificar a conta de serviço.
- Uma description opcional para documentar para que a conta de serviço é utilizada.
Contas de serviço não possuem senha e não podem fazer login de forma interativa — elas são acessadas exclusivamente por meio dos tokens de acesso que você emite para elas. Diferente de usuários regulares, elas também não possuem uma página de perfil no HF, não fazem parte da lista de membros da organização e são gerenciadas apenas pelas configurações de Service Accounts.
Contas de serviço não podem ser adicionadas a Resource Groups, inclusive por meio de auto-join. Para limitar quais repositórios uma conta de serviço pode acessar, defina o escopo de seus tokens de acesso (veja abaixo).
Gerenciando Tokens de Acesso
O acesso de uma conta de serviço à sua organização é definido inteiramente pelos tokens de acesso de granularidade fina que você emite para ela. Para cada token, você escolhe um nome e um conjunto de permissões de granularidade fina, de modo a conceder apenas o acesso necessário para um determinado fluxo de trabalho.
As permissões podem ser concedidas em dois níveis:
- Em toda a organização — aplique uma permissão (por exemplo, acesso de leitura ou gravação ao conteúdo dos repositórios) em todos os repositórios da organização.
- Por repositório — limite o acesso de leitura ou gravação a repositórios específicos. Pesquise e selecione os repositórios aos quais o token deve se aplicar e, em seguida, escolha as permissões a serem concedidas. Você pode selecionar repositórios pertencentes à organização e repositórios com acesso restrito fora da organização aos quais a conta de serviço foi autorizada.
Isso permite emitir tokens com escopo restrito — por exemplo, um token que pode apenas ler um único repositório de modelo — em vez de conceder acesso a toda a organização.
Os tokens também podem ser permitidos para trabalhar com repositórios com controle de acesso fora da sua organização, na seção Repositórios com controle de acesso do formulário do token:
- Leia o conteúdo de repositórios com acesso restrito aos quais a conta de serviço tem acesso — leia repositórios com acesso restrito após a conta de serviço ter sido autorizada.
- Solicitar acesso a repositórios restritos — permite que o token envie solicitações de acesso a repositórios restritos em nome da conta de serviço.
Para conceder a um token acesso apenas a alguns desses repositórios com controle de acesso, deixe Read contents of gated repos the service account has access to desmarcado e selecione-os individualmente nas permissões por repositório.

A partir da página da conta de serviço, os administradores podem:
- Crie um novo token de acesso com um nome escolhido e permissões granulares.
- Atualizar o nome ou as permissões de um token existente.
- Rotacionar um token para substituí-lo por um novo valor. O token anterior deixa de funcionar imediatamente, o que é útil se uma credencial pode ter sido exposta.
- Excluir um token para revogar permanentemente seu acesso.
Tokens de conta de serviço não precisam de aprovação sob a política de token “Exigir aprovação do administrador”. Eles podem acessar os recursos da sua organização assim que forem criados.
Assim como os tokens de acesso pessoal, os tokens de conta de serviço expiram após um ano sem uso. Os administradores da organização recebem um e-mail 30 dias antes, e o token exibe um selo Expires na página da conta de serviço. Para manter o token, use-o antes dessa data. Tokens expirados exibem um selo Invalidated e deixam de funcionar. Rode-os para obter um novo valor, que você precisará atualizar em todos os locais onde o token é utilizado.
Um token de acesso é exibido apenas uma vez, no momento em que é criado ou rotacionado. Armazene-o com segurança — ele não pode ser recuperado posteriormente. Se você o perder, rotacione o token para gerar um novo valor.
Gerando credenciais do S3
Tokens de conta de serviço podem ser usados para acessar os Storage Buckets da sua organização por meio da S3-compatible API. O gateway autentica com chaves de acesso no estilo AWS derivadas de um token de conta de serviço.
Acesse a página da conta de serviço. Crie um token com o botão Criar novo token caso ainda não tenha um. As permissões do token se tornam as permissões das credenciais do S3.
Encontre o token na lista, abra o menu suspenso correspondente e selecione Generate S3 credentials.

Copie o ID da chave de acesso gerada (com o prefixo
HFAK…) e a chave de acesso secreta em um local seguro — a chave secreta é exibida apenas uma vez. Se você a perder, use Invalidar e atualizar credenciais S3 para gerar um novo par. A chave de acesso anterior para de funcionar imediatamente.
As credenciais do S3 herdam as permissões do token de acesso subjacente. Restrinja o escopo do token apenas aos buckets que você pretende usar.
Use Revogar credenciais do S3 para desabilitar o par sem excluir o token — excluir o token (ou a conta de serviço) também revoga suas credenciais do S3. A página da conta de serviço mostra o ID da chave de acesso atualmente pareado com cada token.
Use o nome da sua organização como <namespace> na URL do endpoint (veja Configurando um Cliente). A geração e a revogação de credenciais S3 são registradas nos Logs de Auditoria da organização.
Se um token tiver a Isenção de Segurança da Rede ativada, apenas administradores da organização podem gerar credenciais S3 para ele.
Isenção de segurança de rede
Esta opção faz parte do plano Enterprise Plus.
Se a sua organização usa configurações de Network Security, os tokens de conta de serviço estão sujeitos a elas como qualquer outra credencial: eles só funcionam a partir dos intervalos de IP da sua organização, e a Content Access Policy se aplica ao que eles podem acessar.
Alguns fluxos de trabalho automatizados são executados fora da rede corporativa — por exemplo, um trabalho de CI hospedado por um provedor de nuvem. Para esses casos, você pode isentar um token individual da aplicação de Segurança de Rede da sua organização com a opção Bypass IP restrictions and the Content Access Policy no formulário do token.
Quando ativado:
- O token funciona a partir de qualquer endereço IP, mesmo quando Restringir o acesso da organização apenas aos seus intervalos de IP está ativado.
- O token pode acessar conteúdo que a Política de Acesso a Conteúdo da sua organização bloquearia de outra forma.
- A isenção se aplica apenas às configurações de Segurança de Rede da sua própria organização. Ela nunca contorna a política de outra organização.
- O token é listado com o selo Sem restrições de IP na página da conta de serviço.
- A rotação do token preserva a isenção.
Apenas administradores de organização podem ativar a isenção ou rotacionar um token que já esteja isento.
Como um token isento não é mais protegido pelo perímetro da sua rede, o próprio token se torna a única credencial que protege os recursos aos quais ele pode acessar. Recomendamos limitá-lo ao menor conjunto possível de repositórios, concedendo permissões somente de leitura quando isso for suficiente e realizando a rotação regularmente.
Faturamento
Contas de serviço não são contabilizadas como membros cobráveis da sua organização, portanto, a criação delas não consome uma vaga paga no seu plano.
Update on GitHub