Lembrando os usuários inativos de usarem sua licença do Copilot GitHub

Use a API GitHub para identificar usuários inativos e ajudá-los a começar.

Quem pode usar esse recurso?

Organization owners and billing managers

GitHub Copilot Business or GitHub Copilot Enterprise

Neste artigo

Quando você está implementando GitHub Copilot em uma empresa, é importante controlar quais usuários estão usando sua licença Copilot, para que você possa responder efetivamente, reatribuindo licenças não utilizadas ou ajudando as pessoas a começarem a usar o Copilot.

Use o ponto de extremidade da API para Listar todas as atribuições de estações do Copilot para uma organização para localizar a data da última atividade de cada usuário que foi atribuído uma licença em uma organização. Em seguida, você pode responder automaticamente filtrando por usuários que não usaram a licença por um determinado período e enviando um lembrete para eles.

Escrevendo a mensagem de lembrete

Seu lembrete para usuários inativos deve ajudar os usuários a superar obstáculos comuns à adoção do Copilot. Recomendamos identificar obstáculos específicos para sua empresa realizando pesquisas ou entrevistando os desenvolvedores.

Por exemplo, a mensagem pode incluir informações e links para ajudar os usuários a:

  • Instalar Copilot no ambiente deles.
  • Configurar o Copilot para funcionar com o proxy ou firewall de sua empresa.
  • Aproveitar ao máximo o Copilot em seu trabalho diário.

Você também deve comunicar claramente qualquer outra ação que tomará se a licença continuar não sendo usada, como revogá-la.

Exemplo de lembrete

Na próxima seção, usaremos essa mensagem em uma automação que cria um problema atribuído a cada usuário inativo.

Notamos que você não usou sua licença atribuída do GitHub Copilot em 30 dias. Aqui estão alguns recursos que podem ajudá-lo a get started:

Se você não precisar mais de acesso ao Copilot, informe-nos sobre esta questão. Se sua licença permanecer inativa por mais 30 dias, a revogaremos para liberar access para outro usuário.

Exemplo de lembrete em Markdown

Markdown
We noticed you haven't used your assigned license for GitHub Copilot in 30 days. Here are some resources that might help you get started:

