Skip to main content

Getting started with self-hosted runners for your enterprise

You can configure a runner machine for your enterprise so your developers can start automating workflows with GitHub Actions.

Who can use this feature

Enterprise owners can configure policies for GitHub Actions and add self-hosted runners to the enterprise.

About self-hosted runners for GitHub Actions

GitHub Actions allows members of your enterprise to improve productivity by automating every phase of the software development workflow. For more information, see "About GitHub Actions for enterprises."

With GitHub Actions, developers can write and combine individual tasks called actions to create custom workflows. You can host your own runner machine to execute jobs, and this machine is called a self-hosted runner. Os executores auto-hospedados podem ser físicos, virtuais, em um contêiner, no local ou em uma nuvem. A sua máquina do executor conecta-se ao GitHub Enterprise Cloud usando o aplicativo do executor auto-hospedado de GitHub Actions. All runners can run Linux, Windows, or macOS. For more information, see "About self-hosted runners."

Alternatively, you can use runner machines that GitHub hosts. GitHub-hosted runners are outside the scope of this guide. For more information, see "About GitHub-hosted runners."

This guide shows you how to apply a centralized management approach to self-hosted runners for GitHub Actions in your enterprise. In the guide, you'll complete the following tasks.

  1. Configure a limited policy to restrict the actions and reusable workflows that can run within your enterprise
  2. Deploy a self-hosted runner for your enterprise
  3. Create a group to manage access to the runners available to your enterprise
  4. Optionally, further restrict the repositories that can use the runner
  5. Optionally, build custom tooling to automatically scale your self-hosted runners

You'll also find additional information about how to monitor and secure your self-hosted runners, and how to customize the software on your runner machines.

After you finish the guide, members of your enterprise will be able to run workflow jobs from GitHub Actions on a self-hosted runner machine.

Prerequisites

1. Configure policies for GitHub Actions

First, enable GitHub Actions for all organizations, and configure a policy to restrict the actions and reusable workflows that can run within your enterprise on GitHub Enterprise Cloud. Optionally, organization owners can further restrict these policies for each organization.

  1. No canto superior direito do GitHub.com, clique na foto do seu perfil e em Suas empresas. "Suas empresas" no menu suspenso na foto de perfil no GitHub Enterprise Cloud

  2. Na lista de empresas, clique na empresa que você deseja visualizar. Nome de uma empresa na lista das suas empresas

  3. Na barra lateral da empresa, clique em Políticas. Guia Políticas na barra lateral da conta corporativa

  4. Em " Políticas", clique em Actions.

  5. Under "Policies", select Enable for all organizations.

    Screenshot of "Enable for all organizations" policy for GitHub Actions

  6. Select Permitir a empresa e fluxos de trabalho reutilizáveis e ações selecionados que não são empresa and Allow actions created by GitHub to allow local actions and reusable workflows, and actions created by GitHub.

    Screenshot of "Allow select actions" and "Allow actions created by GitHub" for GitHub Actions

  7. Click Save.

You can configure additional policies to restrict the actions available to enterprise members. For more information, see "Enforcing policies for GitHub Actions in your enterprise."

2. Deploy the self-hosted runner for your enterprise

Next, add a self-hosted runner to your enterprise. GitHub Enterprise Cloud will guide you through installation of the necessary software on the runner machine. After you deploy the runner, you can verify connectivity between the runner machine and your enterprise.

Adding the self-hosted runner

  1. No canto superior direito do GitHub.com, clique na foto do seu perfil e em Suas empresas. "Suas empresas" no menu suspenso na foto de perfil no GitHub Enterprise Cloud

  2. Na lista de empresas, clique na empresa que você deseja visualizar. Nome de uma empresa na lista das suas empresas

  3. Na barra lateral da empresa, clique em Políticas. Guia Políticas na barra lateral da conta corporativa

  4. Em " Políticas", clique em Actions.

  5. Clique na guia Executores.

  6. Click New runner, then click New self-hosted runner.

  7. Selecione a imagem e a arquitetura do sistema operacional do computador do executor auto-hospedado.

  8. Você verá instruções mostrando como baixar o executor e instalá-lo em sua máquina de executor auto-hospedada.

    Abra um shell em sua máquina de executor auto-hospedado e execute cada comando shell na ordem mostrada.

    Observação: no Windows, caso você deseje instalar o aplicativo do executor auto-hospedado como um serviço, abra um shell com privilégios de administrador. Também recomendamos que você use C:\actions-runner como diretório para o aplicativo do executor auto-hospedado para que as contas do sistema do Windows possam acessar o diretório do executor.

    As instruções te ajudam a completar estas tarefas:

    • Transferindo e extraindo o aplicativo do executor auto-hospedado.
    • Executar o script config para configurar o aplicativo do executor auto-hospedado e registrá-lo no GitHub Actions. O script config exige a URL de destino e um token de tempo limitado gerado automaticamente para autenticar a solicitação.
    • Executando o aplicativo do executor auto-hospedado para conectar a máquina ao GitHub Actions.

