Gerenciar seus tokens de acesso pessoal

Sobre personal access tokens

Personal access tokens são uma alternativa ao uso de senhas para autenticação no GitHub ao usar a GitHub API ou a linha de comando.

Personal access tokens são destinados a acessar GitHub recursos em nome de si mesmo. Para acessar recursos em nome de uma organização ou para integrações de longa duração, você deve usar uma GitHub App. Para saber mais, confira Sobre a criação de aplicativos GitHub.

Um token tem os mesmos recursos para acessar recursos e executar ações nesses recursos que o proprietário do token e é ainda mais limitado por quaisquer escopos ou permissões concedidos ao token. Um token não pode conceder recursos de acesso adicionais a um usuário. Por exemplo, um personal access token pode ser configurado com um admin:org escopo, mas se o proprietário do token não for um proprietário da organização, o token não dará acesso administrativo à organização.

Tipos de personal access tokens

GitHub atualmente dá suporte a dois tipos de personal access tokens: fine-grained personal access tokens e personal access tokens (classic). GitHub recomenda que você use fine-grained personal access token em vez de personal access tokens (classic) sempre que possível.

Ambos fine-grained personal access tokene personal access tokens (classic) estão vinculados ao usuário que os gerou e ficarão inativos se o usuário perder o acesso ao recurso.

Os proprietários da organização podem definir uma política para restringir o acesso de personal access tokens (classic) à sua organização, e os proprietários da corporação podem restringir o acesso de personal access tokens (classic) à corporação ou às organizações pertencentes à corporação. Para saber mais, confira Como configurar uma política de token de acesso pessoal para a organização.

Fine-grained personal access tokens

Fine-grained personal access tokens têm várias vantagens de segurança sobre personal access tokens (classic), mas também têm limitações que podem fazer com que você não consiga usá-las em todos os cenários. Esses limites, e nossos planos para corrigi-los, podem ser encontrados na seção abaixo.

Se você puder usar um fine-grained personal access token para seu cenário, você se beneficiará dessas melhorias:

• Cada token é limitado a acessar recursos pertencentes a um usuário ou uma organização.
• Cada token pode ser ainda mais limitado a acessar apenas repositórios específicos desse usuário ou organização.
• Cada token recebe permissões específicas e granulares, que oferecem mais controle do que os escopos concedidos a personal access tokens (classic).
• Os proprietários da organização podem exigir aprovação para quaisquer fine-grained personal access tokens que possam acessar recursos na organização.
• Os proprietários corporativos podem exigir aprovação para qualquer fine-grained personal access tokens que possa acessar recursos em organizações pertencentes à empresa.

Fine-grained personal access tokens Limitações

Fine-grained personal access tokens não dão suporte a todos os recursos de personal access tokens (classic). Essas lacunas de recursos não são permanentes, GitHub está trabalhando para fechá-las. Examine nosso roteiro público para obter mais detalhes sobre quando esses cenários terão suporte.

As principais lacunas em fine-grained personal access tokens são:

• Usar fine-grained personal access token para contribuir com repositórios públicos em que o usuário não é membro.

• Usar fine-grained personal access token para contribuir com repositórios em que o usuário é um colaborador externo ou de repositório.

• Usar fine-grained personal access token para acessar várias organizações ao mesmo tempo.

• Usar fine-grained personal access token para acessar internal recursos em uma empresa à qual o usuário pertence.

• Usar fine-grained personal access token para chamar APIs que gerenciam a conta Enterprise.

• Usar fine-grained personal access token para acessar pacotes.

• Usar fine-grained personal access token para chamar a API de Verificações.

• Usar fine-grained personal access token para acessar projetos de propriedade de uma conta de usuário.

Todas essas lacunas serão resolvidas ao longo do tempo, à medida que GitHub continuar investindo em padrões de acesso mais seguros.

Personal access tokens (classic)

Personal access tokens (classic) são menos seguros. Entretanto, alguns recursos só funcionam com personal access tokens (classic):

• Somente personal access tokens (classic) têm acesso de gravação para repositórios públicos que não pertencem a você ou a uma organização da qual você não é membro.
• Somente personal access tokens (classic) têm acesso de gravação automaticamente para repositórios internos pertencentes à empresa. Fine-grained personal access tokens precisam receber acesso a repositórios internos.
• Os colaboradores externos só podem usar personal access tokens (classic) para acessar repositórios da organização nos quais são colaboradores.
• Somente personal access tokens (classic) podem acessar empresas. (O Fine-grained personal access token pode acessar organizações pertencentes a empresas.)
• Alguns Pontos de Extremidade de API REST só estão disponíveis com um personal access tokens (classic). Para determinar se um ponto de extremidade também oferece suporte a fine-grained personal access tokens, confira a documentação correspondente ou confira Pontos de extremidade disponíveis para tokens de acesso pessoal refinados.

Se você optar por usar um personal access token (classic), tenha em mente que ele concederá acesso a todos os repositórios dentro das organizações às quais você tem acesso, bem como a todos os repositórios pessoais em sua conta pessoal.

