Gerenciar contas corporativas

Sobre o gerenciamento de contas corporativas com o GraphQL

Para ajudá-lo a monitorar e fazer alterações nas suas organizações e manter a conformidade, você pode usar a API de Contas corporativas e a API de log de auditoria, que estão disponíveis apenas como APIs do GraphQL.

Os endpoints da conta corporativa funcionam tanto para o GitHub Enterprise Cloud quanto para o GitHub Enterprise Server.

O GraphQL permite que você solicite e retorne apenas os dados especificados. Por exemplo, você pode criar uma consulta GraphQL ou solicitar informações para ver todos os novos membros da organização adicionados à sua organização. Ou você pode fazer uma mutação ou alteração para convidar um administrador para sua conta corporativa.

Com a API do Log de Auditoria, você pode monitorar quando alguém:

Acessa as configurações de sua organização ou repositório.
Altera as permissões.
Adiciona ou remove usuários em uma organização, repositório ou equipe.
Promove os usuários a administrador.
Altera as permissões de um aplicativo GitHub.

A API do Log de Auditoria permite que você mantenha cópias dos dados do log de auditoria. Para consultas feitas com a API do Log de Auditoria, a resposta do GraphQL pode incluir dados por um período de até 90 a 120 dias. Para ver uma lista dos campos disponíveis na API de Log de Auditoria, confira a Administração de empresas.

Com a API de Contas corporativas, você pode:

Listar e revisar todas as organizações e repositórios que pertencem à conta corporativa.
Alterar configurações da conta empresarial.
Configurar políticas para configurações na conta corporativa e em suas organizações.
Convidar os administradores para a sua conta empresarial.
Criar novas organizações na sua conta corporativa.

Para obter uma lista dos campos disponíveis com a API contas corporativas, consulte Gerenciar contas corporativas.

Primeiros passos com o uso do GraphQL para contas empresariais

Consulte Como usar clientes do GraphQL para começar a usar o GraphQL para gerenciar suas contas corporativas.

Para ver alguns exemplos de consultas, confira Um exemplo de consulta que usa a API de Contas Enterprise.

1. Escolher um método de autenticação

É recomendável usar um GitHub App para operações GraphQL empresariais que oferecem suporte a isso. GitHub Apps fornece permissões refinadas e tokens de curta duração sem depender de um proprietário da conta corporativa personal access token. Nem todas as consultas e mutações do GraphQL corporativo dão suporte a GitHub Apps. Use uma personal access token para operações que não dão suporte a elas.

Usando um GitHub App

Registre um GitHub App e selecione as permissões corporativas necessárias para suas operações. Consulte Registrando um aplicativo GitHub.
Instale o aplicativo na empresa que você deseja gerenciar. Se você não for um proprietário da empresa, precisará pedir ao proprietário da empresa para instalá-lo. Consulte Como instalar um aplicativo do GitHub em sua empresa.
Autentique com um token de acesso de instalação ou um token de acesso do usuário, dependendo da operação e se o aplicativo precisa agir em nome de um usuário. As instruções do Insomnia abaixo usam um token de acesso do usuário.

Uma instalação corporativa concede somente permissões corporativas. Ele não concede acesso a organizações ou repositórios na enterprise. Para operações de organização ou repositório, o aplicativo precisa de instalações separadas nas organizações relevantes e permissões apropriadas. Depois de instalado nas organizações, seu aplicativo pode operar entre elas em uma consulta GraphQL usando um token de acesso do usuário. Os tokens de instalação são bloqueados para uma única conta corporativa ou organizacional e não podem ser usados entre contas.

Usando um personal access token

Use um personal access token se a operação de que você precisa não der suporte GitHub Appsou se você estiver criando automação para acessar várias organizações ou dados de repositório em uma única consulta GraphQL.