Verificando se o seu executor auto-hospedado foi adicionado com sucesso

Depois de completar as etapas para adicionar um executor auto-hospedado, o executor e seu status serão listados em "Runners".

A aplicação dos executores auto-hospedados deve estar activa para que o executor aceite os trabalhos. Quando o aplicativo do executor estiver conectado a GitHub Enterprise Cloud e pronto para receber trabalhos, você verá a seguinte mensagem no terminal da máquina.

√ Connected to GitHub

2019-10-24 05:45:56Z: Listening for Jobs

3. Manage access to the self-hosted runner using a group

You can create a runner group to manage access to the runner that you added to your enterprise. You'll use the group to choose which organizations can execute jobs from GitHub Actions on the runner.

GitHub Enterprise Cloud adds all new runners to a group. Runners can be in one group at a time. By default, GitHub Enterprise Cloud adds new runners to the "Default" group.

  1. No canto superior direito do GitHub.com, clique na foto do seu perfil e em Suas empresas. "Suas empresas" no menu suspenso na foto de perfil no GitHub Enterprise Cloud

  2. Na lista de empresas, clique na empresa que você deseja visualizar. Nome de uma empresa na lista das suas empresas

  3. Na barra lateral da empresa, clique em Políticas. Guia Políticas na barra lateral da conta corporativa

  4. Em " Políticas", clique em Actions.

  5. Clique na guia Grupos de executores.

  6. Click New runner group.

  7. Under "Group name", type a name for your runner group.

  8. To choose a policy for organization access, under "Organization access", select the Organization access drop-down, and click Selected organizations.

  9. To the right of the drop-down with the organization access policy, click .

  10. Select the organizations you'd like to grant access to the runner group.

  11. Optionally, to allow public repositories in the selected organizations to use runners in the group, select Allow public repositories.

    Warning:

    Recomendamos que você use apenas executores auto-hospedados com repositórios privados. Isso acontece porque as bifurcações do seu repositório público podem executar código perigoso em seu computador de executor auto-hospedado criando uma solicitação de pull que executa o código em um fluxo de trabalho.

    For more information, see "About self-hosted runners."

  12. Click Create group to create the group and apply the policy.

  13. Click the "Runners" tab.

  14. In the list of runners, click the runner that you deployed in the previous section.

  15. Click Edit.

  16. Click Runner groups .

  17. In the list of runner groups, click the name of the group that you previously created.

  18. Click Save to move the runner to the group.

You've now deployed a self-hosted runner that can run jobs from GitHub Actions within the organizations that you specified.

4. Further restrict access to the self-hosted runner

Optionally, organization owners can further restrict the access policy of the runner group that you created. For example, an organization owner could allow only certain repositories in the organization to use the runner group.

For more information, see "Managing access to self-hosted runners using groups."

5. Automatically scale your self-hosted runners

Optionally, you can build custom tooling to automatically scale the self-hosted runners for your enterprise. For example, your tooling can respond to webhook events from GitHub.com to automatically scale a cluster of runner machines. For more information, see "Autoscaling with self-hosted runners."

Next steps

  • You can monitor self-hosted runners and troubleshoot common issues. For more information, see "Monitoring and troubleshooting self-hosted runners."

  • GitHub recommends that you review security considerations for self-hosted runner machines. For more information, see "Security hardening for GitHub Actions."

  • If you use GitHub Enterprise Server or GitHub AE, you can manually sync repositories on GitHub.com containing actions to your enterprise on GitHub Enterprise Server or GitHub AE. Alternatively, you can allow members of your enterprise to automatically access actions from GitHub.com by using GitHub Connect. For more information, see the following.

  • You can customize the software available on your self-hosted runner machines, or configure your runners to run software similar to GitHub-hosted runners. The software that powers runner machines for GitHub Actions is open source. For more information, see the actions/runner and actions/runner-images repositories.

Further reading