Mantendo seus personal access tokens seguros

Personal access tokens são como senhas e compartilham os mesmos riscos de segurança inerentes. Antes de criar um novo personal access token, considere se há um método mais seguro de autenticação disponível para você:

• Para acessar GitHub a partir da linha de comando, você pode usar GitHub CLI ou o Git Credential Manager em vez de criar um personal access token.
• Ao usar um personal access token em um fluxo de trabalho GitHub Actions, considere se você pode usar a funcionalidade interna GITHUB_TOKEN em vez disso. Para saber mais, confira Usar GITHUB_TOKEN para autenticação em fluxos de trabalho.

Se essas opções não forem possíveis e você precisar criar um personal access token, considere usar outro serviço da CLI para armazenar seu token com segurança.

Ao usar um personal access token em um script, você pode armazenar seu token como um segredo e executar seu script através do GitHub Actions. Para obter mais informações, consulte Usar segredos em ações do GitHub.

Para obter mais informações sobre as práticas recomendadas, consulte Manter suas credenciais de API seguras.

Criar um fine-grained personal access token

1. No canto superior direito de qualquer página do GitHub, clique em sua imagem de perfil e, em seguida, clique em Configurações.

2. Na barra lateral esquerda, clique em Developer settings.

3. Na barra lateral esquerda, em Personal access tokens, clique em tokens granulares.

4. Clique em Gerar novo token.

5. Em Nome do token, insira um nome para ele.

6. Em Validade, selecione uma validade para o token. Tempos de vida infinitos são permitidos, mas podem ser bloqueados por uma política de tempo de vida máximo definida pelo proprietário da sua organização ou empresa. Para obter mais informações, veja a aplicação de uma política de tempo de vida máxima para personal access tokens.

7. Opcionalmente, em Descrição, adicione uma observação para descrever a finalidade do token.

8. Em Proprietário do recurso, selecione um proprietário de recurso. O token só poderá acessar recursos pertencentes ao proprietário do recurso selecionado. As organizações das quais você é membro não serão exibidas se a organização tiver bloqueado o uso de fine-grained personal access tokens. Para obter mais informações, consulte Como configurar uma política de token de acesso pessoal para a organização.

9. Opcionalmente, se o proprietário do recurso for uma organização que requer aprovação para fine-grained personal access tokens, abaixo do proprietário do recurso, na caixa, insira uma justificativa para a solicitação.

10. Em Acesso ao repositório, selecione quais repositórios você deseja que o token acesse. Você deve escolher o acesso mínimo ao repositório que atenda às suas necessidades. Os tokens sempre incluem acesso somente leitura a todos os repositórios públicos no GitHub.

11. Se você selecionou Selecionar somente repositórios na etapa anterior, na lista suspensa Repositórios selecionados , selecione os repositórios que você deseja que o token acesse.

12. Em Permissões, selecione quais permissões quer conceder o token. Dependendo do proprietário do recurso e do acesso do repositório especificados, haverá permissões de repositório, organização e conta. Você deve escolher as permissões mínimas para suas necessidades.

    O documento de referência da API REST para cada ponto de extremidade especifica se o ponto de extremidade funciona com fine-grained personal access tokens e indica quais permissões são necessárias para que o token use o ponto de extremidade. Alguns pontos de extremidade podem exigir várias permissões e alguns pontos de extremidade podem exigir uma de várias permissões. Para obter uma visão geral dos pontos de extremidade da API REST que fine-grained personal access token pode acessar com cada permissão, consulte Permissões necessárias para tokens de acesso pessoal refinados.

13. Clique em Gerar token.

Se você selecionou uma organização como o proprietário do recurso e a organização requer aprovação para fine-grained personal access tokens, o token será marcado como pending até que seja revisado por um administrador da organização. O token poderá ler apenas recursos públicos até que seja aprovado. Se você for um proprietário da organização, a solicitação será aprovada automaticamente. Para saber mais, confira Revisar e revogar tokens de acesso pessoal na organização.

Pré-preenchimento de fine-grained personal access token detalhes usando parâmetros de URL

Você pode compartilhar modelos para um fine-grained personal access token por meio de links. Armazenar os detalhes do token dessa maneira facilita a automatização de fluxos de trabalho e melhora a experiência do desenvolvedor, direcionando os usuários para a criação de tokens com campos relevantes já preenchidos.

Cada campo com suporte pode ser definido usando um parâmetro de consulta específico. Todos os parâmetros são opcionais e validados pelo formulário de geração de token para garantir que as combinações de permissões e o proprietário do recurso façam sentido.

Um exemplo de modelo de URL é mostrado aqui, com quebras de linha para legibilidade:

https://github.com/settings/personal-access-tokens/new
  ?name=Repo-reading+token
  &description=Just+contents:read
  &target_name=octodemo
  &expires_in=45
  &contents=read

