From 86656c8e94b16914fe9ec3e2945d3c6c9662e69e Mon Sep 17 00:00:00 2001 From: Laura Coursen Date: Fri, 21 Jan 2022 05:42:04 -0600 Subject: [PATCH] Share actions with your enterprise --- .../creating-actions/about-custom-actions.md | 7 +- content/actions/creating-actions/index.md | 1 + ...ions-and-workflows-with-your-enterprise.md | 39 ++++++ .../finding-and-customizing-actions.md | 114 ++++++++++-------- .../understanding-github-actions.md | 2 + .../security-hardening-for-github-actions.md | 6 + .../advanced-workflow-features.md | 3 + .../using-workflows/reusing-workflows.md | 2 +- ...rets-and-runners-with-your-organization.md | 22 +++- ...ucing-github-actions-to-your-enterprise.md | 6 +- ...ithub-actions-settings-for-a-repository.md | 2 +- data/features/internal-actions.yml | 4 + .../actions/internal-actions-summary.md | 3 + .../outside-collaborators-internal-actions.md | 1 + data/reusables/actions/reusable-workflows.md | 3 +- 15 files changed, 159 insertions(+), 56 deletions(-) create mode 100644 content/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise.md create mode 100644 data/features/internal-actions.yml create mode 100644 data/reusables/actions/internal-actions-summary.md create mode 100644 data/reusables/actions/outside-collaborators-internal-actions.md diff --git a/content/actions/creating-actions/about-custom-actions.md b/content/actions/creating-actions/about-custom-actions.md index 00fecf9091c6..a1a81cc4f100 100644 --- a/content/actions/creating-actions/about-custom-actions.md +++ b/content/actions/creating-actions/about-custom-actions.md @@ -26,7 +26,7 @@ topics: You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {% data variables.product.prodname_dotcom %}'s APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code. {% ifversion fpt or ghec %} -You can write your own actions to use in your workflow or share the actions you build with the {% data variables.product.prodname_dotcom %} community. To share actions you've built, your repository must be public. +You can write your own actions to use in your workflow or share the actions you build with the {% data variables.product.prodname_dotcom %} community. To share actions you've built with everyone, your repository must be public. {% if internal-actions %}To share actions only within your enterprise, your repository must be internal.{% endif %} {% endif %} Actions can run directly on a machine or in a Docker container. You can define an action's inputs, outputs, and environment variables. @@ -69,7 +69,10 @@ If you're developing an action for other people to use, we recommend keeping the Storing an action in its own repository makes it easier for the {% data variables.product.prodname_dotcom %} community to discover the action, narrows the scope of the code base for developers fixing issues and extending the action, and decouples the action's versioning from the versioning of other application code. {% endif %} -{% ifversion fpt or ghec %}If you're building an action that you don't plan to make available to the public, you {% else %} You{% endif %} can store the action's files in any location in your repository. If you plan to combine action, workflow, and application code in a single repository, we recommend storing actions in the `.github` directory. For example, `.github/actions/action-a` and `.github/actions/action-b`. +{% data reusables.actions.internal-actions-summary %} + +{% ifversion fpt or ghec %}If you're building an action that you don't plan to make available to others, you {% else %} You{% endif %} can store the action's files in any location in your repository. If you plan to combine action, workflow, and application code in a single repository, we recommend storing actions in the `.github` directory. For example, `.github/actions/action-a` and `.github/actions/action-b`. + ## Compatibility with {% data variables.product.prodname_ghe_server %} diff --git a/content/actions/creating-actions/index.md b/content/actions/creating-actions/index.md index 1d91ced73d47..defe89ffe5b2 100644 --- a/content/actions/creating-actions/index.md +++ b/content/actions/creating-actions/index.md @@ -21,6 +21,7 @@ children: - /dockerfile-support-for-github-actions - /setting-exit-codes-for-actions - /publishing-actions-in-github-marketplace + - /sharing-actions-and-workflows-with-your-enterprise - /releasing-and-maintaining-actions - /developing-a-third-party-cli-action --- diff --git a/content/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise.md b/content/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise.md new file mode 100644 index 000000000000..dadd57455e0e --- /dev/null +++ b/content/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise.md @@ -0,0 +1,39 @@ +--- +title: Sharing actions and workflows with your enterprise +intro: 'You can share an action or workflow with your enterprise without publishing the action or workflow publicly.' +versions: + feature: 'internal-actions' +type: tutorial +topics: + - Actions + - Action development +shortTitle: Share with your enterprise +--- + +{% note %} + +**Note:** Allowing workflows to access internal repositories is currently in beta and subject to change. + +{% endnote %} + +## About {% data variables.product.prodname_actions %} access to internal repositories + +If your organization is owned by an enterprise account, you can share actions and workflows within your enterprise, without publishing the action or workflow publicly, by allowing {% data variables.product.prodname_actions %} workflows to access an internal repository that contains the action or workflow. + +Any actions or workflows stored in the internal repository can be used in workflows defined in other private and internal repositories owned by the same organization, or by any organization owned by the enterprise. Actions and workflows stored in internal repositories cannot be used in public repositories. + +{% warning %} + +**Warning**: {% data reusables.actions.outside-collaborators-internal-actions %} + +{% endwarning %} + +## Sharing actions and workflows with your enterprise + +1. Store the action or workflow in an internal repository. For more information, see "[About repositories](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories)." +1. Configure the repository to allow access to workflows in other private and internal repositories. For more information, see "[Managing {% data variables.product.prodname_actions %} settings for a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository)." + +## Further reading + +- "[About enterprise accounts](/admin/overview/about-enterprise-accounts)" +- "[Reusing workflows](/actions/using-workflows/reusing-workflows)" \ No newline at end of file diff --git a/content/actions/learn-github-actions/finding-and-customizing-actions.md b/content/actions/learn-github-actions/finding-and-customizing-actions.md index 5b71215cd5ac..ef41c90bec87 100644 --- a/content/actions/learn-github-actions/finding-and-customizing-actions.md +++ b/content/actions/learn-github-actions/finding-and-customizing-actions.md @@ -24,8 +24,9 @@ topics: The actions you use in your workflow can be defined in: -- A public repository -- The same repository where your workflow file references the action +- The same repository as your workflow file{% if internal-actions %} +- An internal repository within the same enterprise account that is configured to allow access to workflows{% endif %} +- Any public repository - A published Docker container image on Docker Hub {% data variables.product.prodname_marketplace %} is a central location for you to find actions created by the {% data variables.product.prodname_dotcom %} community.{% ifversion fpt or ghec %} [{% data variables.product.prodname_marketplace %} page](https://github.com/marketplace/actions/) enables you to filter for actions by category. {% endif %} @@ -46,6 +47,10 @@ You can search and browse actions directly in your repository's workflow editor. ## Adding an action to your workflow +You can add an action to your workflow by referencing the action in your workflow file. + +### Adding an action from {% data variables.product.prodname_marketplace %} + An action's listing page includes the action's version and the workflow syntax required to use the action. To keep your workflow stable even when updates are made to an action, you can reference the version of the action to use by specifying the Git or Docker tag number in your workflow file. 1. Navigate to the action you want to use in your workflow. @@ -58,6 +63,66 @@ An action's listing page includes the action's version and the workflow syntax r {% endif %} +### Adding an action from the same repository + +If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. + +Example repository file structure: + +``` +|-- hello-world (repository) +| |__ .github +| └── workflows +| └── my-first-workflow.yml +| └── actions +| |__ hello-world-action +| └── action.yml +``` + +Example workflow file: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + # This step checks out a copy of your repository. + - uses: actions/checkout@v2 + # This step references the directory that contains the action. + - uses: ./.github/actions/hello-world-action +``` + +The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in "[Metadata syntax for GitHub Actions](/actions/creating-actions/metadata-syntax-for-github-actions)." + +### Adding an action from a different repository + +If an action is defined in a different repository than your workflow file, you can reference the action with the `{owner}/{repo}@{ref}` syntax in your workflow file. + +The action must be stored in a public repository{% if internal-actions %} or an internal repository that is configured to allow access to workflows. For more information, see "[Sharing actions and workflows with your enterprise](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise)."{% else %}.{% endif %} + +```yaml +jobs: + my_first_job: + steps: + - name: My first step + uses: actions/setup-node@v1.1.0 +``` + +### Referencing a container on Docker Hub + +If an action is defined in a published Docker container image on Docker Hub, you must reference the action with the `docker://{image}:{tag}` syntax in your workflow file. To protect your code and data, we strongly recommend you verify the integrity of the Docker container image from Docker Hub before using it in your workflow. + +```yaml +jobs: + my_first_job: + steps: + - name: My first step + uses: docker://alpine:3.8 +``` + +For some examples of Docker actions, see the [Docker-image.yml workflow](https://github.com/actions/starter-workflows/blob/main/ci/docker-image.yml) and "[Creating a Docker container action](/articles/creating-a-docker-container-action)." + + ## Using release management for your custom actions The creators of a community action have the option to use tags, branches, or SHA values to manage releases of the action. Similar to any dependency, you should indicate the version of the action you'd like to use based on your comfort with automatically accepting updates to the action. @@ -127,51 +192,6 @@ outputs: By default, you can use most of the official {% data variables.product.prodname_dotcom %}-authored actions in {% data variables.product.prodname_ghe_managed %}. For more information, see "[Using actions in {% data variables.product.prodname_ghe_managed %}](/admin/github-actions/using-actions-in-github-ae)." {% endif %} -## Referencing an action in the same repository where a workflow file uses the action - -If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. - -Example repository file structure: - -``` -|-- hello-world (repository) -| |__ .github -| └── workflows -| └── my-first-workflow.yml -| └── actions -| |__ hello-world-action -| └── action.yml -``` - -Example workflow file: - -```yaml -jobs: - build: - runs-on: ubuntu-latest - steps: - # This step checks out a copy of your repository. - - uses: actions/checkout@v2 - # This step references the directory that contains the action. - - uses: ./.github/actions/hello-world-action -``` - -The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in "[Metadata syntax for GitHub Actions](/actions/creating-actions/metadata-syntax-for-github-actions)" - -## Referencing a container on Docker Hub - -If an action is defined in a published Docker container image on Docker Hub, you must reference the action with the `docker://{image}:{tag}` syntax in your workflow file. To protect your code and data, we strongly recommend you verify the integrity of the Docker container image from Docker Hub before using it in your workflow. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: docker://alpine:3.8 -``` - -For some examples of Docker actions, see the [Docker-image.yml workflow](https://github.com/actions/starter-workflows/blob/main/ci/docker-image.yml) and "[Creating a Docker container action](/articles/creating-a-docker-container-action)." - ## Next steps To continue learning about {% data variables.product.prodname_actions %}, see "[Essential features of {% data variables.product.prodname_actions %}](/actions/learn-github-actions/essential-features-of-github-actions)." diff --git a/content/actions/learn-github-actions/understanding-github-actions.md b/content/actions/learn-github-actions/understanding-github-actions.md index cc9cd0aca583..1d7f1e36a867 100644 --- a/content/actions/learn-github-actions/understanding-github-actions.md +++ b/content/actions/learn-github-actions/understanding-github-actions.md @@ -64,6 +64,8 @@ An _action_ is a custom application for the {% data variables.product.prodname_a You can write your own actions, or you can find actions to use in your workflows in the {% data variables.product.prodname_marketplace %}. +{% data reusables.actions.internal-actions-summary %} + For more information, see "[Creating actions](/actions/creating-actions)." ### Runners diff --git a/content/actions/security-guides/security-hardening-for-github-actions.md b/content/actions/security-guides/security-hardening-for-github-actions.md index 8b80be9c373c..13e880295367 100644 --- a/content/actions/security-guides/security-hardening-for-github-actions.md +++ b/content/actions/security-guides/security-hardening-for-github-actions.md @@ -196,6 +196,12 @@ You can help mitigate this risk by following these good practices: The same principles described above for using third-party actions also apply to using third-party workflows. You can help mitigate the risks associated with reusing workflows by following the same good practices outlined above. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)." {% endif %} +{% if internal-actions %} +## Allowing workflows to access internal repositories + +{% data reusables.actions.outside-collaborators-internal-actions %} For more information, see "[Sharing actions and workflows with your enterprise](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise)." +{% endif %} + ## Potential impact of a compromised runner These sections consider some of the steps an attacker can take if they're able to run malicious commands on a {% data variables.product.prodname_actions %} runner. diff --git a/content/actions/using-workflows/advanced-workflow-features.md b/content/actions/using-workflows/advanced-workflow-features.md index d4c95e22594b..df1cf877c1c6 100644 --- a/content/actions/using-workflows/advanced-workflow-features.md +++ b/content/actions/using-workflows/advanced-workflow-features.md @@ -164,7 +164,10 @@ To learn more about self-hosted runner labels, see ["Using labels with self-host To learn more about {% data variables.product.prodname_dotcom %}-hosted runner labels, see ["Supported runners and hardware resources"](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources). {% endif %} +{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %} +## Reusing workflows {% data reusables.actions.reusable-workflows %} +{% endif %} {% ifversion fpt or ghes > 3.0 or ghae or ghec %} diff --git a/content/actions/using-workflows/reusing-workflows.md b/content/actions/using-workflows/reusing-workflows.md index cac5ebc6a343..4b170f042dec 100644 --- a/content/actions/using-workflows/reusing-workflows.md +++ b/content/actions/using-workflows/reusing-workflows.md @@ -46,7 +46,7 @@ A reusable workflow can be used by another workflow if {% ifversion ghes or ghec * Both workflows are in the same repository. * The called workflow is stored in a public repository.{% ifversion ghes or ghec or ghae %} -* The called workflow is stored in an internal repository and the settings for that repository allow it to be accessed. For more information, see "[Managing {% data variables.product.prodname_actions %} settings for a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository)."{% endif %} +* The called workflow is stored in an internal repository and the settings for that repository allow it to be accessed. For more information, see {% if internal-actions %}"[Sharing actions and workflows with your enterprise](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise){% else %}"[Managing {% data variables.product.prodname_actions %} settings for a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository){% endif %}."{% endif %} ## Using runners diff --git a/content/actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization.md b/content/actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization.md index 95258466e356..ea1bccfacf9c 100644 --- a/content/actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization.md +++ b/content/actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization.md @@ -20,11 +20,29 @@ type: how_to If you need to share workflows and other {% data variables.product.prodname_actions %} features with your team, then consider collaborating within a {% data variables.product.prodname_dotcom %} organization. An organization allows you to centrally store and manage secrets, artifacts, and self-hosted runners. You can also create starter workflows in the `.github` repository and share them with other users in your organization. -## Using starter workflows +## Sharing {% if internal-actions %}actions and {% endif %}workflows -{% data reusables.actions.workflow-organization-templates %} For more information, see "[Creating starter workflows for your organization](/actions/using-workflows/creating-starter-workflows-for-your-organization)." +{% if internal-actions %} +You can share both individual actions and entire workflows with your organization, with or without publishing the actions or workflows publicly. You can reuse actions and workflows exactly by referencing them in your workflow file, and you can create starter workflows that provide templates for new workflows. +{% else %} +Your organization can share workflows by reusing the workflows exactly or by creating starter workflows that provide templates for new workflows. +{% endif %} + +{% if internal-actions %} +### Sharing actions with your enterprise + +{% data reusables.actions.internal-actions-summary %} +{% endif %} + +{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %} +### Reusing workflows {% data reusables.actions.reusable-workflows %} +{% endif %} + +### Using starter workflows + +{% data reusables.actions.workflow-organization-templates %} For more information, see "[Creating starter workflows for your organization](/actions/using-workflows/creating-starter-workflows-for-your-organization)." ## Sharing secrets within an organization diff --git a/content/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md b/content/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md index 3a0483280d4f..422f522f31e6 100644 --- a/content/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md +++ b/content/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md @@ -66,7 +66,9 @@ There is significant risk in sourcing actions from third-party repositories on { ## Innersourcing -Think about how your enterprise can use features of {% data variables.product.prodname_actions %} to innersource workflows. Innersourcing is a way to incorporate the benefits of open source methodologies into your internal software development cycle. For more information, see [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/) in {% data variables.product.company_short %} Resources. +Think about how your enterprise can use features of {% data variables.product.prodname_actions %} to innersource automation. Innersourcing is a way to incorporate the benefits of open source methodologies into your internal software development cycle. For more information, see [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/) in {% data variables.product.company_short %} Resources. + +{% data reusables.actions.internal-actions-summary %} {% ifversion ghec or ghes > 3.3 or ghae-issue-4757 %} With reusable workflows, your team can call one workflow from another workflow, avoiding exact duplication. Reusable workflows promote best practice by helping your team use workflows that are well designed and have already been tested. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)." @@ -74,7 +76,9 @@ With reusable workflows, your team can call one workflow from another workflow, To provide a starting place for developers building new workflows, you can use starter workflows. This not only saves time for your developers, but promotes consistency and best practice across your enterprise. For more information, see "[Creating starter workflows for your organization](/actions/learn-github-actions/creating-starter-workflows-for-your-organization)." +{% if not internal-actions %} Whenever your workflow developers want to use an action that's stored in a private repository, they must configure the workflow to clone the repository first. To reduce the number of repositories that must be cloned, consider grouping commonly used actions in a single repository. For more information, see "[About custom actions](/actions/creating-actions/about-custom-actions#choosing-a-location-for-your-action)." +{% endif %} ## Managing resources diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md index 9c045efc3a80..579efb137c5a 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md @@ -120,7 +120,7 @@ The default permissions can also be configured in the organization settings. If Members of your enterprise can use internal repositories to work on projects without sharing information publicly. For information, see "[About repositories](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories)." -To configure whether workflows in an internal repository can be accessed from outside the repository: +You can configure whether {% if internal-actions%}actions and {% endif %}workflows in an internal repository can be accessed from outside the repository.{% if internal-actions %} For more information, see "[Sharing actions and workflows with your enterprise](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise)."{% endif %} 1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of the internal repository. 1. Under your repository name, click {% octicon "gear" aria-label="The gear icon" %} **Settings**. diff --git a/data/features/internal-actions.yml b/data/features/internal-actions.yml new file mode 100644 index 000000000000..e4420a21cfe7 --- /dev/null +++ b/data/features/internal-actions.yml @@ -0,0 +1,4 @@ +versions: + ghec: '*' + ghes: '>=3.5' + ghae: 'issue-5610' diff --git a/data/reusables/actions/internal-actions-summary.md b/data/reusables/actions/internal-actions-summary.md new file mode 100644 index 000000000000..3efefb42113b --- /dev/null +++ b/data/reusables/actions/internal-actions-summary.md @@ -0,0 +1,3 @@ +{% if internal-actions %} +To share actions across your enterprise without publishing the actions publicly, you can store the actions in an internal repository, then configure the repository to allow access to {% data variables.product.prodname_actions %} workflows in other repositories owned by the same organization or by any organization in the enterprise. For more information, see "[Sharing actions and workflows with your enterprise](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise)." +{% endif %} \ No newline at end of file diff --git a/data/reusables/actions/outside-collaborators-internal-actions.md b/data/reusables/actions/outside-collaborators-internal-actions.md new file mode 100644 index 000000000000..fcf164b2d1d8 --- /dev/null +++ b/data/reusables/actions/outside-collaborators-internal-actions.md @@ -0,0 +1 @@ +If you make an internal repository in your enterprise accessible to {% data variables.product.prodname_actions %} workflows in other repositories, outside collaborators on the other repositories can indirectly access the internal repository, even though they do not have direct access to the internal repository. The outside collaborators can view logs for workflow runs when actions or workflows from the internal repository are used. \ No newline at end of file diff --git a/data/reusables/actions/reusable-workflows.md b/data/reusables/actions/reusable-workflows.md index 60451866a45c..81a4a7dfeac5 100644 --- a/data/reusables/actions/reusable-workflows.md +++ b/data/reusables/actions/reusable-workflows.md @@ -1,5 +1,4 @@ {% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %} -## Reusing workflows -You can call one workflow from within another workflow. This allows you to reuse workflows, avoiding duplication and making your workflows easier to maintain. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)." +{% ifversion ghes or ghec or ghae %}You can share workflows with your organization, publicly or privately, by calling{% else %} You can call{% endif %} one workflow from within another workflow. This allows you to reuse workflows, avoiding duplication and making your workflows easier to maintain. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)." {% endif %}