* If you haven't yet set up Copilot in your environment, see [Setting up GitHub Copilot for yourself](https://docs.github.com/en/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself) or [Troubleshooting common issues with GitHub Copilot](https://docs.github.com/en/copilot/troubleshooting-github-copilot/troubleshooting-common-issues-with-github-copilot).
* For best practices and advice on getting started, see [Best practices for using GitHub Copilot](https://docs.github.com/en/copilot/using-github-copilot/best-practices-for-using-github-copilot) or [Prompt engineering for GitHub Copilot](https://docs.github.com/en/copilot/using-github-copilot/prompt-engineering-for-github-copilot).
* For examples related to specific tasks, see [Copilot Chat Cookbook](https://docs.github.com/en/copilot/example-prompts-for-github-copilot-chat).

If you no longer need access to Copilot, please let us know in this issue. If your license remains inactive for a further 30 days, we'll revoke it to free up access for another user.

Automatizando o recordatório com o GitHub Actions

O fluxo de trabalho de exemplo a seguir usa a API para identificar usuários em uma organização que não usam sua licença há 30 dias ou não a usam desde que a estação foi atribuída e, em seguida, cria um Issue atribuído a cada usuário. Este é um exemplo simples que você pode adaptar para atender às suas necessidades.

Para usar este fluxo de trabalho:

  1. Crie um rótulo no repositório em que os problemas de lembrete serão criados. Dê ao rótulo o nome copilot-reminder. Usaremos essa etiqueta para verificar se uma questão de lembrete já está aberta para cada usuário inativo.

    Para criar um rótulo, confira Gerenciar etiquetas.

  2. Salve sua mensagem de lembrete, como a fornecida em Exemplo de lembrete em Markdown, como uma variável do GitHub Actions em seu repositório ou organização. Chame a variável COPILOT_REMINDER_MESSAGE.

    Para criar uma variável, confira Armazenar informações em variáveis.

  3. Crie um personal access token com permissão para chamar o ponto de extremidade de API Listar todas as atribuições de estações do Copilot para uma organização. Por exemplo, crie um token refinado com os seguintes detalhes: * Proprietário do recurso: a organização em que você está procurando usuários inativos. * Permissões da organização: GitHub Copilot Business (somente leitura).

    Para criar um token, consulte Gerenciar seus tokens de acesso pessoal.

  4. Salve o token de acesso como um segredo GitHub Actions no seu repositório ou na organização. Chame o segredo COPILOT_LICENSE_READ.

    Para criar um segredo, consulte Usar segredos em ações do GitHub.

  5. Usando o exemplo abaixo, crie o fluxo de trabalho no repositório em que deseja que os problemas de lembrete sejam criados.

    Se você é novato no GitHub Actions, confira Guia Rápido do GitHub Actions.

  6. Se você quiser criar os problemas em um repositório diferente do em que o fluxo de trabalho está localizado, substitua ${{ github.repository }} nos comandos gh pelo nome do repositório em que você deseja que os problemas de lembrete sejam criados. Por exemplo: octo-org/octo-repo.

Fluxo de trabalho de exemplo

Observação

Este exemplo pressupõe que você atribui licenças por meio de uma organização. Existem endpoints de API semelhantes para contas empresariais e equipes empresariais. Confira Endpoints da API REST para gerenciamento de usuários do Copilot.

YAML
name: Remind inactive users about GitHub Copilot license
on:

Name your workflow

  workflow_dispatch:

Run on demand (enables Run workflow button on the Actions tab to easily trigger a run manually)

  schedule:
    - cron: '0 8 * * *'
jobs:
  context-log:
    runs-on: ubuntu-latest

Run the workflow every day at 8am UTC

    permissions:
      contents: read
      issues: write
    steps:
      - name: Check last GitHub Copilot activity
        id: check-last-activity
        run: |

Modify the default permissions granted to GITHUB_TOKEN

          RESPONSE=$(gh api \
            -H "Accept: application/vnd.github+json" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            -H "Authorization: Bearer ${{ secrets.COPILOT_LICENSE_READ }}" \
            /orgs/${{ github.repository_owner }}/copilot/billing/seats)
          echo "Raw Response from gh api:"
          echo "$RESPONSE"

List all GitHub Copilot seat assignments for an organization

          echo "$RESPONSE" | jq -c '.seats[]' | while read -r seat; do
            LOGIN=$(echo "$seat" | jq -r '.assignee.login')
            LAST_ACTIVITY=$(echo "$seat" | jq -r '.last_activity_at')
            CREATED_AT=$(echo "$seat" | jq -r '.created_at')

Parse and check each user's last_activity_at and created_at

            EXISTING_ISSUES=$(gh issue list --repo ${{ github.repository }} --assignee $LOGIN --label 'copilot-reminder' --json id)

List all open issues with label copilot-reminder

            if [ "$LAST_ACTIVITY" = "null" ]; then
              LAST_ACTIVITY_DATE=$(date -d "$CREATED_AT" +%s)
            else
              LAST_ACTIVITY_DATE=$(date -d "$LAST_ACTIVITY" +%s)
            fi
            THIRTY_DAYS_AGO=$(date -d "30 days ago" +%s)

Get last activity date and convert dates to seconds since epoch for comparison

            if [ "$LAST_ACTIVITY_DATE" -lt "$THIRTY_DAYS_AGO" ] && [ "$EXISTING_ISSUES" = "[]" ]; then
              echo "User $LOGIN has not been active in the last 30 days. Last activity: $LAST_ACTIVITY"
              NEW_ISSUE_URL="$(gh issue create --title "Reminder about your GitHub Copilot license" --body "${{ vars.COPILOT_REMINDER_MESSAGE }}" --repo ${{ github.repository }} --assignee $LOGIN --label 'copilot-reminder')"
            else
              echo "User $LOGIN is active or already has an assigned reminder issue. Last activity: $LAST_ACTIVITY"
            fi
          done

Create issues for inactive users who don't have an existing open issue

        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Set the GH_TOKEN, required for the 'gh issue' commands

# Name your workflow
name: Remind inactive users about GitHub Copilot license

on:
  # Run on demand (enables `Run workflow` button on the Actions tab to easily trigger a run manually)
  workflow_dispatch:
  # Run the workflow every day at 8am UTC
  schedule:
    - cron: '0 8 * * *'

jobs:
  context-log:
    runs-on: ubuntu-latest

    # Modify the default permissions granted to GITHUB_TOKEN
    permissions:
      contents: read
      issues: write

    steps:
      - name: Check last GitHub Copilot activity
        id: check-last-activity
        run: |
          # List all GitHub Copilot seat assignments for an organization
          RESPONSE=$(gh api \
            -H "Accept: application/vnd.github+json" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            -H "Authorization: Bearer ${{ secrets.COPILOT_LICENSE_READ }}" \
            /orgs/${{ github.repository_owner }}/copilot/billing/seats)
          echo "Raw Response from gh api:"
          echo "$RESPONSE"

          # Parse and check each user's `last_activity_at` and `created_at`
          echo "$RESPONSE" | jq -c '.seats[]' | while read -r seat; do
            LOGIN=$(echo "$seat" | jq -r '.assignee.login')
            LAST_ACTIVITY=$(echo "$seat" | jq -r '.last_activity_at')
            CREATED_AT=$(echo "$seat" | jq -r '.created_at')

            # List all open issues with label `copilot-reminder`
            EXISTING_ISSUES=$(gh issue list --repo ${{ github.repository }} --assignee $LOGIN --label 'copilot-reminder' --json id)

            # Get last activity date and convert dates to seconds since epoch for comparison
            if [ "$LAST_ACTIVITY" = "null" ]; then
              LAST_ACTIVITY_DATE=$(date -d "$CREATED_AT" +%s)
            else
              LAST_ACTIVITY_DATE=$(date -d "$LAST_ACTIVITY" +%s)
            fi
            THIRTY_DAYS_AGO=$(date -d "30 days ago" +%s)

            # Create issues for inactive users who don't have an existing open issue
            if [ "$LAST_ACTIVITY_DATE" -lt "$THIRTY_DAYS_AGO" ] && [ "$EXISTING_ISSUES" = "[]" ]; then
              echo "User $LOGIN has not been active in the last 30 days. Last activity: $LAST_ACTIVITY"

              NEW_ISSUE_URL="$(gh issue create --title "Reminder about your GitHub Copilot license" --body "${{ vars.COPILOT_REMINDER_MESSAGE }}" --repo ${{ github.repository }} --assignee $LOGIN --label 'copilot-reminder')"
            else
              echo "User $LOGIN is active or already has an assigned reminder issue. Last activity: $LAST_ACTIVITY"
            fi
          done

        # Set the GH_TOKEN, required for the 'gh issue' commands
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Leitura adicional

  •         [AUTOTITLE](/copilot/reference/metrics-data#last_activity_at)

  •         [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company)

  •         [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api)