Para autenticar com o GraphQL com um personal access token, crie um nas configurações do desenvolvedor. Para obter mais informações, consulte Gerenciar seus tokens de acesso pessoal.
Conceda permissões de administrador e controle total às áreas personal access token da sua empresa que você gostaria de acessar. Para obter permissão total para repositórios privados, organizações, equipes, dados do usuário e acesso a dados de cobrança empresarial e de perfil, recomendamos que você selecione os seguintes escopos para o seu personal access token:
- repo
- admin:org
- user
- admin:enterprise
Os escopos específicos da conta corporativa são:
- admin:enterprise: fornece controle completo das empresas (inclui manage_runners:enterprise, manage_billing:enterprise e read:enterprise)
- manage_billing:enterprise: ler e gravar dados de cobrança da empresa.
- read:enterprise: lê os dados de perfil da empresa.
Copie-o personal access token e mantenha-o em um local seguro até adicioná-lo ao cliente GraphQL.

2. Escolher um cliente do GraphQL

Recomendamos que você use o GraphiQL ou outro cliente autônomo do GraphQL que permite configurar a URL de base.

Você também pode considerar o uso destes clientes do GraphQL:

As próximas etapas usarão Insomnia.

3. Configurar o Insomnia para usar a API GraphQL do GitHub com contas empresariais

Adicione a URL base e o método POST ao cliente GraphQL. Ao usar o GraphQL para solicitar informações (consultas), alterar informações (mutações) ou transferir dados usando a API GitHub, o método HTTP padrão é POST e a URL base segue esta sintaxe:
- Para sua instância corporativa: https://<HOST>/api/graphql
- Para GitHub Enterprise Cloud: https://api.github.com/graphql
- Para GitHub Enterprise Cloud com Residência de Dados: https://api.SUBDOMAIN.ghe.com/graphql

Autentique com um GitHub App

Este procedimento usa o fluxo de código de autorização do OAuth 2.0 para obter um GitHub Apptoken de acesso do usuário, não um token de acesso de instalação.

Nas configurações do aplicativo, defina a Callback URL como http://localhost. Isso deve corresponder exatamente à URL de Redirecionamento que você usa no Insomnia.
Copie o Client ID do aplicativo, não o App ID. Gerar e copiar um segredo do cliente. Mantenha o segredo seguro e não compartilhe-o em capturas de tela ou código-fonte. Esse fluxo não usa a chave privada do aplicativo.
Em Insomnia, selecione a guia Auth e selecione OAuth 2.0. Se você tiver selecionado anteriormente um método de autenticação diferente, a guia poderá ser rotulada com esse método.

Defina essas configurações com as credenciais do seu próprio aplicativo.

Setting	Valor
Habilitados	✔️
Tipo de permissão	Código de Autorização
URL de Autorização	`https://github.com/login/oauth/authorize`
URL do token de acesso	`https://github.com/login/oauth/access_token`
ID do cliente	Client ID do seu aplicativo
Segredo do Cliente	O segredo do cliente do seu aplicativo
Usar PKCE

Selecionado | | | | Método de desafio por código | SHA-256 | | | | URL de redirecionamento | http://localhost | | Usando o navegador padrão | Deixe desmarcado, a menos que sua empresa tenha o SSO habilitado, o que pode falhar no navegador inserido da Insomnia. Se ele tiver o SSO habilitado, marque esta caixa e siga as instruções para atualizar a URL de redirecionamento do aplicativo | | Scope | Deixe em branco. GitHub Apps use permissões do registro do aplicativo, não escopos OAuth. |

Se você usar GitHub Enterprise Cloud com residência de dados, substitua https://github.com por https://SUBDOMAIN.ghe.com em ambas as URLs do OAuth, em que SUBDOMAIN é o subdomínio da sua empresa. Use a URL da Web, não o nome do host api.SUBDOMAIN.ghe.com.

Clique em Buscar Tokens, entre e autorize o aplicativo como um usuário com as permissões corporativas necessárias. O token de acesso do usuário é limitado às permissões e recursos que o usuário e o aplicativo podem acessar. O Insomnia usa o token buscado para suas solicitações.