https://github.com/settings/personal-access-tokens/new
  ?name=Repo-reading+token
  &description=Just+contents:read
  &target_name=octodemo
  &expires_in=45
  &contents=read

Experimente a URL para criar um token com contents:read e metadata:read, com o nome e a descrição fornecidos e uma data de validade de 45 dias no futuro. Você verá uma mensagem de erro indicando Cannot find the specified resource owner: octodemo porque você não é membro da organização octodemo.

Abaixo estão alguns exemplos de URLs que geram os tokens que vemos com mais frequência:

• Ler conteúdo do repositório
• Acesso push aos repositórios
• Acesso a modelos do GitHub
• Atualizar código e abrir PR
• Gerenciar licenças do Copilot em uma organização
• Fazer solicitações do Copilot

Parâmetros de consulta compatíveis

Para criar seu próprio modelo de token, siga os detalhes do parâmetro de consulta fornecidos nesta tabela:

Permissões

Cada permissão com suporte é definida usando seu nome como um parâmetro de consulta, com o valor especificando o nível de acesso desejado. Os níveis de acesso válidos são read, write e admin. Algumas permissões só dão suporte a read, algumas só dão suporte a writee apenas algumas têm admin. Use quantas permissões forem necessárias, no formato &contents=read&pull_requests=write&....

Você não precisa incluir tanto read quanto write para uma permissão em sua URL—write sempre inclui read e admin sempre inclui write.

Permissões de conta

As permissões de conta só são usadas quando o usuário atual é definido como o proprietário do recurso.

Permissões do repositório

As permissões de repositório funcionam para proprietários de recursos do usuário e da organização.

Permissões da organização

As permissões da organização só poderão ser usadas se o proprietário do recurso for uma organização.

Criar um personal access token (classic)

1. No canto superior direito de qualquer página do GitHub, clique em sua imagem de perfil e, em seguida, clique em Configurações.

2. Na barra lateral esquerda, clique em Developer settings.

3. Na barra lateral esquerda, em Personal access tokens, clique em Tokens (clássico).

4. Selecione Gerar novo token e clique em Gerar novo token (clássico).

5. No campo "Observação", dê um nome descritivo ao token.

6. Para dar uma validade ao token, selecione Validade e escolha uma opção padrão ou clique em Personalizado para inserir uma data.

7. Selecione os escopos ou as permissões que deseja conceder a esse token. Para usar o token para acessar os repositórios na linha de comando, selecione repositório. Um token com nenhum escopo atribuído só pode acessar informações públicas. Para saber mais, confira Escopos para aplicativos OAuth.

8. Clique em Gerar token.

9. Opcionalmente, para copiar o novo token para sua área de transferência, clique em .

Excluindo um personal access token

Você deve excluir um personal access token se ele não for mais necessário. Se você excluir um personal access token que foi usado para criar uma chave de implantação, a chave de implantação também será excluída.

1. No canto superior direito de qualquer página do GitHub, clique em sua imagem de perfil e, em seguida, clique em Configurações.
2. Na barra lateral esquerda, clique em Developer settings.
3. Na barra lateral esquerda, em Personal access tokens, clique em Tokens detalhados ou Tokens (Clássicos), dependendo do tipo que você gostaria de excluir personal access token.
4. À direita de personal access token que você deseja excluir, clique em Excluir.

Usando um personal access token na linha de comando

Depois de ter uma personal access token, você pode inseri-la em vez de sua senha ao executar operações do Git por HTTPS.

Por exemplo, para clonar um repositório na linha de comando, insira o comando git clone a seguir. Você será solicitado a inserir seu nome de usuário e senha. Quando solicitado, insira o seu personal access token em vez de uma senha.

$ git clone https://HOSTNAME/USERNAME/REPO.git
Username: YOUR-USERNAME
Password: YOUR-PERSONAL-ACCESS-TOKEN

Embora seja necessário inserir seu nome de usuário junto com personal access token, o nome de usuário não é usado para autenticar você. Em vez disso, o personal access token é usado para autenticar você. Se você não inserir um nome de usuário, receberá uma mensagem de erro informando que suas credenciais são inválidas.

Personal access tokens só podem ser usados para operações HTTPS Git. Se o repositório usar uma URL remota SSH, você precisará alternar o repositório remoto de SSH para HTTPS.

Se não for solicitado a informar seu nome de usuário e a senha, suas credenciais poderão ser armazenadas em cache no seu computador. Você pode atualizar suas credenciais no conjunto de chaves para substituir sua senha antiga pelo token.

Em vez de inserir manualmente seu personal access token para cada operação HTTPS Git, você pode armazenar em cache seu personal access token usando um cliente Git. O Git irá armazenar temporariamente as suas credenciais na memória até que um intervalo de expiração tenha passado. Você também pode armazenar o token em um arquivo de texto simples que o Git pode ler antes de cada solicitação. Para saber mais, confira Armazenando suas credenciais de GitHub em cache no Git.

Leitura adicional

• Sobre a autenticação para GitHub
• Vencimento e revogação de token