Para obter mais informações, consulte Gerando um token de acesso do usuário para um aplicativo GitHub.

Autenticar com um personal access token

Se você usar um personal access token em vez disso, configure a autenticação Bearer.

Selecione o menu Auth e clique em Bearer Token. Se você tiver selecionado anteriormente um método de autenticação diferente, o menu será rotulado com esse método, como "Autenticação Básica".
No campo "TOKEN", insira seu personal access token obtido em uma etapa anterior.

Captura de tela das configurações de autenticação "Bearer" em Insomnia. O campo "TOKEN" é descrito em laranja escuro.

Definir o tipo de conteúdo

Depois de configurar o método de autenticação, defina o tipo de conteúdo da solicitação.

Clique em Cabeçalhos.

Captura de tela das guias de configurações em Insônia. A guia "Cabeçalhos" está descrita em laranja escuro.

Na guia Cabeçalhos, clique em Adicionar.
No campo "cabeçalho", insira Content-Type.
No campo "valor", insira application/json.

Agora você está pronto para começar a fazer consultas.

Um exemplo de consulta usando a API de Contas Empresariais

Esta consulta do GraphQL solicita o número total de public repositórios em cada uma das organizações do seu dispositivo usando a API de Contas Enterprise. Para personalizar essa consulta, substitua <enterprise-account-name> pelo identificador da sua conta corporativa. Por exemplo, se sua conta corporativa estiver localizada em https://github.com/enterprises/octo-enterprise, substitua <enterprise-account-name> por octo-enterprise.

query publicRepositoriesByOrganization($slug: String!) {
  enterprise(slug: $slug) {
    ...enterpriseFragment
  }
}

fragment enterpriseFragment on Enterprise {
  ... on Enterprise{
    name
    organizations(first: 100){
      nodes{
        name
        ... on Organization{
          name
          repositories(privacy: PUBLIC){
            totalCount
          }
        }
      }
    }
  }
}

# Passing our Enterprise Account as a variable
variables {
  "slug": "<enterprise-account-name>"
}

O próximo exemplo de consulta GraphQL mostra como é complexo recuperar o número de repositórios public em cada organização sem usar a API de Contas Enterprise. Observe que a API de Contas corporativas do GraphQL simplificou esta tarefa para empresas, pois você só precisa personalizar uma única variável. Para personalizar essa consulta, substitua <name-of-organization-one> e <name-of-organization-two> etc. pelos nomes da organização na sua instância.

# Each organization is queried separately
{
  organizationOneAlias: organization(login: "nameOfOrganizationOne") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}

## How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

Consulte cada organização separadamente

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # How to use a fragment
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... and so on up-to lets say 100
}
# How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

Esta consulta do GraphQL solicita as últimas 5 entradas de registro para uma organização corporativa. Para personalizar essa consulta, substitua <org-name> e <user-name>.

{
  organization(login: "<org-name>") {
    auditLog(last: 5, query: "actor:<user-name>") {
      edges {
        node {
          ... on AuditEntry {
# Get Audit Log Entry by 'Action'
            action
            actorLogin
            createdAt
# User 'Action' was performed on
           user{
              name
                email
            }
          }
        }
      }
    }
  }
}

Para obter mais informações sobre como começar com o GraphQL, consulte Introdução ao GraphQL e Realizar chamadas com o GraphQL.

Campos e tipos do GraphQL para a API de Contas corporativas

Para obter mais detalhes sobre as novas consultas, as mutações e os tipos definidos por esquema disponíveis para uso na API de Contas Enterprise, confira a barra lateral com definições detalhadas do GraphQL de qualquer página de referência do GraphQL.

Você pode acessar os documentos de referência a partir dos clientes GraphQL. Para obter mais informações, consulte Como usar clientes do GraphQL. Para obter outras informações, como detalhes de autenticação e limite de taxa, confira o guides.

Neste artigo