jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Merge branch 'main' into repo-sync

Browse Source
This commit is contained in:
Zeke Sikelianos
2020-09-29 15:24:48 -07:00
committed by GitHub
parent 8c911a75ab c9e42a6fb9
commit 2e7cde29c0
14818 changed files with 100341 additions and 100254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/repo-sync.yml vendored
View File

@@ -24,11 +24,11 @@ jobs:
uses: actions/checkout@v2 uses: actions/checkout@v2
- name: Sync repo to branch - name: Sync repo to branch
uses: repo-sync/github-sync@v2.1.0 uses: repo-sync/github-sync@v2
env: env:
GITHUB_TOKEN: ${{ secrets.OCTOMERGER_PAT_WITH_REPO_AND_WORKFLOW_SCOPE }} GITHUB_TOKEN: ${{ secrets.OCTOMERGER_PAT_WITH_REPO_AND_WORKFLOW_SCOPE }}
with: with:
source_repo: ${{ secrets.SOURCE_REPO }} source_repo: ${{ secrets.SOURCE_REPO }} # https://${access_token}@github.com/github/the-other-repo.git
source_branch: main source_branch: main
destination_branch: repo-sync destination_branch: repo-sync
github_token: ${{ secrets.OCTOMERGER_PAT_WITH_REPO_AND_WORKFLOW_SCOPE }} github_token: ${{ secrets.OCTOMERGER_PAT_WITH_REPO_AND_WORKFLOW_SCOPE }}

42
content/actions/creating-actions/about-actions.md
View File

@@ -1,7 +1,7 @@
--- ---
title: About actions title: About actions
intro: 'Actions are individual tasks that you can combine to create jobs and customize your workflow. You can create your own actions, or use and customize actions shared by the {{ site.data.variables.product.prodname_dotcom }} community.' intro: 'Actions are individual tasks that you can combine to create jobs and customize your workflow. You can create your own actions, or use and customize actions shared by the {% data variables.product.prodname_dotcom %} community.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/about-actions - /articles/about-actions
- /github/automating-your-workflow-with-github-actions/about-actions - /github/automating-your-workflow-with-github-actions/about-actions
@@ -12,22 +12,22 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About actions ### About actions
You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {{ site.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. 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.
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
You can write your own actions to use in your workflow or share the actions you build with the {{ site.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, your repository must be public.
{% 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. Actions can run directly on a machine or in a Docker container. You can define an action's inputs, outputs, and environment variables.
### Types of actions ### Types of actions
You can build Docker container and JavaScript actions. Actions require a metadata file to define the inputs, outputs and main entrypoint for your action. The metadata filename must be either `action.yml` or `action.yaml`. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/articles/metadata-syntax-for-github-actions)." You can build Docker container and JavaScript actions. Actions require a metadata file to define the inputs, outputs and main entrypoint for your action. The metadata filename must be either `action.yml` or `action.yaml`. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/articles/metadata-syntax-for-github-actions)."
| Type | Operating system | | Type | Operating system |
| ---- | ------------------- | | ---- | ------------------- |
@@ -37,19 +37,19 @@ You can build Docker container and JavaScript actions. Actions require a metadat
#### Docker container actions #### Docker container actions
Docker containers package the environment with the {{ site.data.variables.product.prodname_actions }} code. This creates a more consistent and reliable unit of work because the consumer of the action does not need to worry about the tools or dependencies. Docker containers package the environment with the {% data variables.product.prodname_actions %} code. This creates a more consistent and reliable unit of work because the consumer of the action does not need to worry about the tools or dependencies.
A Docker container allows you to use specific versions of an operating system, dependencies, tools, and code. For actions that must run in a specific environment configuration, Docker is an ideal option because you can customize the operating system and tools. Because of the latency to build and retrieve the container, Docker container actions are slower than JavaScript actions. A Docker container allows you to use specific versions of an operating system, dependencies, tools, and code. For actions that must run in a specific environment configuration, Docker is an ideal option because you can customize the operating system and tools. Because of the latency to build and retrieve the container, Docker container actions are slower than JavaScript actions.
Docker container actions can only execute on runners with a Linux operating system. {{ site.data.reusables.github-actions.self-hosted-runner-reqs-docker }} Docker container actions can only execute on runners with a Linux operating system. {% data reusables.github-actions.self-hosted-runner-reqs-docker %}
#### JavaScript actions #### JavaScript actions
JavaScript actions can run directly on a runner machine, and separate the action code from the environment used to run the code. Using a JavaScript action simplifies the action code and executes faster than a Docker container action. JavaScript actions can run directly on a runner machine, and separate the action code from the environment used to run the code. Using a JavaScript action simplifies the action code and executes faster than a Docker container action.
{{ site.data.reusables.github-actions.pure-javascript }} {% data reusables.github-actions.pure-javascript %}
If you're developing a Node.js project, the {{ site.data.variables.product.prodname_actions }} Toolkit provides packages that you can use in your project to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository. If you're developing a Node.js project, the {% data variables.product.prodname_actions %} Toolkit provides packages that you can use in your project to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository.
#### Composite run steps actions #### Composite run steps actions
@@ -60,14 +60,14 @@ A _composite run steps_ action allows you to combine multiple workflow run steps
If you're developing an action for other people to use, we recommend keeping the action in its own repository instead of bundling it with other application code. This allows you to version, track, and release the action just like any other software. If you're developing an action for other people to use, we recommend keeping the action in its own repository instead of bundling it with other application code. This allows you to version, track, and release the action just like any other software.
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
Storing an action in its own repository makes it easier for the {{ site.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. 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 %} {% endif %}
{% if currentVersion == "free-pro-team@latest" %}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`. {% if currentVersion == "free-pro-team@latest" %}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`.
### Compatibility with {{ site.data.variables.product.prodname_ghe_server }} ### Compatibility with {% data variables.product.prodname_ghe_server %}
To ensure that your action is compatible with {{ site.data.variables.product.prodname_ghe_server }}, you should make sure that you do not use any hard-coded references to {{ site.data.variables.product.prodname_dotcom }} API URLs. You should instead use environment variables to refer to the {{ site.data.variables.product.prodname_dotcom }} API: To ensure that your action is compatible with {% data variables.product.prodname_ghe_server %}, you should make sure that you do not use any hard-coded references to {% data variables.product.prodname_dotcom %} API URLs. You should instead use environment variables to refer to the {% data variables.product.prodname_dotcom %} API:
- For the REST API, use the `GITHUB_API_URL` environment variable. - For the REST API, use the `GITHUB_API_URL` environment variable.
- For GraphQL, use the `GITHUB_GRAPHQL_URL` environment variable. - For GraphQL, use the `GITHUB_GRAPHQL_URL` environment variable.
@@ -84,7 +84,7 @@ If you're developing an action for other people to use, we recommend using relea
Under this release management approach, users should not be referencing an action's `master` branch, as it's likely to contain the latest code and consequently might be unstable. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues. Under this release management approach, users should not be referencing an action's `master` branch, as it's likely to contain the latest code and consequently might be unstable. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues.
To use a specific action version, users can configure their {{ site.data.variables.product.prodname_actions }} workflow to target a tag, a commit's SHA, or a branch named for a release. To use a specific action version, users can configure their {% data variables.product.prodname_actions %} workflow to target a tag, a commit's SHA, or a branch named for a release.
#### Using tags for release management #### Using tags for release management
@@ -139,21 +139,21 @@ We recommend creating a README file to help people learn how to use your action.
- Environment variables the action uses - Environment variables the action uses
- An example of how to use your action in a workflow - An example of how to use your action in a workflow
### Comparing {{ site.data.variables.product.prodname_actions }} to {{ site.data.variables.product.prodname_github_apps}} ### Comparing {% data variables.product.prodname_actions %} to {% data variables.product.prodname_github_apps %}
{{ site.data.variables.product.prodname_marketplace }} offers tools to improve your workflow. Understanding the differences and the benefits of each tool will allow you to select the best tool for your job. For more information about building apps, see "[About apps](/apps/about-apps/)." {% data variables.product.prodname_marketplace %} offers tools to improve your workflow. Understanding the differences and the benefits of each tool will allow you to select the best tool for your job. For more information about building apps, see "[About apps](/apps/about-apps/)."
#### Strengths of GitHub Actions and GitHub Apps #### Strengths of GitHub Actions and GitHub Apps
While both {{ site.data.variables.product.prodname_actions }} and {{ site.data.variables.product.prodname_github_app }}s provide ways to build automation and workflow tools, they each have strengths that make them useful in different ways. While both {% data variables.product.prodname_actions %} and {% data variables.product.prodname_github_app %}s provide ways to build automation and workflow tools, they each have strengths that make them useful in different ways.
{{ site.data.variables.product.prodname_github_apps }}: {% data variables.product.prodname_github_apps %}:
* Run persistently and can react to events quickly. * Run persistently and can react to events quickly.
* Work great when persistent data is needed. * Work great when persistent data is needed.
* Work best with API requests that aren't time consuming. * Work best with API requests that aren't time consuming.
* Run on a server or compute infrastructure that you provide. * Run on a server or compute infrastructure that you provide.
{{ site.data.variables.product.prodname_actions }}: {% data variables.product.prodname_actions %}:
* Provide automation that can perform continuous integration and continuous deployment. * Provide automation that can perform continuous integration and continuous deployment.
* Can run directly on runner machines or in Docker containers. * Can run directly on runner machines or in Docker containers.
* Can include access to a clone of your repository, enabling deployment and publishing tools, code formatters, and command line tools to access your code. * Can include access to a clone of your repository, enabling deployment and publishing tools, code formatters, and command line tools to access your code.
@@ -162,4 +162,4 @@ While both {{ site.data.variables.product.prodname_actions }} and {{ site.data.v
### Further reading ### Further reading
- "[Development tools for {{ site.data.variables.product.prodname_actions }}](/articles/development-tools-for-github-actions)" - "[Development tools for {% data variables.product.prodname_actions %}](/articles/development-tools-for-github-actions)"

10
content/actions/creating-actions/creating-a-composite-run-steps-action.md
View File

@@ -1,14 +1,14 @@
--- ---
title: Creating a composite run steps action title: Creating a composite run steps action
intro: 'In this guide, you''ll learn how to build a composite run steps action.' intro: 'In this guide, you''ll learn how to build a composite run steps action.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
@@ -18,9 +18,9 @@ Once you complete this project, you should understand how to build your own comp
### Prerequisites ### Prerequisites
Before you begin, you'll create a {{ site.data.variables.product.product_name }} repository. Before you begin, you'll create a {% data variables.product.product_name %} repository.
1. Create a new public repository on {{ site.data.variables.product.product_location }}. You can choose any repository name, or use the following `hello-world-composite-run-steps-action` example. You can add these files after your project has been pushed to {{ site.data.variables.product.product_name }}. For more information, see "[Create a new repository](/articles/creating-a-new-repository)." 1. Create a new public repository on {% data variables.product.product_location %}. You can choose any repository name, or use the following `hello-world-composite-run-steps-action` example. You can add these files after your project has been pushed to {% data variables.product.product_name %}. For more information, see "[Create a new repository](/articles/creating-a-new-repository)."
1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)." 1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)."

26
content/actions/creating-actions/creating-a-docker-container-action.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Creating a Docker container action title: Creating a Docker container action
intro: 'This guide shows you the minimal steps required to build a Docker container action. ' intro: 'This guide shows you the minimal steps required to build a Docker container action. '
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/creating-a-docker-container-action - /articles/creating-a-docker-container-action
- /github/automating-your-workflow-with-github-actions/creating-a-docker-container-action - /github/automating-your-workflow-with-github-actions/creating-a-docker-container-action
@@ -12,8 +12,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
@@ -21,18 +21,18 @@ In this guide, you'll learn about the basic components needed to create and use
Once you complete this project, you should understand how to build your own Docker container action and test it in a workflow. Once you complete this project, you should understand how to build your own Docker container action and test it in a workflow.
{{ site.data.reusables.github-actions.self-hosted-runner-reqs-docker }} {% data reusables.github-actions.self-hosted-runner-reqs-docker %}
### Prerequisites ### Prerequisites
You may find it helpful to have a basic understanding of {{ site.data.variables.product.prodname_actions }} environment variables and the Docker container filesystem: You may find it helpful to have a basic understanding of {% data variables.product.prodname_actions %} environment variables and the Docker container filesystem:
- "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)" - "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)"
- "[Virtual environments for {{ site.data.variables.product.prodname_dotcom }}](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners#docker-container-filesystem)" - "[Virtual environments for {% data variables.product.prodname_dotcom %}](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners#docker-container-filesystem)"
Before you begin, you'll need to create a GitHub repository. Before you begin, you'll need to create a GitHub repository.
1. Create a new repository on {{ site.data.variables.product.product_location }}. You can choose any repository name or use "hello-world-docker-action" like this example. For more information, see "[Create a new repository](/articles/creating-a-new-repository)." 1. Create a new repository on {% data variables.product.product_location %}. You can choose any repository name or use "hello-world-docker-action" like this example. For more information, see "[Create a new repository](/articles/creating-a-new-repository)."
1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)." 1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)."
@@ -44,7 +44,7 @@ Before you begin, you'll need to create a GitHub repository.
### Creating a Dockerfile ### Creating a Dockerfile
In your new `hello-world-docker-action` directory, create a new `Dockerfile` file. For more information, see "[Dockerfile support for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/dockerfile-support-for-github-actions)." In your new `hello-world-docker-action` directory, create a new `Dockerfile` file. For more information, see "[Dockerfile support for {% data variables.product.prodname_actions %}](/actions/creating-actions/dockerfile-support-for-github-actions)."
**Dockerfile** **Dockerfile**
```dockerfile ```dockerfile
@@ -60,7 +60,7 @@ ENTRYPOINT ["/entrypoint.sh"]
### Creating an action metadata file ### Creating an action metadata file
Create a new `action.yml` file in the `hello-world-docker-action` directory you created above. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/metadata-syntax-for-github-actions)." Create a new `action.yml` file in the `hello-world-docker-action` directory you created above. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions)."
{% raw %} {% raw %}
**action.yml** **action.yml**
@@ -86,13 +86,13 @@ runs:
This metadata defines one `who-to-greet` input and one `time` output parameter. To pass inputs to the Docker container, you must declare the input using `inputs` and pass the input in the `args` keyword. This metadata defines one `who-to-greet` input and one `time` output parameter. To pass inputs to the Docker container, you must declare the input using `inputs` and pass the input in the `args` keyword.
{{ site.data.variables.product.prodname_dotcom }} will build an image from your `Dockerfile`, and run commands in a new container using this image. {% data variables.product.prodname_dotcom %} will build an image from your `Dockerfile`, and run commands in a new container using this image.
### Writing the action code ### Writing the action code
You can choose any base Docker image and, therefore, any language for your action. The following shell script example uses the `who-to-greet` input variable to print "Hello [who-to-greet]" in the log file. You can choose any base Docker image and, therefore, any language for your action. The following shell script example uses the `who-to-greet` input variable to print "Hello [who-to-greet]" in the log file.
Next, the script gets the current time and sets it as an output variable that actions running later in a job can use. In order for {{ site.data.variables.product.prodname_dotcom }} to recognize output variables, you must use a workflow command in a specific syntax: `echo "::set-output name=<output name>::<value>"`. For more information, see "[Workflow commands for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter)." Next, the script gets the current time and sets it as an output variable that actions running later in a job can use. In order for {% data variables.product.prodname_dotcom %} to recognize output variables, you must use a workflow command in a specific syntax: `echo "::set-output name=<output name>::<value>"`. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter)."
1. Create a new `entrypoint.sh` file in the `hello-world-docker-action` directory. 1. Create a new `entrypoint.sh` file in the `hello-world-docker-action` directory.
@@ -153,7 +153,7 @@ with:
who-to-greet: 'Mona the Octocat' who-to-greet: 'Mona the Octocat'
``` ```
### Commit, tag, and push your action to {{ site.data.variables.product.product_name }} ### Commit, tag, and push your action to {% data variables.product.product_name %}
From your terminal, commit your `action.yml`, `entrypoint.sh`, `Dockerfile`, and `README.md` files. From your terminal, commit your `action.yml`, `entrypoint.sh`, `Dockerfile`, and `README.md` files.
@@ -170,7 +170,7 @@ git push --follow-tags
Now you're ready to test your action out in a workflow. When an action is in a private repository, the action can only be used in workflows in the same repository. Public actions can be used by workflows in any repository. Now you're ready to test your action out in a workflow. When an action is in a private repository, the action can only be used in workflows in the same repository. Public actions can be used by workflows in any repository.
{{ site.data.reusables.actions.enterprise-marketplace-actions }} {% data reusables.actions.enterprise-marketplace-actions %}
#### Example using a public action #### Example using a public action

18
content/actions/creating-actions/creating-a-javascript-action.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Creating a JavaScript action title: Creating a JavaScript action
intro: 'In this guide, you''ll learn how to build a JavaScript action using the actions toolkit.' intro: 'In this guide, you''ll learn how to build a JavaScript action using the actions toolkit.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/creating-a-javascript-action - /articles/creating-a-javascript-action
- /github/automating-your-workflow-with-github-actions/creating-a-javascript-action - /github/automating-your-workflow-with-github-actions/creating-a-javascript-action
@@ -12,18 +12,18 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
In this guide, you'll learn about the basic components needed to create and use a packaged JavaScript action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name. In this guide, you'll learn about the basic components needed to create and use a packaged JavaScript action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name.
This guide uses the {{ site.data.variables.product.prodname_actions }} Toolkit Node.js module to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository. This guide uses the {% data variables.product.prodname_actions %} Toolkit Node.js module to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository.
Once you complete this project, you should understand how to build your own JavaScript action and test it in a workflow. Once you complete this project, you should understand how to build your own JavaScript action and test it in a workflow.
{{ site.data.reusables.github-actions.pure-javascript }} {% data reusables.github-actions.pure-javascript %}
### Prerequisites ### Prerequisites
@@ -33,7 +33,7 @@ Before you begin, you'll need to download Node.js and create a GitHub repository
https://nodejs.org/en/download/current/ https://nodejs.org/en/download/current/
1. Create a new repository on {{ site.data.variables.product.product_location }}. You can choose any repository name or use "hello-world-javascript-action" like this example. You can add these files after your project has been pushed to {{ site.data.variables.product.product_name }}. For more information, see "[Create a new repository](/articles/creating-a-new-repository)." 1. Create a new repository on {% data variables.product.product_location %}. You can choose any repository name or use "hello-world-javascript-action" like this example. You can add these files after your project has been pushed to {% data variables.product.product_name %}. For more information, see "[Create a new repository](/articles/creating-a-new-repository)."
1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)." 1. Clone your repository to your computer. For more information, see "[Cloning a repository](/articles/cloning-a-repository)."
@@ -51,7 +51,7 @@ Before you begin, you'll need to download Node.js and create a GitHub repository
### Creating an action metadata file ### Creating an action metadata file
Create a new file `action.yml` in the `hello-world-javascript-action` directory with the following example code. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/metadata-syntax-for-github-actions)." Create a new file `action.yml` in the `hello-world-javascript-action` directory with the following example code. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions)."
**action.yml** **action.yml**
@@ -162,7 +162,7 @@ with:
### Commit, tag, and push your action to GitHub ### Commit, tag, and push your action to GitHub
{{ site.data.variables.product.product_name }} downloads each action run in a workflow during runtime and executes it as a complete package of code before you can use workflow commands like `run` to interact with the runner machine. This means you must include any package dependencies required to run the JavaScript code. You'll need to check in the toolkit `core` and `github` packages to your action's repository. {% data variables.product.product_name %} downloads each action run in a workflow during runtime and executes it as a complete package of code before you can use workflow commands like `run` to interact with the runner machine. This means you must include any package dependencies required to run the JavaScript code. You'll need to check in the toolkit `core` and `github` packages to your action's repository.
From your terminal, commit your `action.yml`, `index.js`, `node_modules`, `package.json`, `package-lock.json`, and `README.md` files. If you added a `.gitignore` file that lists `node_modules`, you'll need to remove that line to commit the `node_modules` directory. From your terminal, commit your `action.yml`, `index.js`, `node_modules`, `package.json`, `package-lock.json`, and `README.md` files. If you added a `.gitignore` file that lists `node_modules`, you'll need to remove that line to commit the `node_modules` directory.
@@ -205,7 +205,7 @@ git push --follow-tags
Now you're ready to test your action out in a workflow. When an action is in a private repository, the action can only be used in workflows in the same repository. Public actions can be used by workflows in any repository. Now you're ready to test your action out in a workflow. When an action is in a private repository, the action can only be used in workflows in the same repository. Public actions can be used by workflows in any repository.
{{ site.data.reusables.actions.enterprise-marketplace-actions }} {% data reusables.actions.enterprise-marketplace-actions %}
#### Example using a public action #### Example using a public action

20
content/actions/creating-actions/dockerfile-support-for-github-actions.md
View File

@@ -2,7 +2,7 @@
title: Dockerfile support for GitHub Actions title: Dockerfile support for GitHub Actions
shortTitle: Docker shortTitle: Docker
intro: 'When creating a `Dockerfile` for a Docker container action, you should be aware of how some Docker instructions interact with GitHub Actions and an action''s metadata file.' intro: 'When creating a `Dockerfile` for a Docker container action, you should be aware of how some Docker instructions interact with GitHub Actions and an action''s metadata file.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/building-actions/dockerfile-support-for-github-actions - /actions/building-actions/dockerfile-support-for-github-actions
versions: versions:
@@ -10,8 +10,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About Dockerfile instructions ### About Dockerfile instructions
@@ -19,7 +19,7 @@ A `Dockerfile` contains instructions and arguments that define the contents and
### Dockerfile instructions and overrides ### Dockerfile instructions and overrides
Some Docker instructions interact with GitHub Actions, and an action's metadata file can override some Docker instructions. Ensure that you are familiar with how your Dockerfile interacts with {{ site.data.variables.product.prodname_actions }} to prevent any unexpected behavior. Some Docker instructions interact with GitHub Actions, and an action's metadata file can override some Docker instructions. Ensure that you are familiar with how your Dockerfile interacts with {% data variables.product.prodname_actions %} to prevent any unexpected behavior.
#### USER #### USER
@@ -37,11 +37,11 @@ These are some best practices when setting the `FROM` argument:
#### WORKDIR #### WORKDIR
{{ site.data.variables.product.product_name }} sets the working directory path in the `GITHUB_WORKSPACE` environment variable. It's recommended to not use the `WORKDIR` instruction in your `Dockerfile`. Before the action executes, {{ site.data.variables.product.product_name }} will mount the `GITHUB_WORKSPACE` directory on top of anything that was at that location in the Docker image and set `GITHUB_WORKSPACE` as the working directory. For more information, see "[Using environment variables](/actions/configuring-and-managing-workflows/using-environment-variables)" and the [WORKDIR reference](https://docs.docker.com/engine/reference/builder/#workdir) in the Docker documentation. {% data variables.product.product_name %} sets the working directory path in the `GITHUB_WORKSPACE` environment variable. It's recommended to not use the `WORKDIR` instruction in your `Dockerfile`. Before the action executes, {% data variables.product.product_name %} will mount the `GITHUB_WORKSPACE` directory on top of anything that was at that location in the Docker image and set `GITHUB_WORKSPACE` as the working directory. For more information, see "[Using environment variables](/actions/configuring-and-managing-workflows/using-environment-variables)" and the [WORKDIR reference](https://docs.docker.com/engine/reference/builder/#workdir) in the Docker documentation.
#### ENTRYPOINT #### ENTRYPOINT
If you define `entrypoint` in an action's metadata file, it will override the `ENTRYPOINT` defined in the `Dockerfile`. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/metadata-syntax-for-github-actions/#runsentrypoint)." If you define `entrypoint` in an action's metadata file, it will override the `ENTRYPOINT` defined in the `Dockerfile`. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions/#runsentrypoint)."
The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction. For more information about _exec_ and _shell_ form, see the [ENTRYPOINT reference](https://docs.docker.com/engine/reference/builder/#entrypoint) in the Docker documentation. The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction. For more information about _exec_ and _shell_ form, see the [ENTRYPOINT reference](https://docs.docker.com/engine/reference/builder/#entrypoint) in the Docker documentation.
@@ -73,7 +73,7 @@ ENTRYPOINT ["/entrypoint.sh"]
##### Example *entrypoint.sh* file ##### Example *entrypoint.sh* file
Using the example Dockerfile above, {{ site.data.variables.product.product_name }} will send the `args` configured in the action's metadata file as arguments to `entrypoint.sh`. Add the `#!/bin/sh` [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top of the `entrypoint.sh` file to explicitly use the system's [POSIX](https://en.wikipedia.org/wiki/POSIX)-compliant shell. Using the example Dockerfile above, {% data variables.product.product_name %} will send the `args` configured in the action's metadata file as arguments to `entrypoint.sh`. Add the `#!/bin/sh` [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top of the `entrypoint.sh` file to explicitly use the system's [POSIX](https://en.wikipedia.org/wiki/POSIX)-compliant shell.
``` sh ``` sh
#!/bin/sh #!/bin/sh
@@ -96,12 +96,12 @@ Error response from daemon: OCI runtime create failed: container_linux.go:348: s
#### CMD #### CMD
If you define `args` in the action's metadata file, `args` will override the `CMD` instruction specified in the `Dockerfile`. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/metadata-syntax-for-github-actions#runsargs)". If you define `args` in the action's metadata file, `args` will override the `CMD` instruction specified in the `Dockerfile`. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#runsargs)".
If you use `CMD` in your `Dockerfile`, follow these guidelines: If you use `CMD` in your `Dockerfile`, follow these guidelines:
{{ site.data.reusables.github-actions.dockerfile-guidelines }} {% data reusables.github-actions.dockerfile-guidelines %}
### Supported Linux capabilities ### Supported Linux capabilities
{{ site.data.variables.product.prodname_actions }} supports the default Linux capabilities that Docker supports. Capabilities can't be added or removed. For more information about the default Linux capabilities that Docker supports, see "[Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)" in the Docker documentation. To learn more about Linux capabilities, see "[Overview of Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html)" in the Linux man-pages. {% data variables.product.prodname_actions %} supports the default Linux capabilities that Docker supports. Capabilities can't be added or removed. For more information about the default Linux capabilities that Docker supports, see "[Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)" in the Docker documentation. To learn more about Linux capabilities, see "[Overview of Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html)" in the Linux man-pages.

6
content/actions/creating-actions/index.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Creating actions title: Creating actions
intro: 'You can create your own actions, use and customize actions shared by the {{ site.data.variables.product.prodname_dotcom }} community, or write and share the actions you build.' intro: 'You can create your own actions, use and customize actions shared by the {% data variables.product.prodname_dotcom %} community, or write and share the actions you build.'
redirect_from: redirect_from:
- /articles/building-actions - /articles/building-actions
- /github/automating-your-workflow-with-github-actions/building-actions - /github/automating-your-workflow-with-github-actions/building-actions
@@ -12,8 +12,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{% link_in_list /about-actions %} {% link_in_list /about-actions %}
{% link_in_list /creating-a-docker-container-action %} {% link_in_list /creating-a-docker-container-action %}

38
content/actions/creating-actions/metadata-syntax-for-github-actions.md
View File

@@ -2,7 +2,7 @@
title: Metadata syntax for GitHub Actions title: Metadata syntax for GitHub Actions
shortTitle: Metadata syntax shortTitle: Metadata syntax
intro: You can create actions to perform tasks in your repository. Actions require a metadata file that uses YAML syntax. intro: You can create actions to perform tasks in your repository. Actions require a metadata file that uses YAML syntax.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/metadata-syntax-for-github-actions - /articles/metadata-syntax-for-github-actions
- /github/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions - /github/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions
@@ -13,10 +13,10 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About YAML syntax for {{ site.data.variables.product.prodname_actions }} ### About YAML syntax for {% data variables.product.prodname_actions %}
Docker and JavaScript actions require a metadata file. The metadata filename must be either `action.yml` or `action.yaml`. The data in the metadata file defines the inputs, outputs and main entrypoint for your action. Docker and JavaScript actions require a metadata file. The metadata filename must be either `action.yml` or `action.yaml`. The data in the metadata file defines the inputs, outputs and main entrypoint for your action.
@@ -24,7 +24,7 @@ Action metadata files use YAML syntax. If you're new to YAML, you can read "[Lea
### **`name`** ### **`name`**
**Required** The name of your action. {{ site.data.variables.product.prodname_dotcom }} displays the `name` in the **Actions** tab to help visually identify actions in each job. **Required** The name of your action. {% data variables.product.prodname_dotcom %} displays the `name` in the **Actions** tab to help visually identify actions in each job.
### **`author`** ### **`author`**
@@ -36,11 +36,11 @@ Action metadata files use YAML syntax. If you're new to YAML, you can read "[Lea
### **`inputs`** ### **`inputs`**
**Optional** Input parameters allow you to specify data that the action expects to use during runtime. {{ site.data.variables.product.prodname_dotcom }} stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids. **Optional** Input parameters allow you to specify data that the action expects to use during runtime. {% data variables.product.prodname_dotcom %} stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids.
#### Example #### Example
This example configures two inputs: numOctocats and octocatEyeColor. The numOctocats input is not required and will default to a value of '1'. The octocatEyeColor input is required and has no default value. Workflow files that use this action must use the `with` keyword to set an input value for octocatEyeColor. For more information about the `with` syntax, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepswith)." This example configures two inputs: numOctocats and octocatEyeColor. The numOctocats input is not required and will default to a value of '1'. The octocatEyeColor input is required and has no default value. Workflow files that use this action must use the `with` keyword to set an input value for octocatEyeColor. For more information about the `with` syntax, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepswith)."
```yaml ```yaml
@@ -55,7 +55,7 @@ inputs:
``` ```
When you specify an input to an action in a workflow file or use a default input value, {{ site.data.variables.product.prodname_dotcom }} creates an environment variable for the input with the name `INPUT_<VARIABLE_NAME>`. The environment variable created converts input names to uppercase letters and replaces spaces with `_` characters. When you specify an input to an action in a workflow file or use a default input value, {% data variables.product.prodname_dotcom %} creates an environment variable for the input with the name `INPUT_<VARIABLE_NAME>`. The environment variable created converts input names to uppercase letters and replaces spaces with `_` characters.
For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the `INPUT_NUMOCTOCATS` and `INPUT_OCTOCATEYECOLOR` environment variables. For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the `INPUT_NUMOCTOCATS` and `INPUT_OCTOCATEYECOLOR` environment variables.
@@ -79,7 +79,7 @@ For example, if a workflow defined the numOctocats and octocatEyeColor inputs, t
**Optional** Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input. **Optional** Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input.
If you don't declare an output in your action metadata file, you can still set outputs and use them in a workflow. For more information on setting outputs in an action, see "[Workflow commands for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-commands-for-github-actions/#setting-an-output-parameter)." If you don't declare an output in your action metadata file, you can still set outputs and use them in a workflow. For more information on setting outputs in an action, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions/#setting-an-output-parameter)."
#### Example #### Example
@@ -99,7 +99,7 @@ outputs:
### **`outputs`** for composite run steps actions ### **`outputs`** for composite run steps actions
**Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see "[`outputs` for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token. **Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see "[`outputs` for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#outputs)"), but also includes the `value` token.
#### Example #### Example
@@ -121,7 +121,7 @@ runs:
#### **`outputs.<output_id.value>`** #### **`outputs.<output_id.value>`**
**Required** The value that the output parameter will be mapped to. You can set this to a `string` or an expression with context. For example, you can use the `steps` context to set the `value` of an output to the output value of a step. **Required** The value that the output parameter will be mapped to. You can set this to a `string` or an expression with context. For example, you can use the `steps` context to set the `value` of an output to the output value of a step.
For more information on how to use context and expression syntax, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)". For more information on how to use context and expression syntax, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)".
### **`runs`** for JavaScript actions ### **`runs`** for JavaScript actions
@@ -240,7 +240,7 @@ For more information, see "[`github context`](/actions/reference/context-and-exp
##### **`runs.steps.id`** ##### **`runs.steps.id`**
**Optional** A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)". **Optional** A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)".
##### **`runs.steps.env`** ##### **`runs.steps.env`**
@@ -276,7 +276,7 @@ runs:
#### **`pre-entrypoint`** #### **`pre-entrypoint`**
**Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {{ site.data.variables.product.prodname_actions }} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`pre-if`](#pre-if). **Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {% data variables.product.prodname_actions %} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`pre-if`](#pre-if).
The application specified with the [`using`](#runsusing) syntax will execute this file. The application specified with the [`using`](#runsusing) syntax will execute this file.
@@ -304,11 +304,11 @@ runs:
**Optional** Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Use `entrypoint` when the `Dockerfile` does not specify an `ENTRYPOINT` or you want to override the `ENTRYPOINT` instruction. If you omit `entrypoint`, the commands you specify in the Docker `ENTRYPOINT` instruction will execute. The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction. **Optional** Overrides the Docker `ENTRYPOINT` in the `Dockerfile`, or sets it if one wasn't already specified. Use `entrypoint` when the `Dockerfile` does not specify an `ENTRYPOINT` or you want to override the `ENTRYPOINT` instruction. If you omit `entrypoint`, the commands you specify in the Docker `ENTRYPOINT` instruction will execute. The Docker `ENTRYPOINT` instruction has a _shell_ form and _exec_ form. The Docker `ENTRYPOINT` documentation recommends using the _exec_ form of the `ENTRYPOINT` instruction.
For more information about how the `entrypoint` executes, see "[Dockerfile support for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/dockerfile-support-for-github-actions/#entrypoint)." For more information about how the `entrypoint` executes, see "[Dockerfile support for {% data variables.product.prodname_actions %}](/actions/creating-actions/dockerfile-support-for-github-actions/#entrypoint)."
#### **`post-entrypoint`** #### **`post-entrypoint`**
**Optional** Allows you to run a cleanup script once the `runs.entrypoint` action has completed. {{ site.data.variables.product.prodname_actions }} uses `docker run` to launch this action. Because {{ site.data.variables.product.prodname_actions }} runs the script inside a new container using the same base image, the runtime state is different from the main `entrypoint` container. You can access any state you need in either the workspace, `HOME`, or as a `STATE_` variable. The `post-entrypoint:` action always runs by default but you can override this using [`post-if`](#post-if). **Optional** Allows you to run a cleanup script once the `runs.entrypoint` action has completed. {% data variables.product.prodname_actions %} uses `docker run` to launch this action. Because {% data variables.product.prodname_actions %} runs the script inside a new container using the same base image, the runtime state is different from the main `entrypoint` container. You can access any state you need in either the workspace, `HOME`, or as a `STATE_` variable. The `post-entrypoint:` action always runs by default but you can override this using [`post-if`](#post-if).
```yaml ```yaml
runs: runs:
@@ -322,15 +322,15 @@ runs:
#### **`runs.args`** #### **`runs.args`**
**Optional** An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. {{ site.data.variables.product.prodname_dotcom }} passes the `args` to the container's `ENTRYPOINT` when the container starts up. **Optional** An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up.
The `args` are used in place of the `CMD` instruction in a `Dockerfile`. If you use `CMD` in your `Dockerfile`, use the guidelines ordered by preference: The `args` are used in place of the `CMD` instruction in a `Dockerfile`. If you use `CMD` in your `Dockerfile`, use the guidelines ordered by preference:
{{ site.data.reusables.github-actions.dockerfile-guidelines }} {% data reusables.github-actions.dockerfile-guidelines %}
If you need to pass environment variables into an action, make sure your action runs a command shell to perform variable substitution. For example, if your `entrypoint` attribute is set to `"sh -c"`, `args` will be run in a command shell. Alternatively, if your `Dockerfile` uses an `ENTRYPOINT` to run the same command (`"sh -c"`), `args` will execute in a command shell. If you need to pass environment variables into an action, make sure your action runs a command shell to perform variable substitution. For example, if your `entrypoint` attribute is set to `"sh -c"`, `args` will be run in a command shell. Alternatively, if your `Dockerfile` uses an `ENTRYPOINT` to run the same command (`"sh -c"`), `args` will execute in a command shell.
For more information about using the `CMD` instruction with {{ site.data.variables.product.prodname_actions }}, see "[Dockerfile support for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/dockerfile-support-for-github-actions/#cmd)." For more information about using the `CMD` instruction with {% data variables.product.prodname_actions %}, see "[Dockerfile support for {% data variables.product.prodname_actions %}](/actions/creating-actions/dockerfile-support-for-github-actions/#cmd)."
##### Example ##### Example
@@ -348,7 +348,7 @@ runs:
### **`branding`** ### **`branding`**
You can use a color and [Feather](https://feathericons.com/) icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in [{{ site.data.variables.product.prodname_marketplace }}](https://github.com/marketplace?type=actions). You can use a color and [Feather](https://feathericons.com/) icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions).
#### Example #### Example

42
content/actions/creating-actions/publishing-actions-in-github-marketplace.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Publishing actions in GitHub Marketplace title: Publishing actions in GitHub Marketplace
intro: 'You can publish actions in {{ site.data.variables.product.prodname_marketplace }} and share actions you''ve created with the {{ site.data.variables.product.prodname_dotcom }} community.' intro: 'You can publish actions in {% data variables.product.prodname_marketplace %} and share actions you''ve created with the {% data variables.product.prodname_dotcom %} community.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace - /github/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace
- /actions/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace - /actions/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace
@@ -10,56 +10,56 @@ versions:
free-pro-team: '*' free-pro-team: '*'
--- ---
You must accept the terms of service to publish actions in {{ site.data.variables.product.prodname_marketplace }}. You must accept the terms of service to publish actions in {% data variables.product.prodname_marketplace %}.
### About publishing actions ### About publishing actions
Before you can publish an action, you'll need to create an action in your repository. For more information, see "[Creating actions](/actions/creating-actions)." Before you can publish an action, you'll need to create an action in your repository. For more information, see "[Creating actions](/actions/creating-actions)."
When you plan to publish your action to {{ site.data.variables.product.prodname_marketplace }}, you'll need ensure that the repository only includes the metadata file, code, and files necessary for the action. Creating a single repository for the action allows you tag, release, and package the code in a single unit. {{ site.data.variables.product.prodname_dotcom }} also uses the action's metadata on your {{ site.data.variables.product.prodname_marketplace }} page. When you plan to publish your action to {% data variables.product.prodname_marketplace %}, you'll need ensure that the repository only includes the metadata file, code, and files necessary for the action. Creating a single repository for the action allows you tag, release, and package the code in a single unit. {% data variables.product.prodname_dotcom %} also uses the action's metadata on your {% data variables.product.prodname_marketplace %} page.
Actions are published to {{ site.data.variables.product.prodname_marketplace }} immediately and aren't reviewed by {{ site.data.variables.product.prodname_dotcom }} as long as they meet these requirements: Actions are published to {% data variables.product.prodname_marketplace %} immediately and aren't reviewed by {% data variables.product.prodname_dotcom %} as long as they meet these requirements:
- The action must be in a public repository. - The action must be in a public repository.
- Each repository must contain a single action. - Each repository must contain a single action.
- The action's metadata file (`action.yml` or `action.yaml`) must be in the root directory of the repository. - The action's metadata file (`action.yml` or `action.yaml`) must be in the root directory of the repository.
- The `name` in the action's metadata file must be unique. - The `name` in the action's metadata file must be unique.
- The `name` cannot match an existing action name published on {{ site.data.variables.product.prodname_marketplace }}. - The `name` cannot match an existing action name published on {% data variables.product.prodname_marketplace %}.
- The `name` cannot match a user or organization on {{ site.data.variables.product.prodname_dotcom }}, unless the user or organization owner is publishing the action. For example, only the {{ site.data.variables.product.prodname_dotcom }} organization can publish an action named `github`. - The `name` cannot match a user or organization on {% data variables.product.prodname_dotcom %}, unless the user or organization owner is publishing the action. For example, only the {% data variables.product.prodname_dotcom %} organization can publish an action named `github`.
- The `name` cannot match an existing {{ site.data.variables.product.prodname_marketplace }} category. - The `name` cannot match an existing {% data variables.product.prodname_marketplace %} category.
- {{ site.data.variables.product.prodname_dotcom }} reserves the names of {{ site.data.variables.product.prodname_dotcom }} features. - {% data variables.product.prodname_dotcom %} reserves the names of {% data variables.product.prodname_dotcom %} features.
### Publishing an action ### Publishing an action
You can add the action you've created to {{ site.data.variables.product.prodname_marketplace }} by tagging it as a new release and publishing it. You can add the action you've created to {% data variables.product.prodname_marketplace %} by tagging it as a new release and publishing it.
To draft a new release and publish the action to {{ site.data.variables.product.prodname_marketplace }}, follow these instructions: To draft a new release and publish the action to {% data variables.product.prodname_marketplace %}, follow these instructions:
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
1. When a repository contains an action metadata file (`action.yml` or `action.yaml`), you'll see a banner to publish the action to {{ site.data.variables.product.prodname_marketplace }}. Click **Draft a release**. 1. When a repository contains an action metadata file (`action.yml` or `action.yaml`), you'll see a banner to publish the action to {% data variables.product.prodname_marketplace %}. Click **Draft a release**.
![Publish this action to markeplace button](/assets/images/help/repository/publish-github-action-to-markeplace-button.png) ![Publish this action to markeplace button](/assets/images/help/repository/publish-github-action-to-markeplace-button.png)
1. Select **Publish this action to the {{ site.data.variables.product.prodname_marketplace }}**. If you can't select the **Publish this action to the {{ site.data.variables.product.prodname_marketplace }}** checkbox, you'll need to read and accept the {{ site.data.variables.product.prodname_marketplace }} agreement first. 1. Select **Publish this action to the {% data variables.product.prodname_marketplace %}**. If you can't select the **Publish this action to the {% data variables.product.prodname_marketplace %}** checkbox, you'll need to read and accept the {% data variables.product.prodname_marketplace %} agreement first.
![Select publish to Marketplace](/assets/images/help/repository/marketplace_actions_publish.png) ![Select publish to Marketplace](/assets/images/help/repository/marketplace_actions_publish.png)
1. If the labels in your metadata file contain any problems, you will see an error message. 1. If the labels in your metadata file contain any problems, you will see an error message.
![See notification](/assets/images/help/repository/marketplace_actions_fixerrors.png) ![See notification](/assets/images/help/repository/marketplace_actions_fixerrors.png)
1. If you see any on-screen suggestions, address them by updating your metadata file. Once complete, you will see an "Everything looks good!" message. 1. If you see any on-screen suggestions, address them by updating your metadata file. Once complete, you will see an "Everything looks good!" message.
![Fix errors](/assets/images/help/repository/marketplace_actions_looksgood.png) ![Fix errors](/assets/images/help/repository/marketplace_actions_looksgood.png)
1. Choose a "Primary Category" and, optionally, "Another Category" which will help people find your action in {{ site.data.variables.product.prodname_marketplace }}. 1. Choose a "Primary Category" and, optionally, "Another Category" which will help people find your action in {% data variables.product.prodname_marketplace %}.
![Choose category](/assets/images/help/repository/marketplace_actions_categories.png) ![Choose category](/assets/images/help/repository/marketplace_actions_categories.png)
1. Tag your Action with a version, and add a release title. This helps people know what changes or features the release includes. People will see the version in the action's dedicated {{ site.data.variables.product.prodname_marketplace }} page. 1. Tag your Action with a version, and add a release title. This helps people know what changes or features the release includes. People will see the version in the action's dedicated {% data variables.product.prodname_marketplace %} page.
![Tag a version](/assets/images/help/repository/marketplace_actions_version.png) ![Tag a version](/assets/images/help/repository/marketplace_actions_version.png)
1. Complete all other fields and click **Publish release**. Publishing requires you to use two-factor authentication. For more information, see "[Configuring two-factor authentication](/articles/configuring-two-factor-authentication/)." 1. Complete all other fields and click **Publish release**. Publishing requires you to use two-factor authentication. For more information, see "[Configuring two-factor authentication](/articles/configuring-two-factor-authentication/)."
![Publish the release](/assets/images/help/repository/marketplace_actions_publishrelease.png) ![Publish the release](/assets/images/help/repository/marketplace_actions_publishrelease.png)
### Removing an action from {{ site.data.variables.product.prodname_marketplace }} ### Removing an action from {% data variables.product.prodname_marketplace %}
To remove a published action from {{ site.data.variables.product.prodname_marketplace }}, you'll need to update each published release. Perform the following steps for each release of the action you've published to {{ site.data.variables.product.prodname_marketplace }}. To remove a published action from {% data variables.product.prodname_marketplace %}, you'll need to update each published release. Perform the following steps for each release of the action you've published to {% data variables.product.prodname_marketplace %}.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.releases }} {% data reusables.repositories.releases %}
3. On the Releases page, to the right of the release you want to edit, click **Edit**. 3. On the Releases page, to the right of the release you want to edit, click **Edit**.
![Release edit button](/assets/images/help/releases/release-edit-btn.png) ![Release edit button](/assets/images/help/releases/release-edit-btn.png)
4. Select **Publish this action to the {{ site.data.variables.product.prodname_marketplace }}** to remove the check from the box. 4. Select **Publish this action to the {% data variables.product.prodname_marketplace %}** to remove the check from the box.
![Publish this action button](/assets/images/help/repository/actions-marketplace-unpublish.png) ![Publish this action button](/assets/images/help/repository/actions-marketplace-unpublish.png)
5. Click **Update release** at the bottom of the page. 5. Click **Update release** at the bottom of the page.
![Update release button](/assets/images/help/repository/actions-marketplace-update-release.png) ![Update release button](/assets/images/help/repository/actions-marketplace-update-release.png)

10
content/actions/creating-actions/setting-exit-codes-for-actions.md
View File

@@ -1,8 +1,8 @@
--- ---
title: Setting exit codes for actions title: Setting exit codes for actions
shortTitle: Setting exit codes shortTitle: Setting exit codes
intro: 'You can use exit codes to set the status of an action. {{ site.data.variables.product.prodname_dotcom }} displays statuses to indicate passing or failing actions.' intro: 'You can use exit codes to set the status of an action. {% data variables.product.prodname_dotcom %} displays statuses to indicate passing or failing actions.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/building-actions/setting-exit-codes-for-actions - /actions/building-actions/setting-exit-codes-for-actions
versions: versions:
@@ -10,12 +10,12 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About exit codes ### About exit codes
{{ site.data.variables.product.prodname_dotcom }} uses the exit code to set the action's check run status, which can be `success` or `failure`. {% data variables.product.prodname_dotcom %} uses the exit code to set the action's check run status, which can be `success` or `failure`.
Exit status | Check run status | Description Exit status | Check run status | Description
------------|------------------|------------ ------------|------------------|------------

6
content/actions/guides/about-continuous-integration.md
View File

@@ -12,8 +12,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About continuous integration ### About continuous integration
@@ -43,7 +43,7 @@ For a definition of common terms, see "[Core concepts for {% data variables.prod
{% data variables.product.product_name %} offers CI workflow templates for a variety of languages and frameworks. {% data variables.product.product_name %} offers CI workflow templates for a variety of languages and frameworks.
Browse the complete list of CI workflow templates offered by {% data variables.product.product_name %} in the {% if currentVersion == "free-pro-team@latest" %}[actions/starter-workflows](https://github.com/actions/starter-workflows/tree/master/ci) repository{% else %} `actions/starter-workflows` repository on {{ site.data.variables.product.product_location }}{% endif %}. Browse the complete list of CI workflow templates offered by {% data variables.product.product_name %} in the {% if currentVersion == "free-pro-team@latest" %}[actions/starter-workflows](https://github.com/actions/starter-workflows/tree/master/ci) repository{% else %} `actions/starter-workflows` repository on {% data variables.product.product_location %}{% endif %}.
### Notifications for workflow runs ### Notifications for workflow runs

14
content/actions/guides/about-packaging-with-github-actions.md
View File

@@ -1,7 +1,7 @@
--- ---
title: About packaging with GitHub Actions title: About packaging with GitHub Actions
intro: 'You can set up workflows in {{ site.data.variables.product.prodname_actions }} to produce packages and upload them to {{ site.data.variables.product.prodname_registry }} or another package hosting provider.' intro: 'You can set up workflows in {% data variables.product.prodname_actions %} to produce packages and upload them to {% data variables.product.prodname_registry %} or another package hosting provider.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/about-packaging-with-github-actions - /actions/automating-your-workflow-with-github-actions/about-packaging-with-github-actions
- /actions/publishing-packages-with-github-actions/about-packaging-with-github-actions - /actions/publishing-packages-with-github-actions/about-packaging-with-github-actions
@@ -10,8 +10,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About packaging steps ### About packaging steps
@@ -33,10 +33,10 @@ This will let you run the code in the pull request on your machine, which can he
In addition to uploading packaging artifacts for testing in a continuous integration workflow, you can create workflows that build your project and publish packages to a package registry. In addition to uploading packaging artifacts for testing in a continuous integration workflow, you can create workflows that build your project and publish packages to a package registry.
* **Publish packages to {{ site.data.variables.product.prodname_registry }}** * **Publish packages to {% data variables.product.prodname_registry %}**
{{ site.data.variables.product.prodname_registry }} can act as a package hosting service for many types of packages. You can choose to share your packages with all of {{ site.data.variables.product.prodname_dotcom }}, or private packages to share with collaborators or an organization. For more information, see "[About {{ site.data.variables.product.prodname_registry }}](/github/managing-packages-with-github-packages/about-github-packages)." {% data variables.product.prodname_registry %} can act as a package hosting service for many types of packages. You can choose to share your packages with all of {% data variables.product.prodname_dotcom %}, or private packages to share with collaborators or an organization. For more information, see "[About {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages/about-github-packages)."
You may want to publish packages to {{ site.data.variables.product.prodname_registry }} on every push into the master branch. This will allow developers on your project to always be able to run and test the latest build out of master easily, by installing it from {{ site.data.variables.product.prodname_registry }}. You may want to publish packages to {% data variables.product.prodname_registry %} on every push into the master branch. This will allow developers on your project to always be able to run and test the latest build out of master easily, by installing it from {% data variables.product.prodname_registry %}.
* **Publish packages to a package registry** * **Publish packages to a package registry**
For many projects, publishing to a package registry is performed whenever a new version of a project is released. For example, a project that produces a JAR file may upload new releases to the Maven Central repository. Or, a .NET project may produce a nuget package and upload it to the NuGet Gallery. For many projects, publishing to a package registry is performed whenever a new version of a project is released. For example, a project that produces a JAR file may upload new releases to the Maven Central repository. Or, a .NET project may produce a nuget package and upload it to the NuGet Gallery.

18
content/actions/guides/about-service-containers.md
View File

@@ -1,7 +1,7 @@
--- ---
title: About service containers title: About service containers
intro: 'You can use service containers to connect databases, web services, memory caches, and other tools to your workflow.' intro: 'You can use service containers to connect databases, web services, memory caches, and other tools to your workflow.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/about-service-containers - /actions/automating-your-workflow-with-github-actions/about-service-containers
- /actions/configuring-and-managing-workflows/about-service-containers - /actions/configuring-and-managing-workflows/about-service-containers
@@ -10,16 +10,16 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About service containers ### About service containers
Service containers are Docker containers that provide a simple and portable way for you to host services that you might need to test or operate your application in a workflow. For example, your workflow might need to run integration tests that require access to a database and memory cache. Service containers are Docker containers that provide a simple and portable way for you to host services that you might need to test or operate your application in a workflow. For example, your workflow might need to run integration tests that require access to a database and memory cache.
You can configure service containers for each job in a workflow. {{ site.data.variables.product.prodname_dotcom }} creates a fresh Docker container for each service configured in the workflow, and destroys the service container when the job completes. Steps in a job can communicate with all service containers that are part of the same job. You can configure service containers for each job in a workflow. {% data variables.product.prodname_dotcom %} creates a fresh Docker container for each service configured in the workflow, and destroys the service container when the job completes. Steps in a job can communicate with all service containers that are part of the same job.
{{ site.data.reusables.github-actions.docker-container-os-support }} {% data reusables.github-actions.docker-container-os-support %}
### Communicating with service containers ### Communicating with service containers
@@ -27,7 +27,7 @@ You can configure jobs in a workflow to run directly on a runner machine or in a
#### Running jobs in a container #### Running jobs in a container
When you run jobs in a container, {{ site.data.variables.product.prodname_dotcom }} connects service containers to the job using Docker's user-defined bridge networks. For more information, see "[Use bridge networks](https://docs.docker.com/network/bridge/)" in the Docker documentation. When you run jobs in a container, {% data variables.product.prodname_dotcom %} connects service containers to the job using Docker's user-defined bridge networks. For more information, see "[Use bridge networks](https://docs.docker.com/network/bridge/)" in the Docker documentation.
Running the job and services in a container simplifies network access. You can access a service container using the label you configure in the workflow. The hostname of the service container is automatically mapped to the label name. For example, if you create a service container with the label `redis`, the hostname of the service container is `redis`. Running the job and services in a container simplifies network access. You can access a service container using the label you configure in the workflow. The hostname of the service container is automatically mapped to the label name. For example, if you create a service container with the label `redis`, the hostname of the service container is `redis`.
@@ -35,7 +35,7 @@ You don't need to configure any ports for service containers. By default, all co
#### Running jobs on the runner machine #### Running jobs on the runner machine
When running jobs directly on the runner machine, you can access service containers using `localhost:<port>` or `127.0.0.1:<port>`. {{ site.data.variables.product.prodname_dotcom }} configures the container network to enable communication from the service container to the Docker host. When running jobs directly on the runner machine, you can access service containers using `localhost:<port>` or `127.0.0.1:<port>`. {% data variables.product.prodname_dotcom %} configures the container network to enable communication from the service container to the Docker host.
When a job runs directly on a runner machine, the service running in the Docker container does not expose its ports to the job on the runner by default. You need to map ports on the service container to the Docker host. For more information, see "[Mapping Docker host and service container ports](/actions/automating-your-workflow-with-github-actions/about-service-containers#mapping-docker-host-and-service-container-ports)." When a job runs directly on a runner machine, the service running in the Docker container does not expose its ports to the job on the runner by default. You need to map ports on the service container to the Docker host. For more information, see "[Mapping Docker host and service container ports](/actions/automating-your-workflow-with-github-actions/about-service-containers#mapping-docker-host-and-service-container-ports)."
@@ -79,9 +79,9 @@ You can map service containers ports to the Docker host using the `ports` keywor
| `8080:80/udp` | Maps UDP port 80 in the container to port 8080 on the Docker host. | | `8080:80/udp` | Maps UDP port 80 in the container to port 8080 on the Docker host. |
| `8080/udp` | Map a randomly chosen UDP port in the container to UDP port 8080 on the Docker host. | | `8080/udp` | Map a randomly chosen UDP port in the container to UDP port 8080 on the Docker host. |
When you map ports using the `ports` keyword, {{ site.data.variables.product.prodname_dotcom }} uses the `--publish` command to publish the container’s ports to the Docker host. For more information, see "[Docker container networking](https://docs.docker.com/config/containers/container-networking/)" in the Docker documentation. When you map ports using the `ports` keyword, {% data variables.product.prodname_dotcom %} uses the `--publish` command to publish the container’s ports to the Docker host. For more information, see "[Docker container networking](https://docs.docker.com/config/containers/container-networking/)" in the Docker documentation.
When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. {{ site.data.variables.product.prodname_dotcom }} sets the assigned container port in the service container context. For example, for a `redis` service container, if you configured the Docker host port 5432, you can access the corresponding container port using the `job.services.redis.ports[5432]` context. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions#job-context)." When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. {% data variables.product.prodname_dotcom %} sets the assigned container port in the service container context. For example, for a `redis` service container, if you configured the Docker host port 5432, you can access the corresponding container port using the `job.services.redis.ports[5432]` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#job-context)."
#### Example mapping Redis ports #### Example mapping Redis ports

24
content/actions/guides/building-and-testing-java-with-ant.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Building and testing Java with Ant title: Building and testing Java with Ant
intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Ant. intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Ant.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/language-and-framework-guides/building-and-testing-java-with-ant - /actions/language-and-framework-guides/building-and-testing-java-with-ant
versions: versions:
@@ -9,30 +9,30 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Ant build system. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to upload artifacts from a workflow run. This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Ant build system. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to upload artifacts from a workflow run.
{{ site.data.variables.product.prodname_dotcom }}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Ant. For a list of software and the pre-installed versions for JDK and Ant, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". {% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Ant. For a list of software and the pre-installed versions for JDK and Ant, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
### Prerequisites ### Prerequisites
You should be familiar with YAML and the syntax for {{ site.data.variables.product.prodname_actions }}. For more information, see: You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see:
- "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)" - "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)"
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
We recommend that you have a basic understanding of Java and the Ant framework. For more information, see the [Apache Ant Manual](https://ant.apache.org/manual/). We recommend that you have a basic understanding of Java and the Ant framework. For more information, see the [Apache Ant Manual](https://ant.apache.org/manual/).
{{ site.data.reusables.actions.enterprise-setup-prereq }} {% data reusables.actions.enterprise-setup-prereq %}
### Starting with an Ant workflow template ### Starting with an Ant workflow template
{{ site.data.variables.product.prodname_dotcom }} provides an Ant workflow template that will work for most Ant-based Java projects. For more information, see the [Ant workflow template](https://github.com/actions/starter-workflows/blob/master/ci/ant.yml). {% data variables.product.prodname_dotcom %} provides an Ant workflow template that will work for most Ant-based Java projects. For more information, see the [Ant workflow template](https://github.com/actions/starter-workflows/blob/master/ci/ant.yml).
To get started quickly, you can choose the preconfigured Ant template when you create a new workflow. For more information, see the "[{{ site.data.variables.product.prodname_actions }} quickstart](/actions/quickstart)." To get started quickly, you can choose the preconfigured Ant template when you create a new workflow. For more information, see the "[{% data variables.product.prodname_actions %} quickstart](/actions/quickstart)."
You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository. You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository.
@@ -65,9 +65,9 @@ This workflow performs the following steps:
The default workflow templates are excellent starting points when creating your build and test workflow, and you can customize the template to suit your project’s needs. The default workflow templates are excellent starting points when creating your build and test workflow, and you can customize the template to suit your project’s needs.
{{ site.data.reusables.github-actions.example-github-runner }} {% data reusables.github-actions.example-github-runner %}
{{ site.data.reusables.github-actions.java-jvm-architecture }} {% data reusables.github-actions.java-jvm-architecture %}
### Building and testing your code ### Building and testing your code

24
content/actions/guides/building-and-testing-java-with-gradle.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Building and testing Java with Gradle title: Building and testing Java with Gradle
intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Gradle. intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Gradle.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/language-and-framework-guides/building-and-testing-java-with-gradle - /actions/language-and-framework-guides/building-and-testing-java-with-gradle
versions: versions:
@@ -9,30 +9,30 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Gradle build system. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to cache files and upload artifacts from a workflow run. This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Gradle build system. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to cache files and upload artifacts from a workflow run.
{{ site.data.variables.product.prodname_dotcom }}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Gradle. For a list of software and the pre-installed versions for JDK and Gradle, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". {% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Gradle. For a list of software and the pre-installed versions for JDK and Gradle, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
### Prerequisites ### Prerequisites
You should be familiar with YAML and the syntax for {{ site.data.variables.product.prodname_actions }}. For more information, see: You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see:
- "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)" - "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)"
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
We recommend that you have a basic understanding of Java and the Gradle framework. For more information, see [Getting Started](https://docs.gradle.org/current/userguide/getting_started.html) in the Gradle documentation. We recommend that you have a basic understanding of Java and the Gradle framework. For more information, see [Getting Started](https://docs.gradle.org/current/userguide/getting_started.html) in the Gradle documentation.
{{ site.data.reusables.actions.enterprise-setup-prereq }} {% data reusables.actions.enterprise-setup-prereq %}
### Starting with a Gradle workflow template ### Starting with a Gradle workflow template
{{ site.data.variables.product.prodname_dotcom }} provides a Gradle workflow template that will work for most Gradle-based Java projects. For more information, see the [Gradle workflow template](https://github.com/actions/starter-workflows/blob/master/ci/gradle.yml). {% data variables.product.prodname_dotcom %} provides a Gradle workflow template that will work for most Gradle-based Java projects. For more information, see the [Gradle workflow template](https://github.com/actions/starter-workflows/blob/master/ci/gradle.yml).
To get started quickly, you can choose the preconfigured Gradle template when you create a new workflow. For more information, see the "[{{ site.data.variables.product.prodname_actions }} quickstart](/actions/quickstart)." To get started quickly, you can choose the preconfigured Gradle template when you create a new workflow. For more information, see the "[{% data variables.product.prodname_actions %} quickstart](/actions/quickstart)."
You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository. You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository.
@@ -65,9 +65,9 @@ This workflow performs the following steps:
The default workflow templates are excellent starting points when creating your build and test workflow, and you can customize the template to suit your project’s needs. The default workflow templates are excellent starting points when creating your build and test workflow, and you can customize the template to suit your project’s needs.
{{ site.data.reusables.github-actions.example-github-runner }} {% data reusables.github-actions.example-github-runner %}
{{ site.data.reusables.github-actions.java-jvm-architecture }} {% data reusables.github-actions.java-jvm-architecture %}
### Building and testing your code ### Building and testing your code

24
content/actions/guides/building-and-testing-java-with-maven.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Building and testing Java with Maven title: Building and testing Java with Maven
intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Maven. intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Maven.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/language-and-framework-guides/building-and-testing-java-with-maven - /actions/language-and-framework-guides/building-and-testing-java-with-maven
versions: versions:
@@ -9,30 +9,30 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Maven software project management tool. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to cache files and upload artifacts from a workflow run. This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Maven software project management tool. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to cache files and upload artifacts from a workflow run.
{{ site.data.variables.product.prodname_dotcom }}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Maven. For a list of software and the pre-installed versions for JDK and Maven, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". {% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Maven. For a list of software and the pre-installed versions for JDK and Maven, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
### Prerequisites ### Prerequisites
You should be familiar with YAML and the syntax for {{ site.data.variables.product.prodname_actions }}. For more information, see: You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see:
- "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)" - "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)"
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
We recommend that you have a basic understanding of Java and the Maven framework. For more information, see the [Maven Getting Started Guide](http://maven.apache.org/guides/getting-started/index.html) in the Maven documentation. We recommend that you have a basic understanding of Java and the Maven framework. For more information, see the [Maven Getting Started Guide](http://maven.apache.org/guides/getting-started/index.html) in the Maven documentation.
{{ site.data.reusables.actions.enterprise-setup-prereq }} {% data reusables.actions.enterprise-setup-prereq %}
### Starting with a Maven workflow template ### Starting with a Maven workflow template
{{ site.data.variables.product.prodname_dotcom }} provides a Maven workflow template that will work for most Maven-based Java projects. For more information, see the [Maven workflow template](https://github.com/actions/starter-workflows/blob/master/ci/maven.yml). {% data variables.product.prodname_dotcom %} provides a Maven workflow template that will work for most Maven-based Java projects. For more information, see the [Maven workflow template](https://github.com/actions/starter-workflows/blob/master/ci/maven.yml).
To get started quickly, you can choose the preconfigured Maven template when you create a new workflow. For more information, see the "[{{ site.data.variables.product.prodname_actions }} quickstart](/actions/quickstart)." To get started quickly, you can choose the preconfigured Maven template when you create a new workflow. For more information, see the "[{% data variables.product.prodname_actions %} quickstart](/actions/quickstart)."
You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository. You can also add this workflow manually by creating a new file in the `.github/workflows` directory of your repository.
@@ -65,9 +65,9 @@ This workflow performs the following steps:
The default workflow templates are excellent starting points when creating your build and test workflow, and you can customize the template to suit your project’s needs. The default workflow templates are excellent starting points when creating your build and test workflow, and you can customize the template to suit your project’s needs.
{{ site.data.reusables.github-actions.example-github-runner }} {% data reusables.github-actions.example-github-runner %}
{{ site.data.reusables.github-actions.java-jvm-architecture }} {% data reusables.github-actions.java-jvm-architecture %}
### Building and testing your code ### Building and testing your code

28
content/actions/guides/building-and-testing-nodejs.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Building and testing Node.js title: Building and testing Node.js
intro: You can create a continuous integration (CI) workflow to build and test your Node.js project. intro: You can create a continuous integration (CI) workflow to build and test your Node.js project.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/using-nodejs-with-github-actions - /actions/automating-your-workflow-with-github-actions/using-nodejs-with-github-actions
- /actions/language-and-framework-guides/using-nodejs-with-github-actions - /actions/language-and-framework-guides/using-nodejs-with-github-actions
@@ -10,8 +10,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
@@ -21,14 +21,14 @@ This guide shows you how to create a continuous integration (CI) workflow that b
We recommend that you have a basic understanding of Node.js, YAML, workflow configuration options, and how to create a workflow file. For more information, see: We recommend that you have a basic understanding of Node.js, YAML, workflow configuration options, and how to create a workflow file. For more information, see:
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
- "[Getting started with Node.js](https://nodejs.org/en/docs/guides/getting-started-guide/)" - "[Getting started with Node.js](https://nodejs.org/en/docs/guides/getting-started-guide/)"
{{ site.data.reusables.actions.enterprise-setup-prereq }} {% data reusables.actions.enterprise-setup-prereq %}
### Starting with the Node.js workflow template ### Starting with the Node.js workflow template
{{ site.data.variables.product.prodname_dotcom }} provides a Node.js workflow template that will work for most Node.js projects. This guide includes npm and Yarn examples that you can use to customize the template. For more information, see the [Node.js workflow template](https://github.com/actions/starter-workflows/blob/master/ci/node.js.yml). {% data variables.product.prodname_dotcom %} provides a Node.js workflow template that will work for most Node.js projects. This guide includes npm and Yarn examples that you can use to customize the template. For more information, see the [Node.js workflow template](https://github.com/actions/starter-workflows/blob/master/ci/node.js.yml).
To get started quickly, add the template to the `.github/workflows` directory of your repository. To get started quickly, add the template to the `.github/workflows` directory of your repository.
@@ -61,17 +61,17 @@ jobs:
``` ```
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.example-github-runner }} {% data reusables.github-actions.example-github-runner %}
### Specifying the Node.js version ### Specifying the Node.js version
The easiest way to specify a Node.js version is by using the `setup-node` action provided by {{ site.data.variables.product.prodname_dotcom }}. For more information see, [`setup-node`](https://github.com/actions/setup-node/). The easiest way to specify a Node.js version is by using the `setup-node` action provided by {% data variables.product.prodname_dotcom %}. For more information see, [`setup-node`](https://github.com/actions/setup-node/).
The `setup-node` action takes a Node.js version as an input and configures that version on the runner. The `setup-node` action finds a specific version of Node.js from the tools cache on each runner and adds the necessary binaries to `PATH`, which persists for the rest of the job. Using the `setup-node` action is the recommended way of using Node.js with {{ site.data.variables.product.prodname_actions }} because it ensures consistent behavior across different runners and different versions of Node.js. If you are using a self-hosted runner, you must install Node.js and add it to `PATH`. The `setup-node` action takes a Node.js version as an input and configures that version on the runner. The `setup-node` action finds a specific version of Node.js from the tools cache on each runner and adds the necessary binaries to `PATH`, which persists for the rest of the job. Using the `setup-node` action is the recommended way of using Node.js with {% data variables.product.prodname_actions %} because it ensures consistent behavior across different runners and different versions of Node.js. If you are using a self-hosted runner, you must install Node.js and add it to `PATH`.
The template includes a matrix strategy that builds and tests your code with three Node.js versions: 8.x, 10.x, and 12.x. The 'x' is a wildcard character that matches the latest minor and patch release available for a version. Each version of Node.js specified in the `node-version` array creates a job that runs the same steps. The template includes a matrix strategy that builds and tests your code with three Node.js versions: 8.x, 10.x, and 12.x. The 'x' is a wildcard character that matches the latest minor and patch release available for a version. Each version of Node.js specified in the `node-version` array creates a job that runs the same steps.
Each job can access the value defined in the matrix `node-version` array using the `matrix` context. The `setup-node` action uses the context as the `node-version` input. The `setup-node` action configures each job with a different Node.js version before building and testing code. For more information about matrix strategies and contexts, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix)" and "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." Each job can access the value defined in the matrix `node-version` array using the `matrix` context. The `setup-node` action uses the context as the `node-version` input. The `setup-node` action configures each job with a different Node.js version before building and testing code. For more information about matrix strategies and contexts, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix)" and "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
{% raw %} {% raw %}
```yaml ```yaml
@@ -123,11 +123,11 @@ jobs:
``` ```
{% endraw %} {% endraw %}
If you don't specify a Node.js version, {{ site.data.variables.product.prodname_dotcom }} uses the environment's default Node.js version. For more information, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". If you don't specify a Node.js version, {% data variables.product.prodname_dotcom %} uses the environment's default Node.js version. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
### Installing dependencies ### Installing dependencies
{{ site.data.variables.product.prodname_dotcom }}-hosted runners have npm and Yarn dependency managers installed. You can use npm and Yarn to install dependencies in your workflow before building and testing your code. The Windows and Linux {{ site.data.variables.product.prodname_dotcom }}-hosted runners also have Grunt, Gulp, and Bower installed. {% data variables.product.prodname_dotcom %}-hosted runners have npm and Yarn dependency managers installed. You can use npm and Yarn to install dependencies in your workflow before building and testing your code. The Windows and Linux {% data variables.product.prodname_dotcom %}-hosted runners also have Grunt, Gulp, and Bower installed.
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
@@ -191,7 +191,7 @@ steps:
#### Example using a private registry and creating the .npmrc file #### Example using a private registry and creating the .npmrc file
{{ site.data.reusables.github-actions.setup-node-intro }} {% data reusables.github-actions.setup-node-intro %}
To authenticate to your private registry, you'll need to store your npm authentication token as a secret in your repository settings. For example, create a secret called `NPM_TOKEN`. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." To authenticate to your private registry, you'll need to store your npm authentication token as a secret in your repository settings. For example, create a secret called `NPM_TOKEN`. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
@@ -273,4 +273,4 @@ You can save artifacts from your build and test steps to view after a job comple
### Publishing to package registries ### Publishing to package registries
You can configure your workflow to publish your Node.js package to a package registry after your CI tests pass. For more information about publishing to npm and {{ site.data.variables.product.prodname_registry }}, see "[Publishing Node.js packages](/actions/automating-your-workflow-with-github-actions/publishing-nodejs-packages)." You can configure your workflow to publish your Node.js package to a package registry after your CI tests pass. For more information about publishing to npm and {% data variables.product.prodname_registry %}, see "[Publishing Node.js packages](/actions/automating-your-workflow-with-github-actions/publishing-nodejs-packages)."

34
content/actions/guides/building-and-testing-python.md
View File

@@ -9,29 +9,29 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you how to build, test, and publish a Python package. This guide shows you how to build, test, and publish a Python package.
{{ site.data.variables.product.prodname_dotcom }}-hosted runners have a tools cache with pre-installed software, which includes Python and PyPy. You don't have to install anything! For a full list of up-to-date software and the pre-installed versions of Python and PyPy, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". {% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Python and PyPy. You don't have to install anything! For a full list of up-to-date software and the pre-installed versions of Python and PyPy, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
### Prerequisites ### Prerequisites
You should be familiar with YAML and the syntax for {{ site.data.variables.product.prodname_actions }}. For more information, see "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)." You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
We recommend that you have a basic understanding of Python, PyPy, and pip. For more information, see: We recommend that you have a basic understanding of Python, PyPy, and pip. For more information, see:
- [Getting started with Python](https://www.python.org/about/gettingstarted/) - [Getting started with Python](https://www.python.org/about/gettingstarted/)
- [PyPy](https://pypy.org/) - [PyPy](https://pypy.org/)
- [Pip package manager](https://pypi.org/project/pip/) - [Pip package manager](https://pypi.org/project/pip/)
{{ site.data.reusables.actions.enterprise-setup-prereq }} {% data reusables.actions.enterprise-setup-prereq %}
### Starting with the Python workflow template ### Starting with the Python workflow template
{{ site.data.variables.product.prodname_dotcom }} provides a Python workflow template that should work for most Python projects. This guide includes examples that you can use to customize the template. For more information, see the [Python workflow template](https://github.com/actions/starter-workflows/blob/master/ci/python-package.yml). {% data variables.product.prodname_dotcom %} provides a Python workflow template that should work for most Python projects. This guide includes examples that you can use to customize the template. For more information, see the [Python workflow template](https://github.com/actions/starter-workflows/blob/master/ci/python-package.yml).
To get started quickly, add the template to the `.github/workflows` directory of your repository. To get started quickly, add the template to the `.github/workflows` directory of your repository.
@@ -74,11 +74,11 @@ jobs:
### Specifying a Python version ### Specifying a Python version
To use a pre-installed version of Python or PyPy on a {{ site.data.variables.product.prodname_dotcom }}-hosted runner, use the `setup-python` action. This action finds a specific version of Python or PyPy from the tools cache on each runner and adds the necessary binaries to `PATH`, which persists for the rest of the job. If a specific version of Python is not pre-installed in the tools cache, the `setup-python` action will download and set up the appropriate version from the [`python-versions`](https://github.com/actions/python-versions) repository. To use a pre-installed version of Python or PyPy on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `setup-python` action. This action finds a specific version of Python or PyPy from the tools cache on each runner and adds the necessary binaries to `PATH`, which persists for the rest of the job. If a specific version of Python is not pre-installed in the tools cache, the `setup-python` action will download and set up the appropriate version from the [`python-versions`](https://github.com/actions/python-versions) repository.
Using the `setup-python` action is the recommended way of using Python with {{ site.data.variables.product.prodname_actions }} because it ensures consistent behavior across different runners and different versions of Python. If you are using a self-hosted runner, you must install Python and add it to `PATH`. For more information, see the [`setup-python` action](https://github.com/marketplace/actions/setup-python). Using the `setup-python` action is the recommended way of using Python with {% data variables.product.prodname_actions %} because it ensures consistent behavior across different runners and different versions of Python. If you are using a self-hosted runner, you must install Python and add it to `PATH`. For more information, see the [`setup-python` action](https://github.com/marketplace/actions/setup-python).
The table below describes the locations for the tools cache in each {{ site.data.variables.product.prodname_dotcom }}-hosted runner. The table below describes the locations for the tools cache in each {% data variables.product.prodname_dotcom %}-hosted runner.
|| Ubuntu | Mac | Windows | || Ubuntu | Mac | Windows |
|------|-------|------|----------| |------|-------|------|----------|
@@ -88,7 +88,7 @@ The table below describes the locations for the tools cache in each {{ site.data
If you are using a self-hosted runner, you can configure the runner to use the `setup-python` action to manage your dependencies. For more information, see [using setup-python with a self-hosted runner](https://github.com/actions/setup-python#using-setup-python-with-a-self-hosted-runner) in the `setup-python` README. If you are using a self-hosted runner, you can configure the runner to use the `setup-python` action to manage your dependencies. For more information, see [using setup-python with a self-hosted runner](https://github.com/actions/setup-python#using-setup-python-with-a-self-hosted-runner) in the `setup-python` README.
{{ site.data.variables.product.prodname_dotcom }} supports semantic versioning syntax. For more information, see "[Using semantic versioning](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept)" and the "[Semantic versioning specification](https://semver.org/)." {% data variables.product.prodname_dotcom %} supports semantic versioning syntax. For more information, see "[Using semantic versioning](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept)" and the "[Semantic versioning specification](https://semver.org/)."
#### Using multiple Python versions #### Using multiple Python versions
@@ -154,7 +154,7 @@ jobs:
If you specify a version of Python that is not available, `setup-python` fails with an error such as: `##[error]Version 3.4 with arch x64 not found`. The error message includes the available versions. If you specify a version of Python that is not available, `setup-python` fails with an error such as: `##[error]Version 3.4 with arch x64 not found`. The error message includes the available versions.
You can also use the `exclude` keyword in your workflow if there is a configuration of Python that you do not wish to run. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategy)." You can also use the `exclude` keyword in your workflow if there is a configuration of Python that you do not wish to run. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategy)."
{% raw %} {% raw %}
```yaml ```yaml
@@ -180,17 +180,17 @@ jobs:
#### Using the default Python version #### Using the default Python version
We recommend using `setup-python` to configure the version of Python used in your workflows because it helps make your dependencies explicit. If you don't use `setup-python`, the default version of Python set in `PATH` is used in any shell when you call `python`. The default version of Python varies between {{ site.data.variables.product.prodname_dotcom }}-hosted runners, which may cause unexpected changes or use an older version than expected. We recommend using `setup-python` to configure the version of Python used in your workflows because it helps make your dependencies explicit. If you don't use `setup-python`, the default version of Python set in `PATH` is used in any shell when you call `python`. The default version of Python varies between {% data variables.product.prodname_dotcom %}-hosted runners, which may cause unexpected changes or use an older version than expected.
| {{ site.data.variables.product.prodname_dotcom }}-hosted runner | Description | | {% data variables.product.prodname_dotcom %}-hosted runner | Description |
|----|----| |----|----|
| Ubuntu | Ubuntu runners have multiple versions of system Python installed under `/usr/bin/python` and `/usr/bin/python3`. The Python versions that come packaged with Ubuntu are in addition to the versions that {{ site.data.variables.product.prodname_dotcom }} installs in the tools cache. | | Ubuntu | Ubuntu runners have multiple versions of system Python installed under `/usr/bin/python` and `/usr/bin/python3`. The Python versions that come packaged with Ubuntu are in addition to the versions that {% data variables.product.prodname_dotcom %} installs in the tools cache. |
| Windows | Excluding the versions of Python that are in the tools cache, Windows does not ship with an equivalent version of system Python. To maintain consistent behavior with other runners and to allow Python to be used out-of-the-box without the `setup-python` action, {{ site.data.variables.product.prodname_dotcom }} adds a few versions from the tools cache to `PATH`.| | Windows | Excluding the versions of Python that are in the tools cache, Windows does not ship with an equivalent version of system Python. To maintain consistent behavior with other runners and to allow Python to be used out-of-the-box without the `setup-python` action, {% data variables.product.prodname_dotcom %} adds a few versions from the tools cache to `PATH`.|
| macOS | The macOS runners have more than one version of system Python installed, in addition to the versions that are part of the tools cache. The system Python versions are located in the `/usr/local/Cellar/python/*` directory. | | macOS | The macOS runners have more than one version of system Python installed, in addition to the versions that are part of the tools cache. The system Python versions are located in the `/usr/local/Cellar/python/*` directory. |
### Installing dependencies ### Installing dependencies
{{ site.data.variables.product.prodname_dotcom }}-hosted runners have the pip package manager installed. You can use pip to install dependencies from the PyPI package registry before building and testing your code. For example, the YAML below installs or upgrades the `pip` package installer and the `setuptools` and `wheel` packages. {% data variables.product.prodname_dotcom %}-hosted runners have the pip package manager installed. You can use pip to install dependencies from the PyPI package registry before building and testing your code. For example, the YAML below installs or upgrades the `pip` package installer and the `setuptools` and `wheel` packages.
You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)." You can also cache dependencies to speed up your workflow. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
@@ -314,7 +314,7 @@ steps:
#### Running tests with tox #### Running tests with tox
With {{ site.data.variables.product.prodname_actions }}, you can run tests with tox and spread the work across multiple jobs. You'll need to invoke tox using the `-e py` option to choose the version of Python in your `PATH`, rather than specifying a specific version. For more information, see [tox](https://tox.readthedocs.io/en/latest/). With {% data variables.product.prodname_actions %}, you can run tests with tox and spread the work across multiple jobs. You'll need to invoke tox using the `-e py` option to choose the version of Python in your `PATH`, rather than specifying a specific version. For more information, see [tox](https://tox.readthedocs.io/en/latest/).
{% raw %} {% raw %}
```yaml ```yaml

14
content/actions/guides/caching-dependencies-to-speed-up-workflows.md
View File

@@ -2,7 +2,7 @@
title: Caching dependencies to speed up workflows title: Caching dependencies to speed up workflows
shortTitle: Caching dependencies shortTitle: Caching dependencies
intro: 'To make your workflows faster and more efficient, you can create and use caches for dependencies and other commonly reused files.' intro: 'To make your workflows faster and more efficient, you can create and use caches for dependencies and other commonly reused files.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows - /github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows
- /actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows - /actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows
@@ -15,9 +15,9 @@ versions:
Workflow runs often reuse the same outputs or downloaded dependencies from one run to another. For example, package and dependency management tools such as Maven, Gradle, npm, and Yarn keep a local cache of downloaded dependencies. Workflow runs often reuse the same outputs or downloaded dependencies from one run to another. For example, package and dependency management tools such as Maven, Gradle, npm, and Yarn keep a local cache of downloaded dependencies.
Jobs on {{ site.data.variables.product.prodname_dotcom }}-hosted runners start in a clean virtual environment and must download dependencies each time, causing increased network utilization, longer runtime, and increased cost. To help speed up the time it takes to recreate these files, {{ site.data.variables.product.prodname_dotcom }} can cache dependencies you frequently use in workflows. Jobs on {% data variables.product.prodname_dotcom %}-hosted runners start in a clean virtual environment and must download dependencies each time, causing increased network utilization, longer runtime, and increased cost. To help speed up the time it takes to recreate these files, {% data variables.product.prodname_dotcom %} can cache dependencies you frequently use in workflows.
To cache dependencies for a job, you'll need to use {{ site.data.variables.product.prodname_dotcom }}'s `cache` action. The action retrieves a cache identified by a unique key. For more information, see [`actions/cache`](https://github.com/actions/cache). To cache dependencies for a job, you'll need to use {% data variables.product.prodname_dotcom %}'s `cache` action. The action retrieves a cache identified by a unique key. For more information, see [`actions/cache`](https://github.com/actions/cache).
{% warning %} {% warning %}
@@ -27,7 +27,7 @@ To cache dependencies for a job, you'll need to use {{ site.data.variables.produ
### Comparing artifacts and dependency caching ### Comparing artifacts and dependency caching
Artifacts and caching are similar because they provide the ability to store files on {{ site.data.variables.product.prodname_dotcom }}, but each feature offers different use cases and cannot be used interchangeably. Artifacts and caching are similar because they provide the ability to store files on {% data variables.product.prodname_dotcom %}, but each feature offers different use cases and cannot be used interchangeably.
- Use caching when you want to reuse files that don't change often between jobs or workflow runs. - Use caching when you want to reuse files that don't change often between jobs or workflow runs.
- Use artifacts when you want to save files produced by a job to view after a workflow has ended. For more information, see "[Persisting workflow data using artifacts](/github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)." - Use artifacts when you want to save files produced by a job to view after a workflow has ended. For more information, see "[Persisting workflow data using artifacts](/github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)."
@@ -118,7 +118,7 @@ To cache files in more than one directory, you will need a step that uses the [`
#### Using contexts to create cache keys #### Using contexts to create cache keys
A cache key can include any of the contexts, functions, literals, and operators supported by {{ site.data.variables.product.prodname_actions }}. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." A cache key can include any of the contexts, functions, literals, and operators supported by {% data variables.product.prodname_actions %}. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
Using expressions to create a `key` allows you to automatically create a new cache when dependencies have changed. For example, you can create a `key` using an expression that calculates the hash of an npm `package-lock.json` file. Using expressions to create a `key` allows you to automatically create a new cache when dependencies have changed. For example, you can create a `key` using an expression that calculates the hash of an npm `package-lock.json` file.
@@ -128,7 +128,7 @@ npm-${{ hashFiles('package-lock.json') }}
``` ```
{% endraw %} {% endraw %}
{{ site.data.variables.product.prodname_dotcom }} evaluates the expression `hash "package-lock.json"` to derive the final `key`. {% data variables.product.prodname_dotcom %} evaluates the expression `hash "package-lock.json"` to derive the final `key`.
``` ```
npm-d5ea0750 npm-d5ea0750
@@ -189,4 +189,4 @@ For example, if a pull request contains a `feature` branch (the current scope) a
### Usage limits and eviction policy ### Usage limits and eviction policy
{{ site.data.variables.product.prodname_dotcom }} will remove any cache entries that have not been accessed in over 7 days. There is no limit on the number of caches you can store, but the total size of all caches in a repository is limited to 5 GB. If you exceed this limit, {{ site.data.variables.product.prodname_dotcom }} will save your cache but will begin evicting caches until the total size is less than 5 GB. {% data variables.product.prodname_dotcom %} will remove any cache entries that have not been accessed in over 7 days. There is no limit on the number of caches you can store, but the total size of all caches in a repository is limited to 5 GB. If you exceed this limit, {% data variables.product.prodname_dotcom %} will save your cache but will begin evicting caches until the total size is less than 5 GB.

40
content/actions/guides/creating-postgresql-service-containers.md
View File

@@ -2,7 +2,7 @@
title: Creating PostgreSQL service containers title: Creating PostgreSQL service containers
shortTitle: PostgreSQL service containers shortTitle: PostgreSQL service containers
intro: You can create a PostgreSQL service container to use in your workflow. This guide shows examples of creating a PostgreSQL service for jobs that run in containers or directly on the runner machine. intro: You can create a PostgreSQL service container to use in your workflow. This guide shows examples of creating a PostgreSQL service for jobs that run in containers or directly on the runner machine.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/creating-postgresql-service-containers - /actions/automating-your-workflow-with-github-actions/creating-postgresql-service-containers
- /actions/configuring-and-managing-workflows/creating-postgresql-service-containers - /actions/configuring-and-managing-workflows/creating-postgresql-service-containers
@@ -11,29 +11,29 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you workflow examples that configure a service container using the Docker Hub `postgres` image. The workflow runs a script to create a PostgreSQL client and populate the client with data. To test that the workflow creates and populates the PostgreSQL client, the script prints the client's data to the console. This guide shows you workflow examples that configure a service container using the Docker Hub `postgres` image. The workflow runs a script to create a PostgreSQL client and populate the client with data. To test that the workflow creates and populates the PostgreSQL client, the script prints the client's data to the console.
{{ site.data.reusables.github-actions.docker-container-os-support }} {% data reusables.github-actions.docker-container-os-support %}
### Prerequisites ### Prerequisites
{{ site.data.reusables.github-actions.service-container-prereqs }} {% data reusables.github-actions.service-container-prereqs %}
You may also find it helpful to have a basic understanding of YAML, the syntax for {{ site.data.variables.product.prodname_actions }}, and PostgreSQL. For more information, see: You may also find it helpful to have a basic understanding of YAML, the syntax for {% data variables.product.prodname_actions %}, and PostgreSQL. For more information, see:
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
- "[PostgreSQL tutorial](https://www.postgresqltutorial.com/)" in the PostgreSQL documentation - "[PostgreSQL tutorial](https://www.postgresqltutorial.com/)" in the PostgreSQL documentation
### Running jobs in containers ### Running jobs in containers
{{ site.data.reusables.github-actions.container-jobs-intro }} {% data reusables.github-actions.container-jobs-intro %}
{{ site.data.reusables.github-actions.copy-workflow-file }} {% data reusables.github-actions.copy-workflow-file %}
{% raw %} {% raw %}
```yaml ```yaml
@@ -89,9 +89,9 @@ jobs:
#### Configuring the runner job #### Configuring the runner job
{{ site.data.reusables.github-actions.service-container-host }} {% data reusables.github-actions.service-container-host %}
{{ site.data.reusables.github-actions.postgres-label-description }} {% data reusables.github-actions.postgres-label-description %}
```yaml ```yaml
jobs: jobs:
@@ -121,7 +121,7 @@ jobs:
#### Configuring the steps #### Configuring the steps
{{ site.data.reusables.github-actions.service-template-steps }} {% data reusables.github-actions.service-template-steps %}
```yaml ```yaml
steps: steps:
@@ -147,7 +147,7 @@ steps:
POSTGRES_PORT: 5432 POSTGRES_PORT: 5432
``` ```
{{ site.data.reusables.github-actions.postgres-environment-variables }} {% data reusables.github-actions.postgres-environment-variables %}
The hostname of the PostgreSQL service is the label you configured in your workflow, in this case, `postgres`. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default PostgreSQL port 5432. The hostname of the PostgreSQL service is the label you configured in your workflow, in this case, `postgres`. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default PostgreSQL port 5432.
@@ -155,7 +155,7 @@ The hostname of the PostgreSQL service is the label you configured in your workf
When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using `localhost` and the Docker host port number. When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using `localhost` and the Docker host port number.
{{ site.data.reusables.github-actions.copy-workflow-file }} {% data reusables.github-actions.copy-workflow-file %}
{% raw %} {% raw %}
```yaml ```yaml
@@ -213,9 +213,9 @@ jobs:
#### Configuring the runner job #### Configuring the runner job
{{ site.data.reusables.github-actions.service-container-host-runner }} {% data reusables.github-actions.service-container-host-runner %}
{{ site.data.reusables.github-actions.postgres-label-description }} {% data reusables.github-actions.postgres-label-description %}
The workflow maps port 5432 on the PostgreSQL service container to the Docker host. For more information about the `ports` keyword, see "[About service containers](/actions/automating-your-workflow-with-github-actions/about-service-containers#mapping-docker-host-and-service-container-ports)." The workflow maps port 5432 on the PostgreSQL service container to the Docker host. For more information about the `ports` keyword, see "[About service containers](/actions/automating-your-workflow-with-github-actions/about-service-containers#mapping-docker-host-and-service-container-ports)."
@@ -248,7 +248,7 @@ jobs:
#### Configuring the steps #### Configuring the steps
{{ site.data.reusables.github-actions.service-template-steps }} {% data reusables.github-actions.service-template-steps %}
```yaml ```yaml
steps: steps:
@@ -274,9 +274,9 @@ steps:
POSTGRES_PORT: 5432 POSTGRES_PORT: 5432
``` ```
{{ site.data.reusables.github-actions.postgres-environment-variables }} {% data reusables.github-actions.postgres-environment-variables %}
{{ site.data.reusables.github-actions.service-container-localhost }} {% data reusables.github-actions.service-container-localhost %}
### Testing the PostgreSQL service container ### Testing the PostgreSQL service container
@@ -284,7 +284,7 @@ You can test your workflow using the following script, which creates a PostgreSQ
You can modify *client.js* to include any PostgreSQL operations needed by your workflow. In this example, the script creates the PostgreSQL client instance, creates a table, adds placeholder data, then retrieves the data. You can modify *client.js* to include any PostgreSQL operations needed by your workflow. In this example, the script creates the PostgreSQL client instance, creates a table, adds placeholder data, then retrieves the data.
{{ site.data.reusables.github-actions.service-container-add-script }} {% data reusables.github-actions.service-container-add-script %}
```javascript ```javascript
const { Client } = require('pg'); const { Client } = require('pg');

40
content/actions/guides/creating-redis-service-containers.md
View File

@@ -2,7 +2,7 @@
title: Creating Redis service containers title: Creating Redis service containers
shortTitle: Redis service containers shortTitle: Redis service containers
intro: You can use service containers to create a Redis client in your workflow. This guide shows examples of creating a Redis service for jobs that run in containers or directly on the runner machine. intro: You can use service containers to create a Redis client in your workflow. This guide shows examples of creating a Redis service for jobs that run in containers or directly on the runner machine.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/creating-redis-service-containers - /actions/automating-your-workflow-with-github-actions/creating-redis-service-containers
- /actions/configuring-and-managing-workflows/creating-redis-service-containers - /actions/configuring-and-managing-workflows/creating-redis-service-containers
@@ -11,29 +11,29 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you workflow examples that configure a service container using the Docker Hub `redis` image. The workflow runs a script to create a Redis client and populate the client with data. To test that the workflow creates and populates the Redis client, the script prints the client's data to the console. This guide shows you workflow examples that configure a service container using the Docker Hub `redis` image. The workflow runs a script to create a Redis client and populate the client with data. To test that the workflow creates and populates the Redis client, the script prints the client's data to the console.
{{ site.data.reusables.github-actions.docker-container-os-support }} {% data reusables.github-actions.docker-container-os-support %}
### Prerequisites ### Prerequisites
{{ site.data.reusables.github-actions.service-container-prereqs }} {% data reusables.github-actions.service-container-prereqs %}
You may also find it helpful to have a basic understanding of YAML, the syntax for {{ site.data.variables.product.prodname_actions }}, and Redis. For more information, see: You may also find it helpful to have a basic understanding of YAML, the syntax for {% data variables.product.prodname_actions %}, and Redis. For more information, see:
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)"
- "[Getting Started with Redis](https://redislabs.com/get-started-with-redis/)" in the Redis documentation - "[Getting Started with Redis](https://redislabs.com/get-started-with-redis/)" in the Redis documentation
### Running jobs in containers ### Running jobs in containers
{{ site.data.reusables.github-actions.container-jobs-intro }} {% data reusables.github-actions.container-jobs-intro %}
{{ site.data.reusables.github-actions.copy-workflow-file }} {% data reusables.github-actions.copy-workflow-file %}
{% raw %} {% raw %}
```yaml ```yaml
@@ -86,9 +86,9 @@ jobs:
#### Configuring the container job #### Configuring the container job
{{ site.data.reusables.github-actions.service-container-host }} {% data reusables.github-actions.service-container-host %}
{{ site.data.reusables.github-actions.redis-label-description }} {% data reusables.github-actions.redis-label-description %}
```yaml ```yaml
jobs: jobs:
@@ -115,7 +115,7 @@ jobs:
#### Configuring the steps #### Configuring the steps
{{ site.data.reusables.github-actions.service-template-steps }} {% data reusables.github-actions.service-template-steps %}
```yaml ```yaml
steps: steps:
@@ -140,7 +140,7 @@ steps:
REDIS_PORT: 6379 REDIS_PORT: 6379
``` ```
{{ site.data.reusables.github-actions.redis-environment-variables }} {% data reusables.github-actions.redis-environment-variables %}
The hostname of the Redis service is the label you configured in your workflow, in this case, `redis`. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default Redis port 6379. The hostname of the Redis service is the label you configured in your workflow, in this case, `redis`. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default Redis port 6379.
@@ -148,7 +148,7 @@ The hostname of the Redis service is the label you configured in your workflow,
When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using `localhost` and the Docker host port number. When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using `localhost` and the Docker host port number.
{{ site.data.reusables.github-actions.copy-workflow-file }} {% data reusables.github-actions.copy-workflow-file %}
{% raw %} {% raw %}
```yaml ```yaml
@@ -203,9 +203,9 @@ jobs:
#### Configuring the runner job #### Configuring the runner job
{{ site.data.reusables.github-actions.service-container-host-runner }} {% data reusables.github-actions.service-container-host-runner %}
{{ site.data.reusables.github-actions.redis-label-description }} {% data reusables.github-actions.redis-label-description %}
The workflow maps port 6379 on the Redis service container to the Docker host. For more information about the `ports` keyword, see "[About service containers](/actions/automating-your-workflow-with-github-actions/about-service-containers#mapping-docker-host-and-service-container-ports)." The workflow maps port 6379 on the Redis service container to the Docker host. For more information about the `ports` keyword, see "[About service containers](/actions/automating-your-workflow-with-github-actions/about-service-containers#mapping-docker-host-and-service-container-ports)."
@@ -235,7 +235,7 @@ jobs:
#### Configuring the steps #### Configuring the steps
{{ site.data.reusables.github-actions.service-template-steps }} {% data reusables.github-actions.service-template-steps %}
```yaml ```yaml
steps: steps:
@@ -261,9 +261,9 @@ steps:
REDIS_PORT: 6379 REDIS_PORT: 6379
``` ```
{{ site.data.reusables.github-actions.redis-environment-variables }} {% data reusables.github-actions.redis-environment-variables %}
{{ site.data.reusables.github-actions.service-container-localhost }} {% data reusables.github-actions.service-container-localhost %}
### Testing the Redis service container ### Testing the Redis service container
@@ -271,7 +271,7 @@ You can test your workflow using the following script, which creates a Redis cli
You can modify *client.js* to include any Redis operations needed by your workflow. In this example, the script creates the Redis client instance, adds placeholder data, then retrieves the data. You can modify *client.js* to include any Redis operations needed by your workflow. In this example, the script creates the Redis client instance, adds placeholder data, then retrieves the data.
{{ site.data.reusables.github-actions.service-container-add-script }} {% data reusables.github-actions.service-container-add-script %}
```javascript ```javascript
const redis = require("redis"); const redis = require("redis");

10
content/actions/guides/index.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Guides title: Guides
shortTitle: Guides shortTitle: Guides
intro: 'These guides for {{ site.data.variables.product.prodname_actions }} include specific use cases and examples to help you configure workflows.' intro: 'These guides for {% data variables.product.prodname_actions %} include specific use cases and examples to help you configure workflows.'
redirect_from: redirect_from:
- /actions/guides/caching-and-storing-workflow-data - /actions/guides/caching-and-storing-workflow-data
- /actions/automating-your-workflow-with-github-actions/using-databases-and-services - /actions/automating-your-workflow-with-github-actions/using-databases-and-services
@@ -19,12 +19,12 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Creating custom continuous integration workflows ### Creating custom continuous integration workflows
You can use {{ site.data.variables.product.prodname_actions }} to create custom continuous integration (CI) workflows that build and test projects written in different programming languages. You can use {% data variables.product.prodname_actions %} to create custom continuous integration (CI) workflows that build and test projects written in different programming languages.
{% link_in_list /about-continuous-integration %} {% link_in_list /about-continuous-integration %}
{% link_in_list /setting-up-continuous-integration-using-workflow-templates %} {% link_in_list /setting-up-continuous-integration-using-workflow-templates %}
@@ -36,7 +36,7 @@ You can use {{ site.data.variables.product.prodname_actions }} to create custom
### Publishing software packages ### Publishing software packages
You can automate publishing software packages as part your continuous delivery (CD) workflow. Packages can be published to any package host and to {{ site.data.reusables.gated-features.packages }}. You can automate publishing software packages as part your continuous delivery (CD) workflow. Packages can be published to any package host and to {% data reusables.gated-features.packages %}.
{% link_in_list /about-packaging-with-github-actions %} {% link_in_list /about-packaging-with-github-actions %}
{% link_in_list /publishing-nodejs-packages %} {% link_in_list /publishing-nodejs-packages %}

44
content/actions/guides/publishing-docker-images.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Publishing Docker images title: Publishing Docker images
intro: 'You can publish Docker images to a registry, such as Docker Hub or {{ site.data.variables.product.prodname_registry }}, as part of your continuous integration (CI) workflow.' intro: 'You can publish Docker images to a registry, such as Docker Hub or {% data variables.product.prodname_registry %}, as part of your continuous integration (CI) workflow.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/language-and-framework-guides/publishing-docker-images - /actions/language-and-framework-guides/publishing-docker-images
versions: versions:
@@ -9,40 +9,40 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you how to create a workflow that performs a Docker build, and then publishes Docker images to Docker Hub or {{ site.data.variables.product.prodname_registry }}. With a single workflow, you can publish images to a single registry or to multiple registries. This guide shows you how to create a workflow that performs a Docker build, and then publishes Docker images to Docker Hub or {% data variables.product.prodname_registry %}. With a single workflow, you can publish images to a single registry or to multiple registries.
{% note %} {% note %}
**Note:** If you want to push to another third-party Docker registry, the example in the "[Publishing images to {{ site.data.variables.product.prodname_registry }}](#publishing-images-to-github-packages)" section can serve as a good template. **Note:** If you want to push to another third-party Docker registry, the example in the "[Publishing images to {% data variables.product.prodname_registry %}](#publishing-images-to-github-packages)" section can serve as a good template.
{% endnote %} {% endnote %}
### Prerequisites ### Prerequisites
We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)." We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
You might also find it helpful to have a basic understanding of the following: You might also find it helpful to have a basic understanding of the following:
- "[Encrypted secrets](/actions/reference/encrypted-secrets)" - "[Encrypted secrets](/actions/reference/encrypted-secrets)"
- "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)" - "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)"
- "[Configuring Docker for use with {{ site.data.variables.product.prodname_registry }}](/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages)" - "[Configuring Docker for use with {% data variables.product.prodname_registry %}](/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages)"
### About image configuration ### About image configuration
This guide assumes that you have a complete definition for a Docker image stored in a {{ site.data.variables.product.prodname_dotcom }} repository. For example, your repository must contain a _Dockerfile_, and any other files needed to perform a Docker build to create an image. This guide assumes that you have a complete definition for a Docker image stored in a {% data variables.product.prodname_dotcom %} repository. For example, your repository must contain a _Dockerfile_, and any other files needed to perform a Docker build to create an image.
In this guide, we will use the Docker `build-push-action` action to build the Docker image and push it to one or more Docker registries. For more information, see [`build-push-action`](https://github.com/marketplace/actions/build-and-push-docker-images). In this guide, we will use the Docker `build-push-action` action to build the Docker image and push it to one or more Docker registries. For more information, see [`build-push-action`](https://github.com/marketplace/actions/build-and-push-docker-images).
{{ site.data.reusables.actions.enterprise-marketplace-actions }} {% data reusables.actions.enterprise-marketplace-actions %}
### Publishing images to Docker Hub ### Publishing images to Docker Hub
{{ site.data.reusables.github-actions.release-trigger-workflow }} {% data reusables.github-actions.release-trigger-workflow %}
In the example workflow below, we use the Docker `build-push-action` action to build the Docker image and, if the build succeeds, push the built image to Docker Hub. In the example workflow below, we use the Docker `build-push-action` action to build the Docker image and, if the build succeeds, push the built image to Docker Hub.
@@ -50,7 +50,7 @@ To push to Docker Hub, you will need to have a Docker Hub account, and have a Do
The `build-push-action` options required for Docker Hub are: The `build-push-action` options required for Docker Hub are:
* `username` and `password`: This is your Docker Hub username and password. We recommend storing your Docker Hub username and password as encrypted secrets in the your {{ site.data.variables.product.prodname_dotcom }} repository so they aren't exposed in your workflow file. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." * `username` and `password`: This is your Docker Hub username and password. We recommend storing your Docker Hub username and password as encrypted secrets in the your {% data variables.product.prodname_dotcom %} repository so they aren't exposed in your workflow file. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
* `repository`: Your Docker Hub repository in the format `DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY`. * `repository`: Your Docker Hub repository in the format `DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY`.
{% raw %} {% raw %}
@@ -76,20 +76,20 @@ jobs:
``` ```
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.docker-tag-with-ref }} {% data reusables.github-actions.docker-tag-with-ref %}
### Publishing images to {{ site.data.variables.product.prodname_registry }} ### Publishing images to {% data variables.product.prodname_registry %}
{{ site.data.reusables.github-actions.release-trigger-workflow }} {% data reusables.github-actions.release-trigger-workflow %}
In the example workflow below, we use the Docker `build-push-action` action to build the Docker image, and if the build succeeds, push the built image to {{ site.data.variables.product.prodname_registry }}. In the example workflow below, we use the Docker `build-push-action` action to build the Docker image, and if the build succeeds, push the built image to {% data variables.product.prodname_registry %}.
The `build-push-action` options required for {{ site.data.variables.product.prodname_registry }} are: The `build-push-action` options required for {% data variables.product.prodname_registry %} are:
* `username`: You can use the {% raw %}`${{ github.actor }}`{% endraw %} context to automatically use the username of the user that triggered the workflow run. For more information, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)." * `username`: You can use the {% raw %}`${{ github.actor }}`{% endraw %} context to automatically use the username of the user that triggered the workflow run. For more information, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)."
* `password`: You can use the automatically-generated `GITHUB_TOKEN` secret for the password. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)." * `password`: You can use the automatically-generated `GITHUB_TOKEN` secret for the password. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)."
* `registry`: Must be set to `docker.pkg.github.com`. * `registry`: Must be set to `docker.pkg.github.com`.
* `repository`: Must be set in the format `OWNER/REPOSITORY/IMAGE_NAME`. For example, for an image named `octo-image` stored on {{ site.data.variables.product.prodname_dotcom }} at `http://github.com/octo-org/octo-repo`, the `repository` option should be set to `octo-org/octo-repo/octo-image`. * `repository`: Must be set in the format `OWNER/REPOSITORY/IMAGE_NAME`. For example, for an image named `octo-image` stored on {% data variables.product.prodname_dotcom %} at `http://github.com/octo-org/octo-repo`, the `repository` option should be set to `octo-org/octo-repo/octo-image`.
{% raw %} {% raw %}
```yaml ```yaml
@@ -116,13 +116,13 @@ jobs:
``` ```
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.docker-tag-with-ref }} {% data reusables.github-actions.docker-tag-with-ref %}
### Publishing images to Docker Hub and {{ site.data.variables.product.prodname_registry }} ### Publishing images to Docker Hub and {% data variables.product.prodname_registry %}
In a single workflow, you can publish your Docker image to multiple registries by using the `build-push-action` action for each registry. In a single workflow, you can publish your Docker image to multiple registries by using the `build-push-action` action for each registry.
The following example workflow uses the `build-push-action` steps from the previous sections ("[Publishing images to Docker Hub](#publishing-images-to-docker-hub)" and "[Publishing images to {{ site.data.variables.product.prodname_registry }}](#publishing-images-to-github-packages)") to create a single workflow that pushes to both registries. The following example workflow uses the `build-push-action` steps from the previous sections ("[Publishing images to Docker Hub](#publishing-images-to-docker-hub)" and "[Publishing images to {% data variables.product.prodname_registry %}](#publishing-images-to-github-packages)") to create a single workflow that pushes to both registries.
{% raw %} {% raw %}
```yaml ```yaml
@@ -155,4 +155,4 @@ jobs:
``` ```
{% endraw %} {% endraw %}
The above workflow checks out the {{ site.data.variables.product.prodname_dotcom }} repository, and uses the `build-push-action` action twice to build and push the Docker image to Docker Hub and {{ site.data.variables.product.prodname_registry }}. For both steps, it sets the `build-push-action` option [`tag_with_ref`](https://github.com/marketplace/actions/build-and-push-docker-images#tag_with_ref) to automatically tag the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a {{ site.data.variables.product.prodname_dotcom }} release, so the reference for both registries will be the Git tag for the release. The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, and uses the `build-push-action` action twice to build and push the Docker image to Docker Hub and {% data variables.product.prodname_registry %}. For both steps, it sets the `build-push-action` option [`tag_with_ref`](https://github.com/marketplace/actions/build-and-push-docker-images#tag_with_ref) to automatically tag the built Docker image with the Git reference of the workflow event. This workflow is triggered on publishing a {% data variables.product.prodname_dotcom %} release, so the reference for both registries will be the Git tag for the release.

42
content/actions/guides/publishing-java-packages-with-gradle.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Publishing Java packages with Gradle title: Publishing Java packages with Gradle
intro: You can use Gradle to publish Java packages to a registry as part of your continuous integration (CI) workflow. intro: You can use Gradle to publish Java packages to a registry as part of your continuous integration (CI) workflow.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/language-and-framework-guides/publishing-java-packages-with-gradle - /actions/language-and-framework-guides/publishing-java-packages-with-gradle
versions: versions:
@@ -9,22 +9,22 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
{{ site.data.reusables.github-actions.publishing-java-packages-intro }} {% data reusables.github-actions.publishing-java-packages-intro %}
### Prerequisites ### Prerequisites
We recommend that you have a basic understanding of workflow files and configuration options. For more information, see "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)." We recommend that you have a basic understanding of workflow files and configuration options. For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
For more information about creating a CI workflow for your Java project with Gradle, see "[Building and testing Java with Gradle](/actions/language-and-framework-guides/building-and-testing-java-with-gradle)." For more information about creating a CI workflow for your Java project with Gradle, see "[Building and testing Java with Gradle](/actions/language-and-framework-guides/building-and-testing-java-with-gradle)."
You may also find it helpful to have a basic understanding of the following: You may also find it helpful to have a basic understanding of the following:
- "[Configuring npm for use with {{ site.data.variables.product.prodname_registry }}](/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages)" - "[Configuring npm for use with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages)"
- "[Environment variables](/actions/reference/environment-variables)" - "[Environment variables](/actions/reference/environment-variables)"
- "[Encrypted secrets](/actions/reference/encrypted-secrets)" - "[Encrypted secrets](/actions/reference/encrypted-secrets)"
- "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)" - "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)"
@@ -88,20 +88,20 @@ jobs:
``` ```
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.gradle-workflow-steps }} {% data reusables.github-actions.gradle-workflow-steps %}
1. Runs the `gradle publish` command to publish to the `OSSRH` Maven repository. The `MAVEN_USERNAME` environment variable will be set with the contents of your `OSSRH_USERNAME` secret, and the `MAVEN_PASSWORD` environment variable will be set with the contents of your `OSSRH_TOKEN` secret. 1. Runs the `gradle publish` command to publish to the `OSSRH` Maven repository. The `MAVEN_USERNAME` environment variable will be set with the contents of your `OSSRH_USERNAME` secret, and the `MAVEN_PASSWORD` environment variable will be set with the contents of your `OSSRH_TOKEN` secret.
For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
### Publishing packages to {{ site.data.variables.product.prodname_registry }} ### Publishing packages to {% data variables.product.prodname_registry %}
Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to {{ site.data.variables.product.prodname_registry }} if CI tests pass. For more information on the `release` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#release)." Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to {% data variables.product.prodname_registry %} if CI tests pass. For more information on the `release` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#release)."
You can define a new Maven repository in the publishing block of your _build.gradle_ that points to {{ site.data.variables.product.prodname_registry }}. In that repository configuration, you can also take advantage of environment variables set in your CI workflow run. You can use the `GITHUB_ACTOR` environment variable as a username, and you can set the `GITHUB_TOKEN` environment variable with your `GITHUB_TOKEN` secret. You can define a new Maven repository in the publishing block of your _build.gradle_ that points to {% data variables.product.prodname_registry %}. In that repository configuration, you can also take advantage of environment variables set in your CI workflow run. You can use the `GITHUB_ACTOR` environment variable as a username, and you can set the `GITHUB_TOKEN` environment variable with your `GITHUB_TOKEN` secret.
The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)." The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)."
For example, if your organization is named "octocat" and your repository is named "hello-world", then the {{ site.data.variables.product.prodname_registry }} configuration in _build.gradle_ would look similar to the below example. For example, if your organization is named "octocat" and your repository is named "hello-world", then the {% data variables.product.prodname_registry %} configuration in _build.gradle_ would look similar to the below example.
{% raw %} {% raw %}
```groovy ```groovy
@@ -145,20 +145,20 @@ jobs:
``` ```
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.gradle-workflow-steps }} {% data reusables.github-actions.gradle-workflow-steps %}
1. Runs the `gradle publish` command to publish to {{ site.data.variables.product.prodname_registry }}. The `GITHUB_TOKEN` environment variable will be set with the content of the `GITHUB_TOKEN` secret. 1. Runs the `gradle publish` command to publish to {% data variables.product.prodname_registry %}. The `GITHUB_TOKEN` environment variable will be set with the content of the `GITHUB_TOKEN` secret.
For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
### Publishing packages to the Maven Central Repository and {{ site.data.variables.product.prodname_registry }} ### Publishing packages to the Maven Central Repository and {% data variables.product.prodname_registry %}
You can publish your packages to both the Maven Central Repository and {{ site.data.variables.product.prodname_registry }} by configuring each in your _build.gradle_ file. You can publish your packages to both the Maven Central Repository and {% data variables.product.prodname_registry %} by configuring each in your _build.gradle_ file.
Ensure your _build.gradle_ file includes a repository for both your {{ site.data.variables.product.prodname_dotcom }} repository and your Maven Central Repository provider. Ensure your _build.gradle_ file includes a repository for both your {% data variables.product.prodname_dotcom %} repository and your Maven Central Repository provider.
For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with the `name` set to `OSSRH`. If you deploy to {{ site.data.variables.product.prodname_registry }}, you might want to specify it in a distribution management repository with the `name` set to `GitHubPackages`. For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with the `name` set to `OSSRH`. If you deploy to {% data variables.product.prodname_registry %}, you might want to specify it in a distribution management repository with the `name` set to `GitHubPackages`.
If your organization is named "octocat" and your repository is named "hello-world", then the {{ site.data.variables.product.prodname_registry }} configuration in _build.gradle_ would look similar to the below example. If your organization is named "octocat" and your repository is named "hello-world", then the {% data variables.product.prodname_registry %} configuration in _build.gradle_ would look similar to the below example.
{% raw %} {% raw %}
```groovy ```groovy
@@ -187,7 +187,7 @@ publishing {
``` ```
{% endraw %} {% endraw %}
With this configuration, you can create a workflow that publishes your package to both the Maven Central Repository and {{ site.data.variables.product.prodname_registry }} by running the `gradle publish` command. With this configuration, you can create a workflow that publishes your package to both the Maven Central Repository and {% data variables.product.prodname_registry %} by running the `gradle publish` command.
{% raw %} {% raw %}
```yaml ```yaml
@@ -213,7 +213,7 @@ jobs:
``` ```
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.gradle-workflow-steps }} {% data reusables.github-actions.gradle-workflow-steps %}
1. Runs the `gradle publish` command to publish to the `OSSRH` Maven repository and {{ site.data.variables.product.prodname_registry }}. The `MAVEN_USERNAME` environment variable will be set with the contents of your `OSSRH_USERNAME` secret, and the `MAVEN_PASSWORD` environment variable will be set with the contents of your `OSSRH_TOKEN` secret. The `GITHUB_TOKEN` environment variable will be set with the content of the `GITHUB_TOKEN` secret. 1. Runs the `gradle publish` command to publish to the `OSSRH` Maven repository and {% data variables.product.prodname_registry %}. The `MAVEN_USERNAME` environment variable will be set with the contents of your `OSSRH_USERNAME` secret, and the `MAVEN_PASSWORD` environment variable will be set with the contents of your `OSSRH_TOKEN` secret. The `GITHUB_TOKEN` environment variable will be set with the content of the `GITHUB_TOKEN` secret.
For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."

42
content/actions/guides/publishing-java-packages-with-maven.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Publishing Java packages with Maven title: Publishing Java packages with Maven
intro: You can use Maven to publish Java packages to a registry as part of your continuous integration (CI) workflow. intro: You can use Maven to publish Java packages to a registry as part of your continuous integration (CI) workflow.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/language-and-framework-guides/publishing-java-packages-with-maven - /actions/language-and-framework-guides/publishing-java-packages-with-maven
versions: versions:
@@ -9,22 +9,22 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
{{ site.data.reusables.github-actions.publishing-java-packages-intro }} {% data reusables.github-actions.publishing-java-packages-intro %}
### Prerequisites ### Prerequisites
We recommend that you have a basic understanding of workflow files and configuration options. For more information, see "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)." We recommend that you have a basic understanding of workflow files and configuration options. For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
For more information about creating a CI workflow for your Java project with Maven, see "[Building and testing Java with Maven](/actions/language-and-framework-guides/building-and-testing-java-with-maven)." For more information about creating a CI workflow for your Java project with Maven, see "[Building and testing Java with Maven](/actions/language-and-framework-guides/building-and-testing-java-with-maven)."
You may also find it helpful to have a basic understanding of the following: You may also find it helpful to have a basic understanding of the following:
- "[Configuring npm for use with {{ site.data.variables.product.prodname_registry }}](/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages)" - "[Configuring npm for use with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages)"
- "[Environment variables](/actions/reference/environment-variables)" - "[Environment variables](/actions/reference/environment-variables)"
- "[Encrypted secrets](/actions/reference/encrypted-secrets)" - "[Encrypted secrets](/actions/reference/encrypted-secrets)"
- "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)" - "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)"
@@ -41,7 +41,7 @@ You can use the `setup-java` action to configure the deployment repository as we
Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to the Maven Central Repository if CI tests pass. For more information on the `release` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#release)." Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to the Maven Central Repository if CI tests pass. For more information on the `release` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#release)."
In this workflow, you can use the `setup-java` action. This action installs the given version of the JDK into the `PATH`, but it also configures a Maven _settings.xml_ for publishing packages. By default, the settings file will be configured for {{ site.data.variables.product.prodname_registry }}, but it can be configured to deploy to another package registry, such as the Maven Central Repository. If you already have a distribution management repository configured in _pom.xml_, then you can specify that `id` during the `setup-java` action invocation. In this workflow, you can use the `setup-java` action. This action installs the given version of the JDK into the `PATH`, but it also configures a Maven _settings.xml_ for publishing packages. By default, the settings file will be configured for {% data variables.product.prodname_registry %}, but it can be configured to deploy to another package registry, such as the Maven Central Repository. If you already have a distribution management repository configured in _pom.xml_, then you can specify that `id` during the `setup-java` action invocation.
For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, your _pom.xml_ could specify a distribution management repository with the `id` of `ossrh`. For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, your _pom.xml_ could specify a distribution management repository with the `id` of `ossrh`.
@@ -95,21 +95,21 @@ This workflow performs the following steps:
1. Checks out a copy of project's repository. 1. Checks out a copy of project's repository.
1. Sets up the Java JDK, and also configures the Maven _settings.xml_ file to add authentication for the `ossrh` repository using the `MAVEN_USERNAME` and `MAVEN_PASSWORD` environment variables. 1. Sets up the Java JDK, and also configures the Maven _settings.xml_ file to add authentication for the `ossrh` repository using the `MAVEN_USERNAME` and `MAVEN_PASSWORD` environment variables.
1. {{ site.data.reusables.github-actions.publish-to-maven-workflow-step }} 1. {% data reusables.github-actions.publish-to-maven-workflow-step %}
For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
### Publishing packages to {{ site.data.variables.product.prodname_registry }} ### Publishing packages to {% data variables.product.prodname_registry %}
Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to {{ site.data.variables.product.prodname_registry }} if CI tests pass. For more information on the `release` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#release)." Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to {% data variables.product.prodname_registry %} if CI tests pass. For more information on the `release` event, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#release)."
In this workflow, you can use the `setup-java` action. This action installs the given version of the JDK into the `PATH`, and also sets up a Maven _settings.xml_ for publishing the package to {{ site.data.variables.product.prodname_registry }}. The generated _settings.xml_ defines authentication for a server with an `id` of `github`, using the `GITHUB_ACTOR` environment variable as the username and the `GITHUB_TOKEN` environment variable as the password. In this workflow, you can use the `setup-java` action. This action installs the given version of the JDK into the `PATH`, and also sets up a Maven _settings.xml_ for publishing the package to {% data variables.product.prodname_registry %}. The generated _settings.xml_ defines authentication for a server with an `id` of `github`, using the `GITHUB_ACTOR` environment variable as the username and the `GITHUB_TOKEN` environment variable as the password.
The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)." The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)."
For a Maven-based project, you can make use of these settings by creating a distribution repository in your _pom.xml_ file with an `id` of `github` that points to your {{ site.data.variables.product.prodname_registry }} endpoint. For a Maven-based project, you can make use of these settings by creating a distribution repository in your _pom.xml_ file with an `id` of `github` that points to your {% data variables.product.prodname_registry %} endpoint.
For example, if your organization is named "octocat" and your repository is named "hello-world", then the {{ site.data.variables.product.prodname_registry }} configuration in _pom.xml_ would look similar to the below example. For example, if your organization is named "octocat" and your repository is named "hello-world", then the {% data variables.product.prodname_registry %} configuration in _pom.xml_ would look similar to the below example.
{% raw %} {% raw %}
```xml ```xml
@@ -126,7 +126,7 @@ For example, if your organization is named "octocat" and your repository is name
``` ```
{% endraw %} {% endraw %}
With this configuration, you can create a workflow that publishes your package to {{ site.data.variables.product.prodname_registry }} by making use of the automatically generated _settings.xml_. With this configuration, you can create a workflow that publishes your package to {% data variables.product.prodname_registry %} by making use of the automatically generated _settings.xml_.
{% raw %} {% raw %}
```yaml ```yaml
@@ -153,15 +153,15 @@ This workflow performs the following steps:
1. Checks out a copy of project's repository. 1. Checks out a copy of project's repository.
1. Sets up the Java JDK, and also automatically configures the Maven _settings.xml_ file to add authentication for the `github` Maven repository to use the `GITHUB_TOKEN` environment variable. 1. Sets up the Java JDK, and also automatically configures the Maven _settings.xml_ file to add authentication for the `github` Maven repository to use the `GITHUB_TOKEN` environment variable.
1. {{ site.data.reusables.github-actions.publish-to-packages-workflow-step }} 1. {% data reusables.github-actions.publish-to-packages-workflow-step %}
For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
### Publishing packages to the Maven Central Repository and {{ site.data.variables.product.prodname_registry }} ### Publishing packages to the Maven Central Repository and {% data variables.product.prodname_registry %}
You can publish your packages to both the Maven Central Repository and {{ site.data.variables.product.prodname_registry }} by using the `setup-java` action for each registry. You can publish your packages to both the Maven Central Repository and {% data variables.product.prodname_registry %} by using the `setup-java` action for each registry.
Ensure your _pom.xml_ file includes a distribution management repository for both your {{ site.data.variables.product.prodname_dotcom }} repository and your Maven Central Repository provider. For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with the `id` set to `ossrh`, and you might want to specify {{ site.data.variables.product.prodname_registry }} in a distribution management repository with the `id` set to `github`. Ensure your _pom.xml_ file includes a distribution management repository for both your {% data variables.product.prodname_dotcom %} repository and your Maven Central Repository provider. For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with the `id` set to `ossrh`, and you might want to specify {% data variables.product.prodname_registry %} in a distribution management repository with the `id` set to `github`.
{% raw %} {% raw %}
```yaml ```yaml
@@ -203,8 +203,8 @@ This workflow performs the following steps:
1. Checks out a copy of project's repository. 1. Checks out a copy of project's repository.
1. Calls `setup-java` the first time. This configures the Maven _settings.xml_ file for the `ossrh` repository, and sets the authentication options to environment variables that are defined in the next step. 1. Calls `setup-java` the first time. This configures the Maven _settings.xml_ file for the `ossrh` repository, and sets the authentication options to environment variables that are defined in the next step.
1. {{ site.data.reusables.github-actions.publish-to-maven-workflow-step }} 1. {% data reusables.github-actions.publish-to-maven-workflow-step %}
1. Calls `setup-java` the second time. This automatically configures the Maven _settings.xml_ file for {{ site.data.variables.product.prodname_registry }}. 1. Calls `setup-java` the second time. This automatically configures the Maven _settings.xml_ file for {% data variables.product.prodname_registry %}.
1. {{ site.data.reusables.github-actions.publish-to-packages-workflow-step }} 1. {% data reusables.github-actions.publish-to-packages-workflow-step %}
For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information about using secrets in your workflow, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."

38
content/actions/guides/publishing-nodejs-packages.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Publishing Node.js packages title: Publishing Node.js packages
intro: You can publish Node.js packages to a registry as part of your continuous integration (CI) workflow. intro: You can publish Node.js packages to a registry as part of your continuous integration (CI) workflow.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/publishing-nodejs-packages - /actions/automating-your-workflow-with-github-actions/publishing-nodejs-packages
- /actions/language-and-framework-guides/publishing-nodejs-packages - /actions/language-and-framework-guides/publishing-nodejs-packages
@@ -10,22 +10,22 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
This guide shows you how to create a workflow that publishes Node.js packages to the {{ site.data.variables.product.prodname_registry }} and npm registries after continuous integration (CI) tests pass. With a single workflow, you can publish packages to a single registry or multiple registries. This guide shows you how to create a workflow that publishes Node.js packages to the {% data variables.product.prodname_registry %} and npm registries after continuous integration (CI) tests pass. With a single workflow, you can publish packages to a single registry or multiple registries.
### Prerequisites ### Prerequisites
We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)." We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
For more information about creating a CI workflow for your Node.js project, see "[Using Node.js with {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/using-nodejs-with-github-actions)." For more information about creating a CI workflow for your Node.js project, see "[Using Node.js with {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/using-nodejs-with-github-actions)."
You may also find it helpful to have a basic understanding of the following: You may also find it helpful to have a basic understanding of the following:
- "[Configuring npm for use with {{ site.data.variables.product.prodname_registry }}](/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages)" - "[Configuring npm for use with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages)"
- "[Environment variables](/actions/reference/environment-variables)" - "[Environment variables](/actions/reference/environment-variables)"
- "[Encrypted secrets](/actions/reference/encrypted-secrets)" - "[Encrypted secrets](/actions/reference/encrypted-secrets)"
- "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)" - "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow)"
@@ -34,7 +34,7 @@ You may also find it helpful to have a basic understanding of the following:
The `name` and `version` fields in the *package.json* file create a unique identifier that registries use to link your package to a registry. You can add a summary for the package listing page by including a `description` field in the *package.json* file. For more information, see "[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file)" and "[Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules)" in the npm documentation. The `name` and `version` fields in the *package.json* file create a unique identifier that registries use to link your package to a registry. You can add a summary for the package listing page by including a `description` field in the *package.json* file. For more information, see "[Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file)" and "[Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules)" in the npm documentation.
When a local *.npmrc* file exists and has a `registry` value specified, the `npm publish` command uses the registry configured in the *.npmrc* file. {{ site.data.reusables.github-actions.setup-node-intro }} When a local *.npmrc* file exists and has a `registry` value specified, the `npm publish` command uses the registry configured in the *.npmrc* file. {% data reusables.github-actions.setup-node-intro %}
You can specify the Node.js version installed on the runner using the `setup-node` action. You can specify the Node.js version installed on the runner using the `setup-node` action.
@@ -83,13 +83,13 @@ registry=https://registry.npmjs.org/
always-auth=true always-auth=true
``` ```
### Publishing packages to {{ site.data.variables.product.prodname_registry }} ### Publishing packages to {% data variables.product.prodname_registry %}
Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs anytime the `release` event with type `created` occurs. The workflow publishes the package to {{ site.data.variables.product.prodname_registry }} if CI tests pass. Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs anytime the `release` event with type `created` occurs. The workflow publishes the package to {% data variables.product.prodname_registry %} if CI tests pass.
By default, {{ site.data.variables.product.prodname_registry }} publishes a package in the {{ site.data.variables.product.prodname_dotcom }} repository you specify in the `name` field of the *package.json* file. For example, you would publish a package named `@my-org/test` to the `my-org/test` {{ site.data.variables.product.prodname_dotcom }} repository. For more information, see [`npm-scope`](https://docs.npmjs.com/misc/scope) in the npm documentation. By default, {% data variables.product.prodname_registry %} publishes a package in the {% data variables.product.prodname_dotcom %} repository you specify in the `name` field of the *package.json* file. For example, you would publish a package named `@my-org/test` to the `my-org/test` {% data variables.product.prodname_dotcom %} repository. For more information, see [`npm-scope`](https://docs.npmjs.com/misc/scope) in the npm documentation.
To perform authenticated operations against the {{ site.data.variables.product.prodname_registry }} registry in your workflow, you can use the `GITHUB_TOKEN`. The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." To perform authenticated operations against the {% data variables.product.prodname_registry %} registry in your workflow, you can use the `GITHUB_TOKEN`. The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
This example stores the `GITHUB_TOKEN` secret in the `NODE_AUTH_TOKEN` environment variable. When the `setup-node` action creates an *.npmrc* file, it references the token from the `NODE_AUTH_TOKEN` environment variable. This example stores the `GITHUB_TOKEN` secret in the `NODE_AUTH_TOKEN` environment variable. When the `setup-node` action creates an *.npmrc* file, it references the token from the `NODE_AUTH_TOKEN` environment variable.
@@ -155,25 +155,25 @@ jobs:
``` ```
{% endraw %} {% endraw %}
### Publishing packages to npm and {{ site.data.variables.product.prodname_registry }} ### Publishing packages to npm and {% data variables.product.prodname_registry %}
{% note %} {% note %}
**Note:** If you need to publish to registries that have different scope prefixes, you'll need to modify the *package.json* file on the runner to change the scope prefix. For example, if you publish a package to the `@mona` scope for npm and `@octocat` scope for {{ site.data.variables.product.prodname_registry }}, you can replace the `@mona` scope with `@octocat` in the *package.json* file on the runner after publishing to npm and before publishing to {{ site.data.variables.product.prodname_registry }}. **Note:** If you need to publish to registries that have different scope prefixes, you'll need to modify the *package.json* file on the runner to change the scope prefix. For example, if you publish a package to the `@mona` scope for npm and `@octocat` scope for {% data variables.product.prodname_registry %}, you can replace the `@mona` scope with `@octocat` in the *package.json* file on the runner after publishing to npm and before publishing to {% data variables.product.prodname_registry %}.
{% endnote %} {% endnote %}
You can publish your packages to both the npm registry and {{ site.data.variables.product.prodname_registry }} by using the `setup-node` action for each registry. You can publish your packages to both the npm registry and {% data variables.product.prodname_registry %} by using the `setup-node` action for each registry.
If you publish a package to both registries, you'll need to ensure that your scope prefix on npm matches your {{ site.data.variables.product.prodname_dotcom }} user or organization name. To publish packages to a public registry with a scope prefix, you can use the command `npm publish --access public`. For more information, see [`npm-scope`](https://docs.npmjs.com/misc/scope) and "[Creating and publishing scoped public packages](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages)" in the npm documentation. If you publish a package to both registries, you'll need to ensure that your scope prefix on npm matches your {% data variables.product.prodname_dotcom %} user or organization name. To publish packages to a public registry with a scope prefix, you can use the command `npm publish --access public`. For more information, see [`npm-scope`](https://docs.npmjs.com/misc/scope) and "[Creating and publishing scoped public packages](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages)" in the npm documentation.
Ensure your *package.json* file includes the scope of your {{ site.data.variables.product.prodname_dotcom }} repository and npm registry. For example, if you plan to publish a package in the `octocat/npm-hello-world-test` repository to {{ site.data.variables.product.prodname_dotcom }} and https://www.npmjs.com/package/@octocat/npm-hello-world-test, the name in your *package.json* file would be `"name": "@octocat/npm-hello-world-test"`. Ensure your *package.json* file includes the scope of your {% data variables.product.prodname_dotcom %} repository and npm registry. For example, if you plan to publish a package in the `octocat/npm-hello-world-test` repository to {% data variables.product.prodname_dotcom %} and https://www.npmjs.com/package/@octocat/npm-hello-world-test, the name in your *package.json* file would be `"name": "@octocat/npm-hello-world-test"`.
To perform authenticated operations against the {{ site.data.variables.product.prodname_registry }} registry in your workflow, you can use the `GITHUB_TOKEN`. The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." To perform authenticated operations against the {% data variables.product.prodname_registry %} registry in your workflow, you can use the `GITHUB_TOKEN`. The `GITHUB_TOKEN` exists in your repository by default and has read and write permissions for packages in the repository where the workflow runs. For more information, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."
When you use the `scope` input to the `setup-node` action, the action creates an *.npmrc* file that includes the scope prefix. By default, the `setup-node` action sets the scope in the *.npmrc* file to the user or organization that owns the workflow file. When you use the `scope` input to the `setup-node` action, the action creates an *.npmrc* file that includes the scope prefix. By default, the `setup-node` action sets the scope in the *.npmrc* file to the user or organization that owns the workflow file.
This workflow calls the `setup-node` action two times. Each time the `setup-node` action runs, it overwrites the *.npmrc* file. The *.npmrc* file references the token that allows you to perform authenticated operations against the package registry from the `NODE_AUTH_TOKEN` environment variable. The workflow sets the `NODE_AUTH_TOKEN` environment variable each time the `npm publish` command is run, first with a token to publish to npm (`NPM_TOKEN`) and then with a token to publish to {{ site.data.variables.product.prodname_registry }} (`GITHUB_TOKEN`). This workflow calls the `setup-node` action two times. Each time the `setup-node` action runs, it overwrites the *.npmrc* file. The *.npmrc* file references the token that allows you to perform authenticated operations against the package registry from the `NODE_AUTH_TOKEN` environment variable. The workflow sets the `NODE_AUTH_TOKEN` environment variable each time the `npm publish` command is run, first with a token to publish to npm (`NPM_TOKEN`) and then with a token to publish to {% data variables.product.prodname_registry %} (`GITHUB_TOKEN`).
{% raw %} {% raw %}
```yaml ```yaml

24
content/actions/guides/setting-up-continuous-integration-using-workflow-templates.md
View File

@@ -2,7 +2,7 @@
title: Setting up continuous integration using workflow templates title: Setting up continuous integration using workflow templates
shortTitle: Setting up CI using templates shortTitle: Setting up CI using templates
intro: You can set up continuous integration for your project using a workflow template that matches the language and tooling you want to use. intro: You can set up continuous integration for your project using a workflow template that matches the language and tooling you want to use.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/setting-up-continuous-integration-using-github-actions - /articles/setting-up-continuous-integration-using-github-actions
- /github/automating-your-workflow-with-github-actions/setting-up-continuous-integration-using-github-actions - /github/automating-your-workflow-with-github-actions/setting-up-continuous-integration-using-github-actions
@@ -13,28 +13,28 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
Anyone with write permission to a repository can set up continuous integration (CI) using {{ site.data.variables.product.prodname_actions }}. Anyone with write permission to a repository can set up continuous integration (CI) using {% data variables.product.prodname_actions %}.
After you set up CI, you can customize the workflow to meet your needs. After you set up CI, you can customize the workflow to meet your needs.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
1. Find the template that matches the language and tooling you want to use, then click **Set up this workflow**. 1. Find the template that matches the language and tooling you want to use, then click **Set up this workflow**.
![Setup workflow button](/assets/images/help/repository/setup-workflow-button.png) ![Setup workflow button](/assets/images/help/repository/setup-workflow-button.png)
5. Click **Start commit**. 5. Click **Start commit**.
![Start commit button](/assets/images/help/repository/start-commit.png) ![Start commit button](/assets/images/help/repository/start-commit.png)
{{ site.data.reusables.files.write_commit_message }} {% data reusables.files.write_commit_message %}
{{ site.data.reusables.files.choose_commit_branch }} {% data reusables.files.choose_commit_branch %}
{{ site.data.reusables.files.propose_new_file }} {% data reusables.files.propose_new_file %}
Once a push is made to your repository, you can follow the status and detailed logs of your continuous integration workflow run on {{ site.data.variables.product.prodname_dotcom }} and receive customized notifications. For more information, see "[Configuring notifications](/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#github-actions-notification-options)" and "[Managing a workflow run](/articles/managing-a-workflow-run)." Once a push is made to your repository, you can follow the status and detailed logs of your continuous integration workflow run on {% data variables.product.prodname_dotcom %} and receive customized notifications. For more information, see "[Configuring notifications](/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#github-actions-notification-options)" and "[Managing a workflow run](/articles/managing-a-workflow-run)."
{{ site.data.reusables.repositories.actions-workflow-status-badge-into }} {% data reusables.repositories.actions-workflow-status-badge-into %}
For more information, see "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)." For more information, see "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)."
### Further reading ### Further reading

42
content/actions/guides/storing-workflow-data-as-artifacts.md
View File

@@ -2,7 +2,7 @@
title: Storing workflow data as artifacts title: Storing workflow data as artifacts
shortTitle: Storing workflow artifacts shortTitle: Storing workflow artifacts
intro: Artifacts allow you to share data between jobs in a workflow and store data once that workflow has completed. intro: Artifacts allow you to share data between jobs in a workflow and store data once that workflow has completed.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/persisting-workflow-data-using-artifacts - /articles/persisting-workflow-data-using-artifacts
- /github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts - /github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts
@@ -13,12 +13,12 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About workflow artifacts ### About workflow artifacts
Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run. For example, you can use artifacts to save your build and test output after a workflow run has ended. For pushes and pull requests, {{ site.data.variables.product.product_name }} stores artifacts for 90 days. The retention period for a pull request restarts each time someone pushes a new commit to the pull request. Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run. For example, you can use artifacts to save your build and test output after a workflow run has ended. For pushes and pull requests, {% data variables.product.product_name %} stores artifacts for 90 days. The retention period for a pull request restarts each time someone pushes a new commit to the pull request.
These are some of the common artifacts that you can upload: These are some of the common artifacts that you can upload:
@@ -29,28 +29,28 @@ These are some of the common artifacts that you can upload:
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
Storing artifacts uses storage space on {{ site.data.variables.product.product_name }}. {{ site.data.reusables.github-actions.actions-billing }} For more information, see "[Managing billing for {{ site.data.variables.product.prodname_actions }}](/github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions)." Storing artifacts uses storage space on {% data variables.product.product_name %}. {% data reusables.github-actions.actions-billing %} For more information, see "[Managing billing for {% data variables.product.prodname_actions %}](/github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions)."
{% else %} {% else %}
Artifacts consume storage space on the external blob storage that is configured for {{ site.data.variables.product.prodname_actions }} on {{ site.data.variables.product.product_location }}. Artifacts consume storage space on the external blob storage that is configured for {% data variables.product.prodname_actions %} on {% data variables.product.product_location %}.
{% endif %} {% endif %}
Artifacts are uploaded during a workflow run, and you can view an artifact's name and size in the UI. When an artifact is downloaded using the {{ site.data.variables.product.product_name }} UI, all files that were individually uploaded as part of the artifact get zipped together into a single file. This means that billing is calculated based on the size of the uploaded artifact and not the size of the zip file. Artifacts are uploaded during a workflow run, and you can view an artifact's name and size in the UI. When an artifact is downloaded using the {% data variables.product.product_name %} UI, all files that were individually uploaded as part of the artifact get zipped together into a single file. This means that billing is calculated based on the size of the uploaded artifact and not the size of the zip file.
{{ site.data.variables.product.product_name }} provides two actions that you can use to upload and download build artifacts. For more information, see the {% if currentVersion == "free-pro-team@latest" %}[actions/upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `actions/upload-artifact` and `download-artifact` actions on {{ site.data.variables.product.product_location }}{% endif %}. {% data variables.product.product_name %} provides two actions that you can use to upload and download build artifacts. For more information, see the {% if currentVersion == "free-pro-team@latest" %}[actions/upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `actions/upload-artifact` and `download-artifact` actions on {% data variables.product.product_location %}{% endif %}.
To share data between jobs: To share data between jobs:
* **Uploading files**: Give the uploaded file a name and upload the data before the job ends. * **Uploading files**: Give the uploaded file a name and upload the data before the job ends.
* **Downloading files**: You can only download artifacts that were uploaded during the same workflow run. When you download a file, you can reference it by name. * **Downloading files**: You can only download artifacts that were uploaded during the same workflow run. When you download a file, you can reference it by name.
The steps of a job share the same environment on the runner machine, but run in their own individual processes. To pass data between steps in a job, you can use inputs and outputs. For more information about inputs and outputs, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/articles/metadata-syntax-for-github-actions)." The steps of a job share the same environment on the runner machine, but run in their own individual processes. To pass data between steps in a job, you can use inputs and outputs. For more information about inputs and outputs, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/articles/metadata-syntax-for-github-actions)."
### Passing data between jobs in a workflow ### Passing data between jobs in a workflow
You can use the `upload-artifact` and `download-artifact` actions to share data between jobs in a workflow. This example workflow illustrates how to pass data between jobs in the same workflow. For more information, see the {% if currentVersion == "free-pro-team@latest" %}[actions/upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `actions/upload-artifact` and `download-artifact` actions on {{ site.data.variables.product.product_location }}{% endif %}. You can use the `upload-artifact` and `download-artifact` actions to share data between jobs in a workflow. This example workflow illustrates how to pass data between jobs in the same workflow. For more information, see the {% if currentVersion == "free-pro-team@latest" %}[actions/upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `actions/upload-artifact` and `download-artifact` actions on {% data variables.product.product_location %}{% endif %}.
Jobs that are dependent on a previous job's artifacts must wait for the dependent job to complete successfully. This workflow uses the `needs` keyword to ensure that `job_1`, `job_2`, and `job_3` run sequentially. For example, `job_2` requires `job_1` using the `needs: job_1` syntax. Jobs that are dependent on a previous job's artifacts must wait for the dependent job to complete successfully. This workflow uses the `needs` keyword to ensure that `job_1`, `job_2`, and `job_3` run sequentially. For example, `job_2` requires `job_1` using the `needs: job_1` syntax.
@@ -127,17 +127,17 @@ jobs:
### Sharing data between workflow runs ### Sharing data between workflow runs
After a workflow ends, you can download a compressed file of the uploaded artifacts on {{ site.data.variables.product.product_name }} by finding the workflow run in the **Actions** tab. You can also use the {{ site.data.variables.product.prodname_dotcom }} REST API to download artifacts. For more information, see "[Artifacts](/v3/actions/artifacts/)." After a workflow ends, you can download a compressed file of the uploaded artifacts on {% data variables.product.product_name %} by finding the workflow run in the **Actions** tab. You can also use the {% data variables.product.prodname_dotcom %} REST API to download artifacts. For more information, see "[Artifacts](/v3/actions/artifacts/)."
If you need to access artifacts from a previous workflow run, you can use the {{ site.data.variables.product.product_name }} REST API to retrieve artifacts. For more information, see "[Get an artifact](/rest/reference/actions#artifacts)." If you need to access artifacts from a previous workflow run, you can use the {% data variables.product.product_name %} REST API to retrieve artifacts. For more information, see "[Get an artifact](/rest/reference/actions#artifacts)."
### Uploading build and test artifacts ### Uploading build and test artifacts
You can create a continuous integration (CI) workflow to build and test your code. For more information about using {{ site.data.variables.product.prodname_actions }} to perform CI, see "[About continuous integration](/articles/about-continuous-integration)." You can create a continuous integration (CI) workflow to build and test your code. For more information about using {% data variables.product.prodname_actions %} to perform CI, see "[About continuous integration](/articles/about-continuous-integration)."
The output of building and testing your code often produces files you can use to debug test failures and production code that you can deploy. You can configure a workflow to build and test the code pushed to your repository and report a success or failure status. You can upload the build and test output to use for deployments, debugging failed tests or crashes, and viewing test suite coverage. The output of building and testing your code often produces files you can use to debug test failures and production code that you can deploy. You can configure a workflow to build and test the code pushed to your repository and report a success or failure status. You can upload the build and test output to use for deployments, debugging failed tests or crashes, and viewing test suite coverage.
You can use the `upload-artifact` action to upload artifacts. When uploading an artifact, you can specify a single file or directory, or multiple files or directories. You can also exclude certain files or directories, and use wildcard patterns. We recommend that you provide a name for an artifact, but if no name is provided then `artifact` will be used as the default name. For more information on syntax, see the {% if currentVersion == "free-pro-team@latest" %}[actions/upload-artifact](https://github.com/actions/upload-artifact) action{% else %} `actions/upload-artifact` action on {{ site.data.variables.product.product_location }}{% endif %}. You can use the `upload-artifact` action to upload artifacts. When uploading an artifact, you can specify a single file or directory, or multiple files or directories. You can also exclude certain files or directories, and use wildcard patterns. We recommend that you provide a name for an artifact, but if no name is provided then `artifact` will be used as the default name. For more information on syntax, see the {% if currentVersion == "free-pro-team@latest" %}[actions/upload-artifact](https://github.com/actions/upload-artifact) action{% else %} `actions/upload-artifact` action on {% data variables.product.product_location %}{% endif %}.
#### Example #### Example
@@ -223,11 +223,11 @@ You can also download all artifacts in a workflow run by not specifying a name.
If you download all a workflow run's artifacts, a directory for each artifact is created using its name. If you download all a workflow run's artifacts, a directory for each artifact is created using its name.
For more information on syntax, see the {% if currentVersion == "free-pro-team@latest" %}[actions/download-artifact](https://github.com/actions/download-artifact) action{% else %} `actions/download-artifact` action on {{ site.data.variables.product.product_location }}{% endif %}. For more information on syntax, see the {% if currentVersion == "free-pro-team@latest" %}[actions/download-artifact](https://github.com/actions/download-artifact) action{% else %} `actions/download-artifact` action on {% data variables.product.product_location %}{% endif %}.
#### Downloading and deleting artifacts after a workflow run is complete #### Downloading and deleting artifacts after a workflow run is complete
Artifacts automatically expire after 90 days, but you can always reclaim used {{ site.data.variables.product.prodname_actions }} storage by deleting artifacts before they expire on {{ site.data.variables.product.product_name }}. Artifacts automatically expire after 90 days, but you can always reclaim used {% data variables.product.prodname_actions %} storage by deleting artifacts before they expire on {% data variables.product.product_name %}.
{% warning %} {% warning %}
@@ -235,10 +235,10 @@ Artifacts automatically expire after 90 days, but you can always reclaim used {{
{% endwarning %} {% endwarning %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. To download artifacts, use the **Artifacts** drop-down menu, and select the artifact you want to download. 1. To download artifacts, use the **Artifacts** drop-down menu, and select the artifact you want to download.
![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png) ![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png)
1. To delete artifacts, use the **Artifacts** drop-down menu, and click {% octicon "trashcan" aria-label="The trashcan icon" %}. 1. To delete artifacts, use the **Artifacts** drop-down menu, and click {% octicon "trashcan" aria-label="The trashcan icon" %}.
@@ -248,6 +248,6 @@ Artifacts automatically expire after 90 days, but you can always reclaim used {{
### Further reading ### Further reading
- "[Managing billing for {{ site.data.variables.product.prodname_actions }}](/github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions)". - "[Managing billing for {% data variables.product.prodname_actions %}](/github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions)".
{% endif %} {% endif %}

50
content/actions/hosting-your-own-runners/about-self-hosted-runners.md
View File

@@ -1,6 +1,6 @@
--- ---
title: About self-hosted runners title: About self-hosted runners
intro: 'You can host your own runners and customize the environment used to run jobs in your {{ site.data.variables.product.prodname_actions }} workflows.' intro: 'You can host your own runners and customize the environment used to run jobs in your {% data variables.product.prodname_actions %} workflows.'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/about-self-hosted-runners - /github/automating-your-workflow-with-github-actions/about-self-hosted-runners
- /actions/automating-your-workflow-with-github-actions/about-self-hosted-runners - /actions/automating-your-workflow-with-github-actions/about-self-hosted-runners
@@ -9,58 +9,58 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About self-hosted runners ### About self-hosted runners
{{ site.data.reusables.github-actions.self-hosted-runner-description }} Self-hosted runners can be physical, virtual, in a container, on-premises, or in a cloud. {% data reusables.github-actions.self-hosted-runner-description %} Self-hosted runners can be physical, virtual, in a container, on-premises, or in a cloud.
You can add self-hosted runners at various levels in the management hierarchy: You can add self-hosted runners at various levels in the management hierarchy:
- Repository-level runners are dedicated to a single repository. - Repository-level runners are dedicated to a single repository.
- Organization-level runners can process jobs for multiple repositories in an organization. - Organization-level runners can process jobs for multiple repositories in an organization.
- Enterprise-level runners can be assigned to multiple organizations in an enterprise account. - Enterprise-level runners can be assigned to multiple organizations in an enterprise account.
Your runner machine connects to {{ site.data.variables.product.product_name }} using the {{ site.data.variables.product.prodname_actions }} self-hosted runner application. {{ site.data.reusables.github-actions.runner-app-open-source }} When a new version is released, the runner application automatically updates itself when a job is assigned to the runner, or within a week of release if the runner hasn't been assigned any jobs. Your runner machine connects to {% data variables.product.product_name %} using the {% data variables.product.prodname_actions %} self-hosted runner application. {% data reusables.github-actions.runner-app-open-source %} When a new version is released, the runner application automatically updates itself when a job is assigned to the runner, or within a week of release if the runner hasn't been assigned any jobs.
{{ site.data.reusables.github-actions.self-hosted-runner-auto-removal }} {% data reusables.github-actions.self-hosted-runner-auto-removal %}
For more information about installing and using self-hosted runners, see "[Adding self-hosted runners](/github/automating-your-workflow-with-github-actions/adding-self-hosted-runners)" and "[Using self-hosted runners in a workflow](/github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)." For more information about installing and using self-hosted runners, see "[Adding self-hosted runners](/github/automating-your-workflow-with-github-actions/adding-self-hosted-runners)" and "[Using self-hosted runners in a workflow](/github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)."
### Differences between {{ site.data.variables.product.prodname_dotcom }}-hosted and self-hosted runners ### Differences between {% data variables.product.prodname_dotcom %}-hosted and self-hosted runners
{{ site.data.variables.product.prodname_dotcom }}-hosted runners offer a quicker, simpler way to run your workflows, while self-hosted runners are a highly configurable way to run workflows in your own custom environment. {% data variables.product.prodname_dotcom %}-hosted runners offer a quicker, simpler way to run your workflows, while self-hosted runners are a highly configurable way to run workflows in your own custom environment.
**{{ site.data.variables.product.prodname_dotcom }}-hosted runners:** **{% data variables.product.prodname_dotcom %}-hosted runners:**
- Receive automatic updates for the operating system, preinstalled packages and tools, and the self-hosted runner application. - Receive automatic updates for the operating system, preinstalled packages and tools, and the self-hosted runner application.
- Are managed and maintained by {{ site.data.variables.product.prodname_dotcom }}. - Are managed and maintained by {% data variables.product.prodname_dotcom %}.
- Provide a clean instance for every job execution. - Provide a clean instance for every job execution.
- Use free minutes on your {{ site.data.variables.product.prodname_dotcom }} plan, with per-minute rates applied after surpassing the free minutes. - Use free minutes on your {% data variables.product.prodname_dotcom %} plan, with per-minute rates applied after surpassing the free minutes.
**Self-hosted runners:** **Self-hosted runners:**
- Receive automatic updates for the self-hosted runner application only. You are responsible updating the operating system and all other software. - Receive automatic updates for the self-hosted runner application only. You are responsible updating the operating system and all other software.
- Can use cloud services or local machines that you already pay for. - Can use cloud services or local machines that you already pay for.
- Are customizable to your hardware, operating system, software, and security requirements. - Are customizable to your hardware, operating system, software, and security requirements.
- Don't need to have a clean instance for every job execution. - Don't need to have a clean instance for every job execution.
- Are free to use with {{ site.data.variables.product.prodname_actions }}, but you are responsible for the cost of maintaining your runner machines. - Are free to use with {% data variables.product.prodname_actions %}, but you are responsible for the cost of maintaining your runner machines.
### Requirements for self-hosted runner machines ### Requirements for self-hosted runner machines
You can use any machine as a self-hosted runner as long at it meets these requirements: You can use any machine as a self-hosted runner as long at it meets these requirements:
* You can install and run the self-hosted runner application on the machine. For more information, see "[Supported operating systems for self-hosted runners](#supported-operating-systems-for-self-hosted-runners)." * You can install and run the self-hosted runner application on the machine. For more information, see "[Supported operating systems for self-hosted runners](#supported-operating-systems-for-self-hosted-runners)."
* The machine can communicate with {{ site.data.variables.product.prodname_actions }}. For more information, see "[Communication between self-hosted runners and {{ site.data.variables.product.prodname_dotcom }}](#communication-between-self-hosted-runners-and-github)." * The machine can communicate with {% data variables.product.prodname_actions %}. For more information, see "[Communication between self-hosted runners and {% data variables.product.prodname_dotcom %}](#communication-between-self-hosted-runners-and-github)."
* The machine has enough hardware resources for the type of workflows you plan to run. The self-hosted runner application itself only requires minimal resources. * The machine has enough hardware resources for the type of workflows you plan to run. The self-hosted runner application itself only requires minimal resources.
* If you want to run workflows that use Docker container actions or service containers, you must use a Linux machine and Docker must be installed. * If you want to run workflows that use Docker container actions or service containers, you must use a Linux machine and Docker must be installed.
### Usage limits ### Usage limits
There are some limits on {{ site.data.variables.product.prodname_actions }} usage when using self-hosted runners. These limits are subject to change. There are some limits on {% data variables.product.prodname_actions %} usage when using self-hosted runners. These limits are subject to change.
{{ site.data.reusables.github-actions.usage-workflow-run-time }} {% data reusables.github-actions.usage-workflow-run-time %}
- **Job queue time** - Each job for self-hosted runners can be queued for a maximum of 24 hours. If a self-hosted runner does not start executing the job within this limit, the job is terminated and fails to complete. - **Job queue time** - Each job for self-hosted runners can be queued for a maximum of 24 hours. If a self-hosted runner does not start executing the job within this limit, the job is terminated and fails to complete.
{{ site.data.reusables.github-actions.usage-api-requests }} {% data reusables.github-actions.usage-api-requests %}
- **Job matrix** - {{ site.data.reusables.github-actions.usage-matrix-limits }} - **Job matrix** - {% data reusables.github-actions.usage-matrix-limits %}
### Supported operating systems for self-hosted runners ### Supported operating systems for self-hosted runners
@@ -95,17 +95,17 @@ The following operating systems are supported for the self-hosted runner applica
### Supported actions on self-hosted runners ### Supported actions on self-hosted runners
Some extra configuration might be required to use actions from {{ site.data.variables.product.prodname_dotcom_the_website }} with {{ site.data.variables.product.prodname_ghe_server }}, or to use the `actions/setup-LANGUAGE` actions with self-hosted runners that do not have internet access. For more information, see "[Managing access to actions from {{ site.data.variables.product.prodname_dotcom_the_website }}](/enterprise/admin/github-actions/managing-access-to-actions-from-githubcom)" and contact your {{ site.data.variables.product.prodname_enterprise }} site administrator. Some extra configuration might be required to use actions from {% data variables.product.prodname_dotcom_the_website %} with {% data variables.product.prodname_ghe_server %}, or to use the `actions/setup-LANGUAGE` actions with self-hosted runners that do not have internet access. For more information, see "[Managing access to actions from {% data variables.product.prodname_dotcom_the_website %}](/enterprise/admin/github-actions/managing-access-to-actions-from-githubcom)" and contact your {% data variables.product.prodname_enterprise %} site administrator.
{% endif %} {% endif %}
### Communication between self-hosted runners and {{ site.data.variables.product.product_name }} ### Communication between self-hosted runners and {% data variables.product.product_name %}
The self-hosted runner polls {{ site.data.variables.product.product_name }} to retrieve application updates and to check if any jobs are queued for processing. The self-hosted runner uses a HTTPS _long poll_ that opens a connection to {{ site.data.variables.product.product_name }} for 50 seconds, and if no response is received, it then times out and creates a new long poll. The application must be running on the machine to accept and run {{ site.data.variables.product.prodname_actions }} jobs. The self-hosted runner polls {% data variables.product.product_name %} to retrieve application updates and to check if any jobs are queued for processing. The self-hosted runner uses a HTTPS _long poll_ that opens a connection to {% data variables.product.product_name %} for 50 seconds, and if no response is received, it then times out and creates a new long poll. The application must be running on the machine to accept and run {% data variables.product.prodname_actions %} jobs.
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
You must ensure that the machine has the appropriate network access to communicate with the {{ site.data.variables.product.prodname_dotcom }} URLs listed below. You must ensure that the machine has the appropriate network access to communicate with the {% data variables.product.prodname_dotcom %} URLs listed below.
``` ```
github.com github.com
@@ -113,11 +113,11 @@ api.github.com
*.actions.githubusercontent.com *.actions.githubusercontent.com
``` ```
If you use an IP address allow list for your {{ site.data.variables.product.prodname_dotcom }} organization or enterprise account, you must add your self-hosted runner's IP address to the allow list. For more information, see "[Managing allowed IP addresses for your organization](/github/setting-up-and-managing-organizations-and-teams/managing-allowed-ip-addresses-for-your-organization#using-github-actions-with-an-ip-allow-list)" or "[Enforcing security settings in your enterprise account](/github/setting-up-and-managing-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account#using-github-actions-with-an-ip-allow-list)". If you use an IP address allow list for your {% data variables.product.prodname_dotcom %} organization or enterprise account, you must add your self-hosted runner's IP address to the allow list. For more information, see "[Managing allowed IP addresses for your organization](/github/setting-up-and-managing-organizations-and-teams/managing-allowed-ip-addresses-for-your-organization#using-github-actions-with-an-ip-allow-list)" or "[Enforcing security settings in your enterprise account](/github/setting-up-and-managing-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account#using-github-actions-with-an-ip-allow-list)".
{% else %} {% else %}
You must ensure that the machine has the appropriate network access to communicate with {{ site.data.variables.product.product_location }}. You must ensure that the machine has the appropriate network access to communicate with {% data variables.product.product_location %}.
{% endif %} {% endif %}
@@ -125,9 +125,9 @@ You can also use self-hosted runners with a proxy server. For more information,
### Self-hosted runner security with public repositories ### Self-hosted runner security with public repositories
{{ site.data.reusables.github-actions.self-hosted-runner-security }} {% data reusables.github-actions.self-hosted-runner-security %}
This is not an issue with {{ site.data.variables.product.prodname_dotcom }}-hosted runners because each {{ site.data.variables.product.prodname_dotcom }}-hosted runner is always a clean isolated virtual machine, and it is destroyed at the end of the job execution. This is not an issue with {% data variables.product.prodname_dotcom %}-hosted runners because each {% data variables.product.prodname_dotcom %}-hosted runner is always a clean isolated virtual machine, and it is destroyed at the end of the job execution.
Untrusted workflows running on your self-hosted runner poses significant security risks for your machine and network environment, especially if your machine persists its environment between jobs. Some of the risks include: Untrusted workflows running on your self-hosted runner poses significant security risks for your machine and network environment, especially if your machine persists its environment between jobs. Some of the risks include:

42
content/actions/hosting-your-own-runners/adding-self-hosted-runners.md
View File

@@ -9,14 +9,14 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
For information on supported operating systems for self-hosted runners, or using self-hosted runners with a proxy server, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners)." For information on supported operating systems for self-hosted runners, or using self-hosted runners with a proxy server, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners)."
{% warning %} {% warning %}
**Warning:** {{ site.data.reusables.github-actions.self-hosted-runner-security }} **Warning:** {% data reusables.github-actions.self-hosted-runner-security %}
For more information, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)." For more information, see "[About self-hosted runners](/github/automating-your-workflow-with-github-actions/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories)."
@@ -26,23 +26,23 @@ For more information, see "[About self-hosted runners](/github/automating-your-w
You can add self-hosted runners to a single repository. To add a self-hosted runner to a user repository, you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository. You can add self-hosted runners to a single repository. To add a self-hosted runner to a user repository, you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.sidebar-settings }} {% data reusables.repositories.sidebar-settings %}
{{ site.data.reusables.repositories.settings-sidebar-actions }} {% data reusables.repositories.settings-sidebar-actions %}
1. Under "Self-hosted runners," click **Add runner**. 1. Under "Self-hosted runners," click **Add runner**.
{{ site.data.reusables.github-actions.self-hosted-runner-configure }} {% data reusables.github-actions.self-hosted-runner-configure %}
{{ site.data.reusables.github-actions.self-hosted-runner-check-installation-success }} {% data reusables.github-actions.self-hosted-runner-check-installation-success %}
### Adding a self-hosted runner to an organization ### Adding a self-hosted runner to an organization
You can add self-hosted runners at the organization level, where they can be used to process jobs for multiple repositories in an organization. To add a self-hosted runner to an organization, you must be an organization owner. You can add self-hosted runners at the organization level, where they can be used to process jobs for multiple repositories in an organization. To add a self-hosted runner to an organization, you must be an organization owner.
{{ site.data.reusables.organizations.navigate-to-org }} {% data reusables.organizations.navigate-to-org %}
{{ site.data.reusables.organizations.org_settings }} {% data reusables.organizations.org_settings %}
{{ site.data.reusables.organizations.settings-sidebar-actions }} {% data reusables.organizations.settings-sidebar-actions %}
1. Under "Self-hosted runners," click **Add new**, then click **New runner**. 1. Under "Self-hosted runners," click **Add new**, then click **New runner**.
{{ site.data.reusables.github-actions.self-hosted-runner-configure }} {% data reusables.github-actions.self-hosted-runner-configure %}
{{ site.data.reusables.github-actions.self-hosted-runner-check-installation-success }} {% data reusables.github-actions.self-hosted-runner-check-installation-success %}
### Adding a self-hosted runner to an enterprise ### Adding a self-hosted runner to an enterprise
@@ -51,18 +51,18 @@ You can add self-hosted runners to an enterprise, where they can be assigned to
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
To add a self-hosted runner to an enterprise account, you must be an enterprise owner. To add a self-hosted runner to an enterprise account, you must be an enterprise owner.
{% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%} {% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%}
To add a self-hosted runner at the enterprise level of {{ site.data.variables.product.product_location }}, you must be a site administrator. To add a self-hosted runner at the enterprise level of {% data variables.product.product_location %}, you must be a site administrator.
{% endif %} {% endif %}
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
{{ site.data.reusables.enterprise-accounts.access-enterprise }} {% data reusables.enterprise-accounts.access-enterprise %}
{% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%} {% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.business }} {% data reusables.enterprise_site_admin_settings.business %}
{% endif %} {% endif %}
{{ site.data.reusables.enterprise-accounts.policies-tab }} {% data reusables.enterprise-accounts.policies-tab %}
{{ site.data.reusables.enterprise-accounts.actions-tab }} {% data reusables.enterprise-accounts.actions-tab %}
1. Click the **Self-hosted runners** tab. 1. Click the **Self-hosted runners** tab.
1. Click **Add new**, then click **New runner**. New runners are assigned to the default group. You can modify the runner's group after you've registered the runner. For more information, see "[Managing access to self-hosted runners](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups#moving-a-self-hosted-runner-to-a-group)." 1. Click **Add new**, then click **New runner**. New runners are assigned to the default group. You can modify the runner's group after you've registered the runner. For more information, see "[Managing access to self-hosted runners](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups#moving-a-self-hosted-runner-to-a-group)."
{{ site.data.reusables.github-actions.self-hosted-runner-configure }} {% data reusables.github-actions.self-hosted-runner-configure %}
{{ site.data.reusables.github-actions.self-hosted-runner-check-installation-success }} {% data reusables.github-actions.self-hosted-runner-check-installation-success %}

8
content/actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service.md
View File

@@ -8,12 +8,12 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{% capture service_first_step %}1. Stop the self-hosted runner application if it is currently running.{% endcapture %} {% capture service_first_step %}1. Stop the self-hosted runner application if it is currently running.{% endcapture %}
{% capture service_non_windows_intro_shell %}On the runner machine, open a shell in the directory where you installed the self-hosted runner application. Use the commands below to install and manage the self-hosted runner service.{% endcapture %} {% capture service_non_windows_intro_shell %}On the runner machine, open a shell in the directory where you installed the self-hosted runner application. Use the commands below to install and manage the self-hosted runner service.{% endcapture %}
{% capture service_nonwindows_intro %}You must add a runner to {{ site.data.variables.product.product_name }} before you can configure the self-hosted runner application as a service. For more information, see "[Adding self-hosted runners](/github/automating-your-workflow-with-github-actions/adding-self-hosted-runners)."{% endcapture %} {% capture service_nonwindows_intro %}You must add a runner to {% data variables.product.product_name %} before you can configure the self-hosted runner application as a service. For more information, see "[Adding self-hosted runners](/github/automating-your-workflow-with-github-actions/adding-self-hosted-runners)."{% endcapture %}
{% capture service_win_name %}actions.runner.*{% endcapture %} {% capture service_win_name %}actions.runner.*{% endcapture %}
@@ -31,7 +31,7 @@ For Linux systems that use `systemd`, you can use the `svc.sh` script distribute
{% note %} {% note %}
**Note:** Configuring the self-hosted runner application as a service on Windows is part of the application configuration process. If you have already configured the self-hosted runner application but did not choose to configure it as a service, you must remove the runner from {{ site.data.variables.product.prodname_dotcom }} and re-configure the application. When you re-configure the application, choose the option to configure the application as a service. **Note:** Configuring the self-hosted runner application as a service on Windows is part of the application configuration process. If you have already configured the self-hosted runner application but did not choose to configure it as a service, you must remove the runner from {% data variables.product.prodname_dotcom %} and re-configure the application. When you re-configure the application, choose the option to configure the application as a service.
For more information, see "[Removing self-hosted runners](/actions/automating-your-workflow-with-github-actions/removing-self-hosted-runners)" and "[Adding self-hosted runners](/actions/automating-your-workflow-with-github-actions/adding-self-hosted-runners)." For more information, see "[Removing self-hosted runners](/actions/automating-your-workflow-with-github-actions/removing-self-hosted-runners)" and "[Adding self-hosted runners](/actions/automating-your-workflow-with-github-actions/adding-self-hosted-runners)."

4
content/actions/hosting-your-own-runners/index.md
View File

@@ -9,8 +9,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{% link_in_list /about-self-hosted-runners %} {% link_in_list /about-self-hosted-runners %}
{% link_in_list /adding-self-hosted-runners %} {% link_in_list /adding-self-hosted-runners %}

22
content/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups.md
View File

@@ -8,8 +8,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About self-hosted runner groups ### About self-hosted runner groups
@@ -35,9 +35,9 @@ Self-hosted runners are automatically assigned to the default group when created
When creating a group, you must choose a policy that defines which repositories have access to the runner group. You can configure a runner group to be accessible to a specific list of repositories, all private repositories, or all repositories in the organization. When creating a group, you must choose a policy that defines which repositories have access to the runner group. You can configure a runner group to be accessible to a specific list of repositories, all private repositories, or all repositories in the organization.
{{ site.data.reusables.organizations.navigate-to-org }} {% data reusables.organizations.navigate-to-org %}
{{ site.data.reusables.organizations.org_settings }} {% data reusables.organizations.org_settings %}
{{ site.data.reusables.organizations.settings-sidebar-actions }} {% data reusables.organizations.settings-sidebar-actions %}
1. In the **Self-hosted runners** section, click **Add new**, and then **New group**. 1. In the **Self-hosted runners** section, click **Add new**, and then **New group**.
![Add runner group](/assets/images/help/settings/actions-org-add-runner-group.png) ![Add runner group](/assets/images/help/settings/actions-org-add-runner-group.png)
@@ -55,13 +55,13 @@ Self-hosted runners are automatically assigned to the default group when created
When creating a group, you must choose a policy that grants access to all organizations in the enterprise or choose specific organizations. When creating a group, you must choose a policy that grants access to all organizations in the enterprise or choose specific organizations.
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
{{ site.data.reusables.enterprise-accounts.access-enterprise }} {% data reusables.enterprise-accounts.access-enterprise %}
{% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%} {% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.business }} {% data reusables.enterprise_site_admin_settings.business %}
{% endif %} {% endif %}
{{ site.data.reusables.enterprise-accounts.policies-tab }} {% data reusables.enterprise-accounts.policies-tab %}
{{ site.data.reusables.enterprise-accounts.actions-tab }} {% data reusables.enterprise-accounts.actions-tab %}
1. Click the **Self-hosted runners** tab. 1. Click the **Self-hosted runners** tab.
1. Click **Add new**, and then **New group**. 1. Click **Add new**, and then **New group**.
@@ -75,7 +75,7 @@ When creating a group, you must choose a policy that grants access to all organi
You can update the access policy of a runner group, or rename a runner group. You can update the access policy of a runner group, or rename a runner group.
{{ site.data.reusables.github-actions.self-hosted-runner-configure-runner-group-access }} {% data reusables.github-actions.self-hosted-runner-configure-runner-group-access %}
### Moving a self-hosted runner to a group ### Moving a self-hosted runner to a group

14
content/actions/hosting-your-own-runners/monitoring-and-troubleshooting-self-hosted-runners.md
View File

@@ -10,24 +10,24 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Checking the status of a self-hosted runner ### Checking the status of a self-hosted runner
{{ site.data.reusables.github-actions.self-hosted-runner-management-permissions-required }} {% data reusables.github-actions.self-hosted-runner-management-permissions-required %}
{{ site.data.reusables.github-actions.self-hosted-runner-navigate-repo-and-org }} {% data reusables.github-actions.self-hosted-runner-navigate-repo-and-org %}
{{ site.data.reusables.organizations.settings-sidebar-actions }} {% data reusables.organizations.settings-sidebar-actions %}
1. Under "Self-hosted runners," you can view a list of registered runners, including the runner's name, labels, and status. 1. Under "Self-hosted runners," you can view a list of registered runners, including the runner's name, labels, and status.
![Runner list](/assets/images/help/settings/actions-runner-list.png) ![Runner list](/assets/images/help/settings/actions-runner-list.png)
The status can be one of the following: The status can be one of the following:
* **Idle**: The runner is connected to {{ site.data.variables.product.product_name }} and is ready to execute jobs. * **Idle**: The runner is connected to {% data variables.product.product_name %} and is ready to execute jobs.
* **Active**: The runner is currently executing a job. * **Active**: The runner is currently executing a job.
* **Offline**: The runner is not connected to {{ site.data.variables.product.product_name }}. This could be because the machine is offline, the self-hosted runner application is not running on the machine, or the self-hosted runner application cannot communicate with {{ site.data.variables.product.product_name }}. * **Offline**: The runner is not connected to {% data variables.product.product_name %}. This could be because the machine is offline, the self-hosted runner application is not running on the machine, or the self-hosted runner application cannot communicate with {% data variables.product.product_name %}.
### Reviewing the self-hosted runner application log files ### Reviewing the self-hosted runner application log files

52
content/actions/hosting-your-own-runners/removing-self-hosted-runners.md
View File

@@ -9,71 +9,71 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Removing a runner from a repository ### Removing a runner from a repository
{% note %} {% note %}
**Note:** {{ site.data.reusables.github-actions.self-hosted-runner-removal-impact }} **Note:** {% data reusables.github-actions.self-hosted-runner-removal-impact %}
{{ site.data.reusables.github-actions.self-hosted-runner-auto-removal }} {% data reusables.github-actions.self-hosted-runner-auto-removal %}
{% endnote %} {% endnote %}
To remove a self-hosted runner from a user repository you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository. We recommend that you also have access to the self-hosted runner machine. To remove a self-hosted runner from a user repository you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository. We recommend that you also have access to the self-hosted runner machine.
{{ site.data.reusables.github-actions.self-hosted-runner-reusing }} {% data reusables.github-actions.self-hosted-runner-reusing %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.sidebar-settings }} {% data reusables.repositories.sidebar-settings %}
{{ site.data.reusables.repositories.settings-sidebar-actions }} {% data reusables.repositories.settings-sidebar-actions %}
{{ site.data.reusables.github-actions.self-hosted-runner-removing-a-runner }} {% data reusables.github-actions.self-hosted-runner-removing-a-runner %}
### Removing a runner from an organization ### Removing a runner from an organization
{% note %} {% note %}
**Note:** {{ site.data.reusables.github-actions.self-hosted-runner-removal-impact }} **Note:** {% data reusables.github-actions.self-hosted-runner-removal-impact %}
{{ site.data.reusables.github-actions.self-hosted-runner-auto-removal }} {% data reusables.github-actions.self-hosted-runner-auto-removal %}
{% endnote %} {% endnote %}
To remove a self-hosted runner from an organization, you must be an organization owner. We recommend that you also have access to the self-hosted runner machine. To remove a self-hosted runner from an organization, you must be an organization owner. We recommend that you also have access to the self-hosted runner machine.
{{ site.data.reusables.github-actions.self-hosted-runner-reusing }} {% data reusables.github-actions.self-hosted-runner-reusing %}
{{ site.data.reusables.organizations.navigate-to-org }} {% data reusables.organizations.navigate-to-org %}
{{ site.data.reusables.organizations.org_settings}} {% data reusables.organizations.org_settings %}
{{ site.data.reusables.repositories.settings-sidebar-actions }} {% data reusables.repositories.settings-sidebar-actions %}
{{ site.data.reusables.github-actions.self-hosted-runner-removing-a-runner }} {% data reusables.github-actions.self-hosted-runner-removing-a-runner %}
### Removing a runner from an enterprise ### Removing a runner from an enterprise
{% note %} {% note %}
**Note:** {{ site.data.reusables.github-actions.self-hosted-runner-removal-impact }} **Note:** {% data reusables.github-actions.self-hosted-runner-removal-impact %}
{{ site.data.reusables.github-actions.self-hosted-runner-auto-removal }} {% data reusables.github-actions.self-hosted-runner-auto-removal %}
{% endnote %} {% endnote %}
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
To remove a self-hosted runner from an enterprise account, you must be an enterprise owner. We recommend that you also have access to the self-hosted runner machine. To remove a self-hosted runner from an enterprise account, you must be an enterprise owner. We recommend that you also have access to the self-hosted runner machine.
{% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%} {% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%}
To remove a self-hosted runner at the enterprise level of {{ site.data.variables.product.product_location }}, you must be a site administrator. We recommend that you also have access to the self-hosted runner machine. To remove a self-hosted runner at the enterprise level of {% data variables.product.product_location %}, you must be a site administrator. We recommend that you also have access to the self-hosted runner machine.
{% endif %} {% endif %}
{{ site.data.reusables.github-actions.self-hosted-runner-reusing }} {% data reusables.github-actions.self-hosted-runner-reusing %}
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
{{ site.data.reusables.enterprise-accounts.access-enterprise }} {% data reusables.enterprise-accounts.access-enterprise %}
{% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%} {% else if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21"%}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.business }} {% data reusables.enterprise_site_admin_settings.business %}
{% endif %} {% endif %}
{{ site.data.reusables.enterprise-accounts.policies-tab }} {% data reusables.enterprise-accounts.policies-tab %}
{{ site.data.reusables.enterprise-accounts.actions-tab }} {% data reusables.enterprise-accounts.actions-tab %}
{{ site.data.reusables.github-actions.self-hosted-runner-removing-a-runner }} {% data reusables.github-actions.self-hosted-runner-removing-a-runner %}

6
content/actions/hosting-your-own-runners/using-a-proxy-server-with-self-hosted-runners.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Using a proxy server with self-hosted runners title: Using a proxy server with self-hosted runners
intro: 'You can configure self-hosted runners to use a proxy server to communicate with {{ site.data.variables.product.product_name }}.' intro: 'You can configure self-hosted runners to use a proxy server to communicate with {% data variables.product.product_name %}.'
redirect_from: redirect_from:
- /actions/automating-your-workflow-with-github-actions/using-a-proxy-server-with-self-hosted-runners - /actions/automating-your-workflow-with-github-actions/using-a-proxy-server-with-self-hosted-runners
versions: versions:
@@ -8,8 +8,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Configuring a proxy server using environment variables ### Configuring a proxy server using environment variables

36
content/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners.md
View File

@@ -6,39 +6,39 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
For information on how to use labels to route jobs to specific types of self-hosted runners, see "[Using self-hosted runners in a workflow](/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow)." For information on how to use labels to route jobs to specific types of self-hosted runners, see "[Using self-hosted runners in a workflow](/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow)."
{{ site.data.reusables.github-actions.self-hosted-runner-management-permissions-required }} {% data reusables.github-actions.self-hosted-runner-management-permissions-required %}
### Creating a custom label ### Creating a custom label
{{ site.data.reusables.github-actions.self-hosted-runner-navigate-to-repo-org-enterprise }} {% data reusables.github-actions.self-hosted-runner-navigate-to-repo-org-enterprise %}
{{ site.data.reusables.github-actions.self-hosted-runner-list }} {% data reusables.github-actions.self-hosted-runner-list %}
{{ site.data.reusables.github-actions.self-hosted-runner-list-group }} {% data reusables.github-actions.self-hosted-runner-list-group %}
{{ site.data.reusables.github-actions.self-hosted-runner-labels-view-assigned-labels }} {% data reusables.github-actions.self-hosted-runner-labels-view-assigned-labels %}
1. In the "Filter labels" field, type the name of your new label, and click **Create new label**. 1. In the "Filter labels" field, type the name of your new label, and click **Create new label**.
![Add runner label](/assets/images/help/settings/actions-add-runner-label.png) ![Add runner label](/assets/images/help/settings/actions-add-runner-label.png)
The custom label is created and assigned to the self-hosted runner. Custom labels can be removed from self-hosted runners, but they currently can't be manually deleted. {{ site.data.reusables.github-actions.actions-unused-labels }} The custom label is created and assigned to the self-hosted runner. Custom labels can be removed from self-hosted runners, but they currently can't be manually deleted. {% data reusables.github-actions.actions-unused-labels %}
### Assigning a label to a self-hosted runner ### Assigning a label to a self-hosted runner
{{ site.data.reusables.github-actions.self-hosted-runner-navigate-to-repo-org-enterprise }} {% data reusables.github-actions.self-hosted-runner-navigate-to-repo-org-enterprise %}
{{ site.data.reusables.github-actions.self-hosted-runner-list }} {% data reusables.github-actions.self-hosted-runner-list %}
{{ site.data.reusables.github-actions.self-hosted-runner-list-group }} {% data reusables.github-actions.self-hosted-runner-list-group %}
{{ site.data.reusables.github-actions.self-hosted-runner-labels-view-assigned-labels }} {% data reusables.github-actions.self-hosted-runner-labels-view-assigned-labels %}
1. Click on a label to assign it to your self-hosted runner. 1. Click on a label to assign it to your self-hosted runner.
### Removing a custom label from a self-hosted runner ### Removing a custom label from a self-hosted runner
{{ site.data.reusables.github-actions.self-hosted-runner-navigate-to-repo-org-enterprise }} {% data reusables.github-actions.self-hosted-runner-navigate-to-repo-org-enterprise %}
{{ site.data.reusables.github-actions.self-hosted-runner-list }} {% data reusables.github-actions.self-hosted-runner-list %}
{{ site.data.reusables.github-actions.self-hosted-runner-list-group }} {% data reusables.github-actions.self-hosted-runner-list-group %}
{{ site.data.reusables.github-actions.self-hosted-runner-labels-view-assigned-labels }} {% data reusables.github-actions.self-hosted-runner-labels-view-assigned-labels %}
1. Click on the assigned label to remove it from your self-hosted runner. {{ site.data.reusables.github-actions.actions-unused-labels }} 1. Click on the assigned label to remove it from your self-hosted runner. {% data reusables.github-actions.actions-unused-labels %}
### Using the configuration script to create and assign labels ### Using the configuration script to create and assign labels
@@ -48,7 +48,7 @@ You can use the configuration script on the self-hosted runner to create and ass
./config.sh --labels gpu ./config.sh --labels gpu
``` ```
The label is created if it does not already exist. You can also use this approach to assign the default labels to runners, such as `x64` or `linux`. When default labels are assigned using the configuration script, {{ site.data.variables.product.prodname_actions }} accepts them as given and does not validate that the runner is actually using that operating system or architecture. The label is created if it does not already exist. You can also use this approach to assign the default labels to runners, such as `x64` or `linux`. When default labels are assigned using the configuration script, {% data variables.product.prodname_actions %} accepts them as given and does not validate that the runner is actually using that operating system or architecture.
You can use comma separation to assign multiple labels. For example: You can use comma separation to assign multiple labels. For example:

14
content/actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow.md
View File

@@ -9,8 +9,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
For information on creating custom and default labels, see "[Using labels with self-hosted runners](/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners)." For information on creating custom and default labels, see "[Using labels with self-hosted runners](/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners)."
@@ -18,13 +18,13 @@ For information on creating custom and default labels, see "[Using labels with s
Labels allow you to send workflow jobs to specific types of self-hosted runners, based on their shared characteristics. For example, if your job requires a particular hardware component or software package, you can assign a custom label to a runner and then configure your job to only execute on runners with that label. Labels allow you to send workflow jobs to specific types of self-hosted runners, based on their shared characteristics. For example, if your job requires a particular hardware component or software package, you can assign a custom label to a runner and then configure your job to only execute on runners with that label.
{{ site.data.reusables.github-actions.self-hosted-runner-labels-runs-on }} {% data reusables.github-actions.self-hosted-runner-labels-runs-on %}
For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-on)." For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-on)."
### Using default labels to route jobs ### Using default labels to route jobs
A self-hosted runner automatically receives certain labels when it is added to {{ site.data.variables.product.prodname_actions }}. These are used to indicate its operating system and hardware platform: A self-hosted runner automatically receives certain labels when it is added to {% data variables.product.prodname_actions %}. These are used to indicate its operating system and hardware platform:
* `self-hosted`: Default label applied to all self-hosted runners. * `self-hosted`: Default label applied to all self-hosted runners.
* `linux`, `windows`, or `macOS`: Applied depending on operating system. * `linux`, `windows`, or `macOS`: Applied depending on operating system.
@@ -63,8 +63,8 @@ These labels operate cumulatively, so a self-hosted runner’s labels must match
### Routing precedence for self-hosted runners ### Routing precedence for self-hosted runners
If you use both repository-level and organization-level runners, {{ site.data.variables.product.prodname_dotcom }} follows an order of precedence when routing jobs to self-hosted runners: If you use both repository-level and organization-level runners, {% data variables.product.prodname_dotcom %} follows an order of precedence when routing jobs to self-hosted runners:
1. The job's `runs-on` labels are processed. {{ site.data.variables.product.prodname_dotcom }} then attempts to locate a runner that matches the label requirements: 1. The job's `runs-on` labels are processed. {% data variables.product.prodname_dotcom %} then attempts to locate a runner that matches the label requirements:
2. The job is sent to a repository-level runner that matches the job labels. If no repository-level runner is available (either busy, offline, or no matching labels): 2. The job is sent to a repository-level runner that matches the job labels. If no repository-level runner is available (either busy, offline, or no matching labels):
3. The job is sent to an organization-level runner that matches the job labels. If no organization-level runner is available, the job request fails with an error. 3. The job is sent to an organization-level runner that matches the job labels. If no organization-level runner is available, the job request fails with an error.

6
content/actions/index.md
View File

@@ -1,7 +1,7 @@
--- ---
title: GitHub Actions Documentation title: GitHub Actions Documentation
shortTitle: GitHub Actions shortTitle: GitHub Actions
intro: 'Automate, customize, and execute your software development workflows right in your repository with {{ site.data.variables.product.prodname_actions }}. You can discover, create, and share actions to perform any job you''d like, including CI/CD, and combine actions in a completely customized workflow.' intro: 'Automate, customize, and execute your software development workflows right in your repository with {% data variables.product.prodname_actions %}. You can discover, create, and share actions to perform any job you''d like, including CI/CD, and combine actions in a completely customized workflow.'
gettingStartedLinks: gettingStartedLinks:
- /actions/quickstart - /actions/quickstart
- /actions/learn-github-actions - /actions/learn-github-actions
@@ -36,7 +36,7 @@ versions:
<div class="d-lg-flex gutter my-6 py-6"> <div class="d-lg-flex gutter my-6 py-6">
<div class="col-12 col-lg-4 mb-4 mb-lg-0"> <div class="col-12 col-lg-4 mb-4 mb-lg-0">
<div class="featured-links-heading pb-4"> <div class="featured-links-heading pb-4">
<h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{{ site.data.ui.toc.getting_started }}</h3> <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.getting_started %}</h3>
</div> </div>
<ul class="list-style-none"> <ul class="list-style-none">
{% for link in gettingStartedLinks %} {% for link in gettingStartedLinks %}
@@ -47,7 +47,7 @@ versions:
<div class="col-12 col-lg-4 mb-4 mb-lg-0"> <div class="col-12 col-lg-4 mb-4 mb-lg-0">
<div class="featured-links-heading pb-4"> <div class="featured-links-heading pb-4">
<h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{{ site.data.ui.toc.popular_articles }}</h3> <h3 class="f5 text-normal text-mono underline-dashed color-gray-5">{% data ui.toc.popular_articles %}</h3>
</div> </div>
<ul class="list-style-none"> <ul class="list-style-none">
{% for link in popularLinks %} {% for link in popularLinks %}

16
content/actions/learn-github-actions/essential-features-of-github-actions.md
View File

@@ -1,22 +1,22 @@
--- ---
title: Essential features of GitHub Actions title: Essential features of GitHub Actions
shortTitle: Essential features shortTitle: Essential features
intro: '{{ site.data.variables.product.prodname_actions }} are designed to help you build robust and dynamic automations. This guide will show you how to craft {{ site.data.variables.product.prodname_actions }} workflows that include environment variables, customized scripts, and more.' intro: '{% data variables.product.prodname_actions %} are designed to help you build robust and dynamic automations. This guide will show you how to craft {% data variables.product.prodname_actions %} workflows that include environment variables, customized scripts, and more.'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Overview ### Overview
{{ site.data.variables.product.prodname_actions }} allow you to customize your workflows to meet the unique needs of your application and team. In this guide, we'll discuss some of the essential customization techniques such as using variables, running scripts, and sharing data and artifacts between jobs. {% data variables.product.prodname_actions %} allow you to customize your workflows to meet the unique needs of your application and team. In this guide, we'll discuss some of the essential customization techniques such as using variables, running scripts, and sharing data and artifacts between jobs.
### Using variables in your workflows ### Using variables in your workflows
{{ site.data.variables.product.prodname_actions }} include default environment variables for each workflow run. If you need to use custom environment variables, you can set these in your YAML workflow file. This example demonstrates how to create custom variables named `POSTGRES_HOST` and `POSTGRES_PORT`. These variables are then available to the `node client.js` script. {% data variables.product.prodname_actions %} include default environment variables for each workflow run. If you need to use custom environment variables, you can set these in your YAML workflow file. This example demonstrates how to create custom variables named `POSTGRES_HOST` and `POSTGRES_PORT`. These variables are then available to the `node client.js` script.
```yaml ```yaml
jobs: jobs:
@@ -53,11 +53,11 @@ jobs:
shell: bash shell: bash
``` ```
For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
### Sharing data between jobs ### Sharing data between jobs
If your job generates files that you want to share with another job in the same workflow, or if you want to save the files for later reference, you can store them in {{ site.data.variables.product.prodname_dotcom }} as _artifacts_. Artifacts are the files created when you build and test your code. For example, artifacts might include binary or package files, test results, screenshots, or log files. Artifacts are associated with the workflow run where they were created and can be used by another job. If your job generates files that you want to share with another job in the same workflow, or if you want to save the files for later reference, you can store them in {% data variables.product.prodname_dotcom %} as _artifacts_. Artifacts are the files created when you build and test your code. For example, artifacts might include binary or package files, test results, screenshots, or log files. Artifacts are associated with the workflow run where they were created and can be used by another job.
For example, you can create a file and then upload it as an artifact. For example, you can create a file and then upload it as an artifact.
@@ -92,4 +92,4 @@ For more information about artifacts, see "[Persisting workflow data using artif
### Next steps ### Next steps
To continue learning about {{ site.data.variables.product.prodname_actions }}, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows)." To continue learning about {% data variables.product.prodname_actions %}, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows)."

18
content/actions/learn-github-actions/finding-and-customizing-actions.md
View File

@@ -12,8 +12,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Overview ### Overview
@@ -23,18 +23,18 @@ The actions you use in your workflow can be defined in:
- The same repository where your workflow file references the action - The same repository where your workflow file references the action
- A published Docker container image on Docker Hub - A published Docker container image on Docker Hub
{{ site.data.variables.product.prodname_marketplace }} is a central location for you to find actions created by the {{ site.data.variables.product.prodname_dotcom }} community. [{{ site.data.variables.product.prodname_marketplace }} page](https://github.com/marketplace/actions/) enables you to filter for actions by category. {% data variables.product.prodname_marketplace %} is a central location for you to find actions created by the {% data variables.product.prodname_dotcom %} community. [{% data variables.product.prodname_marketplace %} page](https://github.com/marketplace/actions/) enables you to filter for actions by category.
{{ site.data.reusables.actions.enterprise-marketplace-actions }} {% data reusables.actions.enterprise-marketplace-actions %}
### Browsing Marketplace actions in the workflow editor ### Browsing Marketplace actions in the workflow editor
You can search and browse actions directly in your repository's workflow editor. From the sidebar, you can search for a specific action, view featured actions, and browse featured categories. You can also view the number of stars an action has received from the {{ site.data.variables.product.prodname_dotcom }} community. You can search and browse actions directly in your repository's workflow editor. From the sidebar, you can search for a specific action, view featured actions, and browse featured categories. You can also view the number of stars an action has received from the {% data variables.product.prodname_dotcom %} community.
1. In your repository, browse to the workflow file you want to edit. 1. In your repository, browse to the workflow file you want to edit.
1. In the upper right corner of the file view, to open the workflow editor, click {% octicon "pencil" aria-label="The edit icon" %}. 1. In the upper right corner of the file view, to open the workflow editor, click {% octicon "pencil" aria-label="The edit icon" %}.
![Edit workflow file button](/assets/images/help/repository/actions-edit-workflow-file.png) ![Edit workflow file button](/assets/images/help/repository/actions-edit-workflow-file.png)
1. To the right of the editor, use the {{ site.data.variables.product.prodname_marketplace }} sidebar to browse actions. Actions with the {% octicon "verified" aria-label="The verified badge" %} badge indicate {{ site.data.variables.product.prodname_dotcom }} has verified the creator of the action as a partner organization. 1. To the right of the editor, use the {% data variables.product.prodname_marketplace %} sidebar to browse actions. Actions with the {% octicon "verified" aria-label="The verified badge" %} badge indicate {% data variables.product.prodname_dotcom %} has verified the creator of the action as a partner organization.
![Marketplace workflow sidebar](/assets/images/help/repository/actions-marketplace-sidebar.png) ![Marketplace workflow sidebar](/assets/images/help/repository/actions-marketplace-sidebar.png)
### Adding an action to your workflow ### Adding an action to your workflow
@@ -44,12 +44,12 @@ An action's listing page includes the action's version and the workflow syntax r
1. Navigate to the action you want to use in your workflow. 1. Navigate to the action you want to use in your workflow.
1. Under "Installation", click {% octicon "clippy" aria-label="The edit icon" %} to copy the workflow syntax. 1. Under "Installation", click {% octicon "clippy" aria-label="The edit icon" %} to copy the workflow syntax.
![View action listing](/assets/images/help/repository/actions-sidebar-detailed-view.png) ![View action listing](/assets/images/help/repository/actions-sidebar-detailed-view.png)
1. Paste the syntax as a new step in your workflow. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps)." 1. Paste the syntax as a new step in your workflow. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps)."
1. If the action requires you to provide inputs, set them in your workflow. For information on inputs an action might require, see "[Using inputs and outputs with an action](/actions/learn-github-actions/finding-and-customizing-actions#using-inputs-and-outputs-with-an-action)." 1. If the action requires you to provide inputs, set them in your workflow. For information on inputs an action might require, see "[Using inputs and outputs with an action](/actions/learn-github-actions/finding-and-customizing-actions#using-inputs-and-outputs-with-an-action)."
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
{{ site.data.reusables.dependabot.version-updates-for-actions }} {% data reusables.dependabot.version-updates-for-actions %}
{% endif %} {% endif %}
@@ -156,4 +156,4 @@ For some examples of Docker actions, see the [Docker-image.yml workflow](https:/
### Next steps ### Next steps
To continue learning about {{ site.data.variables.product.prodname_actions }}, see "[Essential features of {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions/essential-features-of-github-actions)." 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)."

2
content/actions/learn-github-actions/index.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Learn GitHub Actions title: Learn GitHub Actions
shortTitle: Learn GitHub Actions shortTitle: Learn GitHub Actions
intro: 'Whether you are new to {{ site.data.variables.product.prodname_actions }} or interested in learning all they have to offer, this guide will help you use {{ site.data.variables.product.prodname_actions }} to accelerate your application development workflows.' intro: 'Whether you are new to {% data variables.product.prodname_actions %} or interested in learning all they have to offer, this guide will help you use {% data variables.product.prodname_actions %} to accelerate your application development workflows.'
redirect_from: redirect_from:
- /articles/about-github-actions - /articles/about-github-actions
- /github/automating-your-workflow-with-github-actions/about-github-actions - /github/automating-your-workflow-with-github-actions/about-github-actions

48
content/actions/learn-github-actions/introduction-to-github-actions.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Introduction to GitHub Actions title: Introduction to GitHub Actions
shortTitle: Introduction to GitHub Actions shortTitle: Introduction to GitHub Actions
intro: 'Learn about the core concepts and various components of {{ site.data.variables.product.prodname_actions }}, and see an example that shows you how to add automation to your repository.' intro: 'Learn about the core concepts and various components of {% data variables.product.prodname_actions %}, and see an example that shows you how to add automation to your repository.'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/core-concepts-for-github-actions - /github/automating-your-workflow-with-github-actions/core-concepts-for-github-actions
- /actions/automating-your-workflow-with-github-actions/core-concepts-for-github-actions - /actions/automating-your-workflow-with-github-actions/core-concepts-for-github-actions
@@ -11,30 +11,30 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Overview ### Overview
{{ site.data.variables.product.prodname_actions }} help you automate tasks within your software development life cycle. {{ site.data.variables.product.prodname_actions }} are event-driven, meaning that you can run a series of commands after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command that executes a software testing script. {% data variables.product.prodname_actions %} help you automate tasks within your software development life cycle. {% data variables.product.prodname_actions %} are event-driven, meaning that you can run a series of commands after a specified event has occurred. For example, every time someone creates a pull request for a repository, you can automatically run a command that executes a software testing script.
This diagram demonstrates how you can use {{ site.data.variables.product.prodname_actions }} to automatically run your software testing scripts. An event automatically triggers the _workflow_, which contains a _job_. The job then uses _steps_ to control the order in which _actions_ are run. These actions are the commands that automate your software testing. This diagram demonstrates how you can use {% data variables.product.prodname_actions %} to automatically run your software testing scripts. An event automatically triggers the _workflow_, which contains a _job_. The job then uses _steps_ to control the order in which _actions_ are run. These actions are the commands that automate your software testing.
![Workflow overview](/assets/images/help/images/overview-actions-simple.png) ![Workflow overview](/assets/images/help/images/overview-actions-simple.png)
### The components of {{ site.data.variables.product.prodname_actions }} ### The components of {% data variables.product.prodname_actions %}
Below is a list of the multiple {{ site.data.variables.product.prodname_actions }} components that work together to run jobs. You can see how these components interact with each other. Below is a list of the multiple {% data variables.product.prodname_actions %} components that work together to run jobs. You can see how these components interact with each other.
![Component and service overview](/assets/images/help/images/overview-actions-design.png) ![Component and service overview](/assets/images/help/images/overview-actions-design.png)
#### Workflows #### Workflows
The workflow is an automated procedure that you add to your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by an event. The workflow can be used to build, test, package, release, or deploy a project on {{ site.data.variables.product.prodname_dotcom }}. The workflow is an automated procedure that you add to your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by an event. The workflow can be used to build, test, package, release, or deploy a project on {% data variables.product.prodname_dotcom %}.
#### Events #### Events
An event is a specific activity that triggers a workflow. For example, activity can originate from {{ site.data.variables.product.prodname_dotcom }} when someone pushes a commit to a repository or when an issue or pull request is created. You can also use the repository dispatch webhook to trigger a workflow when an external event occurs. For a complete list of events that can be used to trigger workflows, see [Events that trigger workflows](/actions/reference/events-that-trigger-workflows). An event is a specific activity that triggers a workflow. For example, activity can originate from {% data variables.product.prodname_dotcom %} when someone pushes a commit to a repository or when an issue or pull request is created. You can also use the repository dispatch webhook to trigger a workflow when an external event occurs. For a complete list of events that can be used to trigger workflows, see [Events that trigger workflows](/actions/reference/events-that-trigger-workflows).
#### Jobs #### Jobs
@@ -46,19 +46,19 @@ A step is an individual task that can run commands (known as _actions_). Each st
#### Actions #### Actions
_Actions_ are standalone commands that are combined into _steps_ to create a _job_. Actions are the smallest portable building block of a workflow. You can create your own actions, or use actions created by the {{ site.data.variables.product.prodname_dotcom }} community. To use an action in a workflow, you must include it as a step. _Actions_ are standalone commands that are combined into _steps_ to create a _job_. Actions are the smallest portable building block of a workflow. You can create your own actions, or use actions created by the {% data variables.product.prodname_dotcom %} community. To use an action in a workflow, you must include it as a step.
#### Runners #### Runners
A runner is a server that has the {{ site.data.variables.product.prodname_actions }} runner application installed. You can use a runner hosted by {{ site.data.variables.product.prodname_dotcom }}, or you can host your own. A runner listens for available jobs, runs one job at a time, and reports the progress, logs, and results back to {{ site.data.variables.product.prodname_dotcom }}. For {{ site.data.variables.product.prodname_dotcom }}-hosted runners, each job in a workflow runs in a fresh virtual environment. A runner is a server that has the {% data variables.product.prodname_actions %} runner application installed. You can use a runner hosted by {% data variables.product.prodname_dotcom %}, or you can host your own. A runner listens for available jobs, runs one job at a time, and reports the progress, logs, and results back to {% data variables.product.prodname_dotcom %}. For {% data variables.product.prodname_dotcom %}-hosted runners, each job in a workflow runs in a fresh virtual environment.
{{ site.data.variables.product.prodname_dotcom }}-hosted runners are based on Ubuntu Linux, Microsoft Windows, and macOS. For information on {{ site.data.variables.product.prodname_dotcom }}-hosted runners, see "[Virtual environments for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/virtual-environments-for-github-hosted-runners)." If you need a different operating system or require a specific hardware configuration, you can host your own runners. For information on self-hosted runners, see "[Hosting your own runners](/actions/hosting-your-own-runners)." {% data variables.product.prodname_dotcom %}-hosted runners are based on Ubuntu Linux, Microsoft Windows, and macOS. For information on {% data variables.product.prodname_dotcom %}-hosted runners, see "[Virtual environments for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/virtual-environments-for-github-hosted-runners)." If you need a different operating system or require a specific hardware configuration, you can host your own runners. For information on self-hosted runners, see "[Hosting your own runners](/actions/hosting-your-own-runners)."
### Create an example workflow ### Create an example workflow
{{ site.data.variables.product.prodname_actions }} uses YAML syntax to define the events, jobs, and steps. These YAML files are stored in your code repository, in a directory called `.github/workflows`. {% data variables.product.prodname_actions %} uses YAML syntax to define the events, jobs, and steps. These YAML files are stored in your code repository, in a directory called `.github/workflows`.
You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. In this workflow, {{ site.data.variables.product.prodname_actions }} checks out the pushed code, installs the software dependencies, and runs `bats -v`. You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. In this workflow, {% data variables.product.prodname_actions %} checks out the pushed code, installs the software dependencies, and runs `bats -v`.
1. In your repository, create the `.github/workflows/` directory to store your workflow files. 1. In your repository, create the `.github/workflows/` directory to store your workflow files.
1. In the `.github/workflows/` directory, create a new file called `learn-github-actions.yml` and add the following code. 1. In the `.github/workflows/` directory, create a new file called `learn-github-actions.yml` and add the following code.
@@ -74,9 +74,9 @@ You can create an example workflow in your repository that automatically trigger
- run: npm install -g bats - run: npm install -g bats
- run: bats -v - run: bats -v
``` ```
1. Commit these changes and push them to your {{ site.data.variables.product.prodname_dotcom }} repository. 1. Commit these changes and push them to your {% data variables.product.prodname_dotcom %} repository.
Your new {{ site.data.variables.product.prodname_actions }} workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. For details about a job's execution history, see "[Viewing the workflow's activity](/actions/learn-github-actions/introduction-to-github-actions#viewing-the-jobs-activity)." Your new {% data variables.product.prodname_actions %} workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. For details about a job's execution history, see "[Viewing the workflow's activity](/actions/learn-github-actions/introduction-to-github-actions#viewing-the-jobs-activity)."
### Understanding the workflow file ### Understanding the workflow file
@@ -91,7 +91,7 @@ To help you understand how YAML syntax is used to create a workflow file, this s
``` ```
</td> </td>
<td> <td>
<em>Optional</em> - The name of the workflow as it will appear in the Actions tab of the {{ site.data.variables.product.prodname_dotcom }} repository. <em>Optional</em> - The name of the workflow as it will appear in the Actions tab of the {% data variables.product.prodname_dotcom %} repository.
</td> </td>
</tr> </tr>
<tr> <tr>
@@ -102,7 +102,7 @@ To help you understand how YAML syntax is used to create a workflow file, this s
``` ```
</td> </td>
<td> <td>
Specify the event that automatically triggers the workflow file. This example uses the <code>push</code> event, so that the jobs run every time someone pushes a change to the repository. You can set up the workflow to only run on certain branches, paths, or tags. For syntax examples including or excluding branches, paths, or tags, see <a href="https://docs.github.com/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths">"Workflow syntax for {{ site.data.variables.product.prodname_actions }}."</a> Specify the event that automatically triggers the workflow file. This example uses the <code>push</code> event, so that the jobs run every time someone pushes a change to the repository. You can set up the workflow to only run on certain branches, paths, or tags. For syntax examples including or excluding branches, paths, or tags, see <a href="https://docs.github.com/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpaths">"Workflow syntax for {% data variables.product.prodname_actions %}."</a>
</td> </td>
</tr> </tr>
<tr> <tr>
@@ -135,7 +135,7 @@ To help you understand how YAML syntax is used to create a workflow file, this s
``` ```
</td> </td>
<td> <td>
Configures the job to run on an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see <a href="https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on">"Workflow syntax for {{ site.data.variables.product.prodname_actions }}."</a> Configures the job to run on an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see <a href="https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on">"Workflow syntax for {% data variables.product.prodname_actions %}."</a>
</td> </td>
</tr> </tr>
<tr> <tr>
@@ -197,16 +197,16 @@ To help you understand how YAML syntax is used to create a workflow file, this s
#### Visualizing the workflow file #### Visualizing the workflow file
In this diagram, you can see the workflow file you just created and how the {{ site.data.variables.product.prodname_actions }} components are organized in a hierarchy. Each step executes a single action. Steps 1 and 2 use prebuilt community actions. To find more prebuilt actions for your workflows, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)." In this diagram, you can see the workflow file you just created and how the {% data variables.product.prodname_actions %} components are organized in a hierarchy. Each step executes a single action. Steps 1 and 2 use prebuilt community actions. To find more prebuilt actions for your workflows, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)."
![Workflow overview](/assets/images/help/images/overview-actions-event.png) ![Workflow overview](/assets/images/help/images/overview-actions-event.png)
### Viewing the job's activity ### Viewing the job's activity
Once your job has started running, you can view each step's activity on {{ site.data.variables.product.prodname_dotcom }}. Once your job has started running, you can view each step's activity on {% data variables.product.prodname_dotcom %}.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
1. Under your repository name, click **Actions**. 1. Under your repository name, click **Actions**.
![Navigate to repository](/assets/images/help/images/learn-github-actions-repository.png) ![Navigate to repository](/assets/images/help/images/learn-github-actions-repository.png)
1. In the left sidebar, click the workflow you want to see. 1. In the left sidebar, click the workflow you want to see.
@@ -218,8 +218,8 @@ Once your job has started running, you can view each step's activity on {{ site.
### Next steps ### Next steps
To continue learning about {{ site.data.variables.product.prodname_actions }}, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)." To continue learning about {% data variables.product.prodname_actions %}, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)."
### Contacting support ### Contacting support
{{ site.data.reusables.github-actions.contacting-support }} {% data reusables.github-actions.contacting-support %}

14
content/actions/learn-github-actions/managing-complex-workflows.md
View File

@@ -1,22 +1,22 @@
--- ---
title: Managing complex workflows title: Managing complex workflows
shortTitle: Managing complex workflows shortTitle: Managing complex workflows
intro: 'This guide shows you how to use the advanced features of {{ site.data.variables.product.prodname_actions }}, with secret management, dependent jobs, caching, build matrices, and labels.' intro: 'This guide shows you how to use the advanced features of {% data variables.product.prodname_actions %}, with secret management, dependent jobs, caching, build matrices, and labels.'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Overview ### Overview
This article describes some of the advanced features of {{ site.data.variables.product.prodname_actions }} that help you work create more complex workflows. This article describes some of the advanced features of {% data variables.product.prodname_actions %} that help you work create more complex workflows.
### Storing secrets ### Storing secrets
If your workflows use sensitive data, such as passwords or certificates, you can save these in {{ site.data.variables.product.prodname_dotcom }} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow. If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow.
This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command. This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.
@@ -79,7 +79,7 @@ For more information, see [`jobs.<job_id>.strategy.matrix`](/actions/reference/w
### Caching dependencies ### Caching dependencies
{{ site.data.variables.product.prodname_dotcom }}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository. {% data variables.product.prodname_dotcom %}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.
This example demonstrates how to cache the ` ~/.npm` directory: This example demonstrates how to cache the ` ~/.npm` directory:
@@ -142,4 +142,4 @@ For more information, see ["Using labels with self-hosted runners](/actions/hos
### Next steps ### Next steps
To continue learning about {{ site.data.variables.product.prodname_actions }}, see "[Sharing workflows with your organization](/actions/learn-github-actions/sharing-workflows-with-your-organization)." To continue learning about {% data variables.product.prodname_actions %}, see "[Sharing workflows with your organization](/actions/learn-github-actions/sharing-workflows-with-your-organization)."

56
content/actions/learn-github-actions/migrating-from-azure-pipelines-to-github-actions.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Migrating from Azure Pipelines to GitHub Actions title: Migrating from Azure Pipelines to GitHub Actions
intro: '{{ site.data.variables.product.prodname_actions }} and Azure Pipelines share several configuration similarities, which makes migrating to {{ site.data.variables.product.prodname_actions }} relatively straightforward.' intro: '{% data variables.product.prodname_actions %} and Azure Pipelines share several configuration similarities, which makes migrating to {% data variables.product.prodname_actions %} relatively straightforward.'
redirect_from: redirect_from:
- /actions/migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions - /actions/migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions
versions: versions:
@@ -8,32 +8,32 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
Azure Pipelines and {{ site.data.variables.product.prodname_actions }} both allow you to create workflows that automatically build, test, publish, release, and deploy code. Azure Pipelines and {{ site.data.variables.product.prodname_actions }} share some similarities in workflow configuration: Azure Pipelines and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. Azure Pipelines and {% data variables.product.prodname_actions %} share some similarities in workflow configuration:
- Workflow configuration files are written in YAML and are stored in the code's repository. - Workflow configuration files are written in YAML and are stored in the code's repository.
- Workflows include one or more jobs. - Workflows include one or more jobs.
- Jobs include one or more steps or individual commands. - Jobs include one or more steps or individual commands.
- Steps or tasks can be reused and shared with the community. - Steps or tasks can be reused and shared with the community.
For more information, see "[Core concepts for {{ site.data.variables.product.prodname_actions }}](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)." For more information, see "[Core concepts for {% data variables.product.prodname_actions %}](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)."
### Key differences ### Key differences
When migrating from Azure Pipelines, consider the following differences: When migrating from Azure Pipelines, consider the following differences:
- Azure Pipelines supports a legacy _classic editor_, which lets you define your CI configuration in a GUI editor instead of creating the pipeline definition in a YAML file. {{ site.data.variables.product.prodname_actions }} uses YAML files to define workflows and does not support a graphical editor. - Azure Pipelines supports a legacy _classic editor_, which lets you define your CI configuration in a GUI editor instead of creating the pipeline definition in a YAML file. {% data variables.product.prodname_actions %} uses YAML files to define workflows and does not support a graphical editor.
- Azure Pipelines allows you to omit some structure in job definitions. For example, if you only have a single job, you don't need to define the job and only need to define its steps. {{ site.data.variables.product.prodname_actions }} requires explicit configuration, and YAML structure cannot be omitted. - Azure Pipelines allows you to omit some structure in job definitions. For example, if you only have a single job, you don't need to define the job and only need to define its steps. {% data variables.product.prodname_actions %} requires explicit configuration, and YAML structure cannot be omitted.
- Azure Pipelines supports _stages_ defined in the YAML file, which can be used to create deployment workflows. {{ site.data.variables.product.prodname_actions }} requires you to separate stages into separate YAML workflow files. - Azure Pipelines supports _stages_ defined in the YAML file, which can be used to create deployment workflows. {% data variables.product.prodname_actions %} requires you to separate stages into separate YAML workflow files.
- On-premises Azure Pipelines build agents can be selected with capabilities. {{ site.data.variables.product.prodname_actions }} self-hosted runners can be selected with labels. - On-premises Azure Pipelines build agents can be selected with capabilities. {% data variables.product.prodname_actions %} self-hosted runners can be selected with labels.
### Migrating jobs and steps ### Migrating jobs and steps
Jobs and steps in Azure Pipelines are very similar to jobs and steps in {{ site.data.variables.product.prodname_actions }}. In both systems, jobs have the following characteristics: Jobs and steps in Azure Pipelines are very similar to jobs and steps in {% data variables.product.prodname_actions %}. In both systems, jobs have the following characteristics:
* Jobs contain a series of steps that run sequentially. * Jobs contain a series of steps that run sequentially.
* Jobs run on separate virtual machines or in separate containers. * Jobs run on separate virtual machines or in separate containers.
@@ -43,7 +43,7 @@ Jobs and steps in Azure Pipelines are very similar to jobs and steps in {{ site.
You can run a script or a shell command as a step in a workflow. In Azure Pipelines, script steps can be specified using the `script` key, or with the `bash`, `powershell`, or `pwsh` keys. Scripts can also be specified as an input to the [Bash task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/bash?view=azure-devops) or the [PowerShell task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/powershell?view=azure-devops). You can run a script or a shell command as a step in a workflow. In Azure Pipelines, script steps can be specified using the `script` key, or with the `bash`, `powershell`, or `pwsh` keys. Scripts can also be specified as an input to the [Bash task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/bash?view=azure-devops) or the [PowerShell task](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/powershell?view=azure-devops).
In {{ site.data.variables.product.prodname_actions }}, all scripts are specified using the `run` key. To select a particular shell, you can specify the `shell` key when providing the script. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsrun)." In {% data variables.product.prodname_actions %}, all scripts are specified using the `run` key. To select a particular shell, you can specify the `shell` key when providing the script. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsrun)."
Below is an example of the syntax for each system: Below is an example of the syntax for each system:
@@ -53,7 +53,7 @@ Below is an example of the syntax for each system:
Azure Pipelines Azure Pipelines
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} {% data variables.product.prodname_actions %}
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -96,15 +96,15 @@ jobs:
### Differences in script error handling ### Differences in script error handling
In Azure Pipelines, scripts can be configured to error if any output is sent to `stderr`. {{ site.data.variables.product.prodname_actions }} does not support this configuration. In Azure Pipelines, scripts can be configured to error if any output is sent to `stderr`. {% data variables.product.prodname_actions %} does not support this configuration.
{{ site.data.variables.product.prodname_actions }} configures shells to "fail fast" whenever possible, which stops the script immediately if one of the commands in a script exits with an error code. In contrast, Azure Pipelines requires explicit configuration to exit immediately on an error. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference)." {% data variables.product.prodname_actions %} configures shells to "fail fast" whenever possible, which stops the script immediately if one of the commands in a script exits with an error code. In contrast, Azure Pipelines requires explicit configuration to exit immediately on an error. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference)."
### Differences in the default shell on Windows ### Differences in the default shell on Windows
In Azure Pipelines, the default shell for scripts on Windows platforms is the Command shell (_cmd.exe_). In {{ site.data.variables.product.prodname_actions }}, the default shell for scripts on Windows platforms is PowerShell. PowerShell has several differences in built-in commands, variable expansion, and flow control. In Azure Pipelines, the default shell for scripts on Windows platforms is the Command shell (_cmd.exe_). In {% data variables.product.prodname_actions %}, the default shell for scripts on Windows platforms is PowerShell. PowerShell has several differences in built-in commands, variable expansion, and flow control.
If you're running a simple command, you might be able to run a Command shell script in PowerShell without any changes. But in most cases, you will either need to update your script with PowerShell syntax or instruct {{ site.data.variables.product.prodname_actions }} to run the script with the Command shell instead of PowerShell. You can do this by specifying `shell` as `cmd`. If you're running a simple command, you might be able to run a Command shell script in PowerShell without any changes. But in most cases, you will either need to update your script with PowerShell syntax or instruct {% data variables.product.prodname_actions %} to run the script with the Command shell instead of PowerShell. You can do this by specifying `shell` as `cmd`.
Below is an example of the syntax for each system: Below is an example of the syntax for each system:
@@ -114,7 +114,7 @@ Below is an example of the syntax for each system:
Azure Pipelines Azure Pipelines
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} {% data variables.product.prodname_actions %}
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -146,13 +146,13 @@ jobs:
</tr> </tr>
</table> </table>
For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell)." For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#using-a-specific-shell)."
### Migrating conditionals and expression syntax ### Migrating conditionals and expression syntax
Azure Pipelines and {{ site.data.variables.product.prodname_actions }} can both run steps conditionally. In Azure Pipelines, conditional expressions are specified using the `condition` key. In {{ site.data.variables.product.prodname_actions }}, conditional expressions are specified using the `if` key. Azure Pipelines and {% data variables.product.prodname_actions %} can both run steps conditionally. In Azure Pipelines, conditional expressions are specified using the `condition` key. In {% data variables.product.prodname_actions %}, conditional expressions are specified using the `if` key.
Azure Pipelines uses functions within expressions to execute steps conditionally. In contrast, {{ site.data.variables.product.prodname_actions }} uses an infix notation. For example, you must replace the `eq` function in Azure Pipelines with the `==` operator in {{ site.data.variables.product.prodname_actions }}. Azure Pipelines uses functions within expressions to execute steps conditionally. In contrast, {% data variables.product.prodname_actions %} uses an infix notation. For example, you must replace the `eq` function in Azure Pipelines with the `==` operator in {% data variables.product.prodname_actions %}.
Below is an example of the syntax for each system: Below is an example of the syntax for each system:
@@ -162,7 +162,7 @@ Below is an example of the syntax for each system:
Azure Pipelines Azure Pipelines
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} {% data variables.product.prodname_actions %}
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -194,11 +194,11 @@ jobs:
</tr> </tr>
</table> </table>
For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
### Dependencies between jobs ### Dependencies between jobs
Both Azure Pipelines and {{ site.data.variables.product.prodname_actions }} allow you to set dependencies for a job. In both systems, jobs run in parallel by default, but job dependencies can be specified explicitly. In Azure Pipelines, this is done with the `dependsOn` key. In {{ site.data.variables.product.prodname_actions }}, this is done with the `needs` key. Both Azure Pipelines and {% data variables.product.prodname_actions %} allow you to set dependencies for a job. In both systems, jobs run in parallel by default, but job dependencies can be specified explicitly. In Azure Pipelines, this is done with the `dependsOn` key. In {% data variables.product.prodname_actions %}, this is done with the `needs` key.
Below is an example of the syntax for each system. The workflows start a first job named `initial`, and when that job completes, two jobs named `fanout1` and `fanout2` will run. Finally, when those jobs complete, the job `fanin` will run. Below is an example of the syntax for each system. The workflows start a first job named `initial`, and when that job completes, two jobs named `fanout1` and `fanout2` will run. Finally, when those jobs complete, the job `fanin` will run.
@@ -208,7 +208,7 @@ Below is an example of the syntax for each system. The workflows start a first j
Azure Pipelines Azure Pipelines
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} {% data variables.product.prodname_actions %}
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -271,11 +271,11 @@ jobs:
</tr> </tr>
</table> </table>
For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)." For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)."
### Migrating tasks to actions ### Migrating tasks to actions
Azure Pipelines uses _tasks_, which are application components that can be re-used in multiple workflows. {{ site.data.variables.product.prodname_actions }} uses _actions_, which can be used to perform tasks and customize your workflow. In both systems, you can specify the name of the task or action to run, along with any required inputs as key/value pairs. Azure Pipelines uses _tasks_, which are application components that can be re-used in multiple workflows. {% data variables.product.prodname_actions %} uses _actions_, which can be used to perform tasks and customize your workflow. In both systems, you can specify the name of the task or action to run, along with any required inputs as key/value pairs.
Below is an example of the syntax for each system: Below is an example of the syntax for each system:
@@ -285,7 +285,7 @@ Below is an example of the syntax for each system:
Azure Pipelines Azure Pipelines
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} {% data variables.product.prodname_actions %}
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -323,5 +323,5 @@ jobs:
</tr> </tr>
</table> </table>
You can find actions that you can use in your workflow in [{{ site.data.variables.product.prodname_marketplace }}](https://github.com/marketplace?type=actions), or you can create your own actions. For more information, see "[Creating actions](/actions/creating-actions)." You can find actions that you can use in your workflow in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions), or you can create your own actions. For more information, see "[Creating actions](/actions/creating-actions)."

46
content/actions/learn-github-actions/migrating-from-circleci-to-github-actions.md
View File

@@ -8,61 +8,61 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
CircleCI and {{ site.data.variables.product.prodname_actions }} both allow you to create workflows that automatically build, test, publish, release, and deploy code. CircleCI and {{ site.data.variables.product.prodname_actions }} share some similarities in workflow configuration: CircleCI and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. CircleCI and {% data variables.product.prodname_actions %} share some similarities in workflow configuration:
- Workflow configuration files are written in YAML and stored in the repository. - Workflow configuration files are written in YAML and stored in the repository.
- Workflows include one or more jobs. - Workflows include one or more jobs.
- Jobs include one or more steps or individual commands. - Jobs include one or more steps or individual commands.
- Steps or tasks can be reused and shared with the community. - Steps or tasks can be reused and shared with the community.
For more information, see "[Core concepts for {{ site.data.variables.product.prodname_actions }}](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)." For more information, see "[Core concepts for {% data variables.product.prodname_actions %}](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)."
### Key differences ### Key differences
When migrating from CircleCI, consider the following differences: When migrating from CircleCI, consider the following differences:
- CircleCI’s automatic test parallelism automatically groups tests according to user-specified rules or historical timing information. This functionality is not built into {{ site.data.variables.product.prodname_actions }}. - CircleCI’s automatic test parallelism automatically groups tests according to user-specified rules or historical timing information. This functionality is not built into {% data variables.product.prodname_actions %}.
- Actions that execute in Docker containers are sensitive to permissions problems since containers have a different mapping of users. You can avoid many of these problems by not using the `USER` instruction in your *Dockerfile*. For more information about the Docker filesystem on {{ site.data.variables.product.product_name }}-hosted runners, see "[Virtual environments for {{ site.data.variables.product.product_name }}-hosted runners](/actions/reference/virtual-environments-for-github-hosted-runners#docker-container-filesystem)." - Actions that execute in Docker containers are sensitive to permissions problems since containers have a different mapping of users. You can avoid many of these problems by not using the `USER` instruction in your *Dockerfile*. For more information about the Docker filesystem on {% data variables.product.product_name %}-hosted runners, see "[Virtual environments for {% data variables.product.product_name %}-hosted runners](/actions/reference/virtual-environments-for-github-hosted-runners#docker-container-filesystem)."
### Migrating workflows and jobs ### Migrating workflows and jobs
CircleCI defines `workflows` in the *config.yml* file, which allows you to configure more than one workflow. {{ site.data.variables.product.product_name }} requires one workflow file per workflow, and as a consequence, does not require you to declare `workflows`. You'll need to create a new workflow file for each workflow configured in *config.yml*. CircleCI defines `workflows` in the *config.yml* file, which allows you to configure more than one workflow. {% data variables.product.product_name %} requires one workflow file per workflow, and as a consequence, does not require you to declare `workflows`. You'll need to create a new workflow file for each workflow configured in *config.yml*.
Both CircleCI and {{ site.data.variables.product.prodname_actions }} configure `jobs` in the configuration file using similar syntax. If you configure any dependencies between jobs using `requires` in your CircleCI workflow, you can use the equivalent {{ site.data.variables.product.prodname_actions }} `needs` syntax. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)." Both CircleCI and {% data variables.product.prodname_actions %} configure `jobs` in the configuration file using similar syntax. If you configure any dependencies between jobs using `requires` in your CircleCI workflow, you can use the equivalent {% data variables.product.prodname_actions %} `needs` syntax. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)."
### Migrating orbs to actions ### Migrating orbs to actions
Both CircleCI and {{ site.data.variables.product.prodname_actions }} provide a mechanism to reuse and share tasks in a workflow. CircleCI uses a concept called orbs, written in YAML, to provide tasks that people can reuse in a workflow. {{ site.data.variables.product.prodname_actions }} has powerful and flexible reusable components called actions, which you build with either JavaScript files or Docker images. You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {{ site.data.variables.product.product_name }}'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. For more information, see "[Creating actions](/actions/creating-actions)." Both CircleCI and {% data variables.product.prodname_actions %} provide a mechanism to reuse and share tasks in a workflow. CircleCI uses a concept called orbs, written in YAML, to provide tasks that people can reuse in a workflow. {% data variables.product.prodname_actions %} has powerful and flexible reusable components called actions, which you build with either JavaScript files or Docker images. 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.product_name %}'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. For more information, see "[Creating actions](/actions/creating-actions)."
CircleCI can reuse pieces of workflows with YAML anchors and aliases. {{ site.data.variables.product.prodname_actions }} supports the most common need for reusability using build matrixes. For more information about build matrixes, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows/#using-a-build-matrix)." CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using build matrixes. For more information about build matrixes, see "[Managing complex workflows](/actions/learn-github-actions/managing-complex-workflows/#using-a-build-matrix)."
### Using Docker images ### Using Docker images
Both CircleCI and {{ site.data.variables.product.prodname_actions }} support running steps inside of a Docker image. Both CircleCI and {% data variables.product.prodname_actions %} support running steps inside of a Docker image.
CircleCI provides a set of pre-built images with common dependencies. These images have the `USER` set to `circleci`, which causes permissions to conflict with {{ site.data.variables.product.prodname_actions }}. CircleCI provides a set of pre-built images with common dependencies. These images have the `USER` set to `circleci`, which causes permissions to conflict with {% data variables.product.prodname_actions %}.
We recommend that you move away from CircleCI's pre-built images when you migrate to {{ site.data.variables.product.prodname_actions }}. In many cases, you can use actions to install the additional dependencies you need. We recommend that you move away from CircleCI's pre-built images when you migrate to {% data variables.product.prodname_actions %}. In many cases, you can use actions to install the additional dependencies you need.
For more information about the Docker filesystem, see "[Virtual environments for {{ site.data.variables.product.product_name }}-hosted runners](/actions/reference/virtual-environments-for-github-hosted-runners#docker-container-filesystem)." For more information about the Docker filesystem, see "[Virtual environments for {% data variables.product.product_name %}-hosted runners](/actions/reference/virtual-environments-for-github-hosted-runners#docker-container-filesystem)."
For more information about the tools and packages available on {{ site.data.variables.product.prodname_dotcom }}-hosted virtual environments, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". For more information about the tools and packages available on {% data variables.product.prodname_dotcom %}-hosted virtual environments, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)".
### Using variables and secrets ### Using variables and secrets
CircleCI and {{ site.data.variables.product.prodname_actions }} support setting environment variables in the configuration file and creating secrets using the CircleCI or {{ site.data.variables.product.product_name }} UI. CircleCI and {% data variables.product.prodname_actions %} support setting environment variables in the configuration file and creating secrets using the CircleCI or {% data variables.product.product_name %} UI.
For more information, see "[Using environment variables](/actions/configuring-and-managing-workflows/using-environment-variables)" and "[Creating and using encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)." For more information, see "[Using environment variables](/actions/configuring-and-managing-workflows/using-environment-variables)" and "[Creating and using encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)."
### Caching ### Caching
CircleCI and {{ site.data.variables.product.prodname_actions }} provide a method to manually cache files in the configuration file. CircleCI and {% data variables.product.prodname_actions %} provide a method to manually cache files in the configuration file.
Below is an example of the syntax for each system. Below is an example of the syntax for each system.
@@ -103,13 +103,13 @@ GitHub Actions
For more information, see "[Caching dependencies to speed up workflows](/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)." For more information, see "[Caching dependencies to speed up workflows](/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)."
{{ site.data.variables.product.prodname_actions }} does not have an equivalent of CircleCI’s Docker Layer Caching (or DLC). {% data variables.product.prodname_actions %} does not have an equivalent of CircleCI’s Docker Layer Caching (or DLC).
### Persisting data between jobs ### Persisting data between jobs
Both CircleCI and {{ site.data.variables.product.prodname_actions }} provide mechanisms to persist data between jobs. Both CircleCI and {% data variables.product.prodname_actions %} provide mechanisms to persist data between jobs.
Below is an example in CircleCI and {{ site.data.variables.product.prodname_actions }} configuration syntax. Below is an example in CircleCI and {% data variables.product.prodname_actions %} configuration syntax.
<table> <table>
<tr> <tr>
@@ -163,9 +163,9 @@ For more information, see "[Persisting workflow data using artifacts](/actions/c
Both systems enable you to include additional containers for databases, caching, or other dependencies. Both systems enable you to include additional containers for databases, caching, or other dependencies.
In CircleCI, the first image listed in the *config.yaml* is the primary image used to run commands. {{ site.data.variables.product.prodname_actions }} uses explicit sections: use `container` for the primary container, and list additional containers in `services`. In CircleCI, the first image listed in the *config.yaml* is the primary image used to run commands. {% data variables.product.prodname_actions %} uses explicit sections: use `container` for the primary container, and list additional containers in `services`.
Below is an example in CircleCI and {{ site.data.variables.product.prodname_actions }} configuration syntax. Below is an example in CircleCI and {% data variables.product.prodname_actions %} configuration syntax.
<table class="d-block"> <table class="d-block">
<tr> <tr>
@@ -285,7 +285,7 @@ For more information, see "[About service containers](/actions/configuring-and-m
### Complete Example ### Complete Example
Below is a real-world example. The left shows the actual CircleCI *config.yml* for the [thoughtbot/administrator](https://github.com/thoughtbot/administrate) repository. The right shows the {{ site.data.variables.product.prodname_actions }} equivalent. Below is a real-world example. The left shows the actual CircleCI *config.yml* for the [thoughtbot/administrator](https://github.com/thoughtbot/administrate) repository. The right shows the {% data variables.product.prodname_actions %} equivalent.
<table class="d-block"> <table class="d-block">
<tr> <tr>

54
content/actions/learn-github-actions/migrating-from-jenkins-to-github-actions.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Migrating from Jenkins to GitHub Actions title: Migrating from Jenkins to GitHub Actions
intro: '{{ site.data.variables.product.prodname_actions }} and Jenkins share multiple similarities, which makes migration to {{ site.data.variables.product.prodname_actions }} relatively straightforward.' intro: '{% data variables.product.prodname_actions %} and Jenkins share multiple similarities, which makes migration to {% data variables.product.prodname_actions %} relatively straightforward.'
redirect_from: redirect_from:
- /actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions - /actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions
versions: versions:
@@ -8,24 +8,24 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
Jenkins and {{ site.data.variables.product.prodname_actions }} both allow you to create workflows that automatically build, test, publish, release, and deploy code. Jenkins and {{ site.data.variables.product.prodname_actions }} share some similarities in workflow configuration: Jenkins and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. Jenkins and {% data variables.product.prodname_actions %} share some similarities in workflow configuration:
- Jenkins creates workflows using _Declarative Pipelines_, which are similar to {{ site.data.variables.product.prodname_actions }} workflow files. - Jenkins creates workflows using _Declarative Pipelines_, which are similar to {% data variables.product.prodname_actions %} workflow files.
- Jenkins uses _stages_ to run a collection of steps, while {{ site.data.variables.product.prodname_actions }} uses jobs to group one or more steps or individual commands. - Jenkins uses _stages_ to run a collection of steps, while {% data variables.product.prodname_actions %} uses jobs to group one or more steps or individual commands.
- Jenkins and {{ site.data.variables.product.prodname_actions }} support container-based builds. For more information, see "[Creating a Docker container action](/articles/creating-a-docker-container-action)." - Jenkins and {% data variables.product.prodname_actions %} support container-based builds. For more information, see "[Creating a Docker container action](/articles/creating-a-docker-container-action)."
- Steps or tasks can be reused and shared with the community. - Steps or tasks can be reused and shared with the community.
For more information, see "[Core concepts for {{ site.data.variables.product.prodname_actions }}](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)." For more information, see "[Core concepts for {% data variables.product.prodname_actions %}](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)."
### Key differences ### Key differences
- Jenkins has two types of syntax for creating pipelines: Declarative Pipeline and Scripted Pipeline. {{ site.data.variables.product.prodname_actions }} uses YAML to create workflows and configuration files. For more information, see "[Workflow syntax for GitHub Actions](/actions/reference/workflow-syntax-for-github-actions)." - Jenkins has two types of syntax for creating pipelines: Declarative Pipeline and Scripted Pipeline. {% data variables.product.prodname_actions %} uses YAML to create workflows and configuration files. For more information, see "[Workflow syntax for GitHub Actions](/actions/reference/workflow-syntax-for-github-actions)."
- Jenkins deployments are typically self-hosted, with users maintaining the servers in their own data centers. {{ site.data.variables.product.prodname_actions }} offers a hybrid cloud approach by hosting its own runners that you can use to run jobs, while also supporting self-hosted runners. For more information, see [About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners). - Jenkins deployments are typically self-hosted, with users maintaining the servers in their own data centers. {% data variables.product.prodname_actions %} offers a hybrid cloud approach by hosting its own runners that you can use to run jobs, while also supporting self-hosted runners. For more information, see [About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners).
### Comparing capabilities ### Comparing capabilities
@@ -33,17 +33,17 @@ For more information, see "[Core concepts for {{ site.data.variables.product.pro
Jenkins lets you send builds to a single build agent, or you can distribute them across multiple agents. You can also classify these agents according to various attributes, such as operating system types. Jenkins lets you send builds to a single build agent, or you can distribute them across multiple agents. You can also classify these agents according to various attributes, such as operating system types.
Similiarly, {{ site.data.variables.product.prodname_actions }} can send jobs to {{ site.data.variables.product.prodname_dotcom }}-hosted or self-hosted runners, and you can use labels to classify runners according to various attributes. The following table compares how the distributed build concept is implemented for both Jenkins and {{ site.data.variables.product.prodname_actions }}. Similiarly, {% data variables.product.prodname_actions %} can send jobs to {% data variables.product.prodname_dotcom %}-hosted or self-hosted runners, and you can use labels to classify runners according to various attributes. The following table compares how the distributed build concept is implemented for both Jenkins and {% data variables.product.prodname_actions %}.
| Jenkins | {{ site.data.variables.product.prodname_actions }} | | Jenkins | {% data variables.product.prodname_actions %} |
| ------------- | ------------- | | ------------- | ------------- |
| [`agents`](https://wiki.jenkins.io/display/JENKINS/Distributed+builds) | [`runners`](/actions/learn-github-actions/introduction-to-github-actions#runners) <br> [`self-hosted runners`](/actions/hosting-your-own-runners/about-self-hosted-runners)| | [`agents`](https://wiki.jenkins.io/display/JENKINS/Distributed+builds) | [`runners`](/actions/learn-github-actions/introduction-to-github-actions#runners) <br> [`self-hosted runners`](/actions/hosting-your-own-runners/about-self-hosted-runners)|
#### Using sections to organize pipelines #### Using sections to organize pipelines
Jenkins splits its Declarative Pipelines into multiple sections. Similiarly, {{ site.data.variables.product.prodname_actions }} organizes its workflows into separate sections. The table below compares Jenkins sections with the {{ site.data.variables.product.prodname_actions }} workflow. Jenkins splits its Declarative Pipelines into multiple sections. Similiarly, {% data variables.product.prodname_actions %} organizes its workflows into separate sections. The table below compares Jenkins sections with the {% data variables.product.prodname_actions %} workflow.
|Jenkins Directives | {{ site.data.variables.product.prodname_actions }} | |Jenkins Directives | {% data variables.product.prodname_actions %} |
| ------------- | ------------- | | ------------- | ------------- |
| [`agent`](https://jenkins.io/doc/book/pipeline/syntax/#agent) | [`jobs.<job_id>.runs-on`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-on) <br> [`jobs.<job_id>.container`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idcontainer)| | [`agent`](https://jenkins.io/doc/book/pipeline/syntax/#agent) | [`jobs.<job_id>.runs-on`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idruns-on) <br> [`jobs.<job_id>.container`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idcontainer)|
| [`post`](https://jenkins.io/doc/book/pipeline/syntax/#post) | | | [`post`](https://jenkins.io/doc/book/pipeline/syntax/#post) | |
@@ -53,9 +53,9 @@ Jenkins splits its Declarative Pipelines into multiple sections. Similiarly, {{
### Using directives ### Using directives
Jenkins uses directives to manage _Declarative Pipelines_. These directives define the characteristics of your workflow and how it will execute. The table below demonstrates how these directives map to concepts within {{ site.data.variables.product.prodname_actions }}. Jenkins uses directives to manage _Declarative Pipelines_. These directives define the characteristics of your workflow and how it will execute. The table below demonstrates how these directives map to concepts within {% data variables.product.prodname_actions %}.
| Jenkins Directives | {{ site.data.variables.product.prodname_actions }} | | Jenkins Directives | {% data variables.product.prodname_actions %} |
| ------------- | ------------- | | ------------- | ------------- |
| [`environment`](https://jenkins.io/doc/book/pipeline/syntax/#environment) | [`jobs.<job_id>.env`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env) <br> [`jobs.<job_id>.steps.env`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepsenv) | | [`environment`](https://jenkins.io/doc/book/pipeline/syntax/#environment) | [`jobs.<job_id>.env`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env) <br> [`jobs.<job_id>.steps.env`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepsenv) |
| [`options`](https://jenkins.io/doc/book/pipeline/syntax/#parameters) | [`jobs.<job_id>.strategy`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategy) <br> [`jobs.<job_id>.strategy.fail-fast`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast) <br> [`jobs.<job_id>.timeout-minutes`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)| | [`options`](https://jenkins.io/doc/book/pipeline/syntax/#parameters) | [`jobs.<job_id>.strategy`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategy) <br> [`jobs.<job_id>.strategy.fail-fast`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast) <br> [`jobs.<job_id>.timeout-minutes`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)|
@@ -64,7 +64,7 @@ Jenkins uses directives to manage _Declarative Pipelines_. These directives defi
| [`triggers { upstreamprojects() }`](https://jenkins.io/doc/book/pipeline/syntax/#triggers) | [`jobs.<job_id>.needs`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idneeds) | | [`triggers { upstreamprojects() }`](https://jenkins.io/doc/book/pipeline/syntax/#triggers) | [`jobs.<job_id>.needs`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idneeds) |
| [Jenkins cron syntax](https://jenkins.io/doc/book/pipeline/syntax/#cron-syntax) | [`on.schedule`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onschedule) | | [Jenkins cron syntax](https://jenkins.io/doc/book/pipeline/syntax/#cron-syntax) | [`on.schedule`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onschedule) |
| [`stage`](https://jenkins.io/doc/book/pipeline/syntax/#stage) | [`jobs.<job_id>`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_id) <br> [`jobs.<job_id>.name`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idname)| | [`stage`](https://jenkins.io/doc/book/pipeline/syntax/#stage) | [`jobs.<job_id>`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_id) <br> [`jobs.<job_id>.name`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idname)|
| [`tools`](https://jenkins.io/doc/book/pipeline/syntax/#tools) | [Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software) | | [`tools`](https://jenkins.io/doc/book/pipeline/syntax/#tools) | [Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software) |
| [`input`](https://jenkins.io/doc/book/pipeline/syntax/#input) | [`inputs`](/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions#inputs) | | [`input`](https://jenkins.io/doc/book/pipeline/syntax/#input) | [`inputs`](/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions#inputs) |
| [`when`](https://jenkins.io/doc/book/pipeline/syntax/#when) | [`jobs.<job_id>.if`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idif) | | [`when`](https://jenkins.io/doc/book/pipeline/syntax/#when) | [`jobs.<job_id>.if`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idif) |
@@ -73,17 +73,17 @@ Jenkins uses directives to manage _Declarative Pipelines_. These directives defi
#### Parallel job processing #### Parallel job processing
Jenkins can run the `stages` and `steps` in parallel, while {{ site.data.variables.product.prodname_actions }} currently only runs jobs in parallel. Jenkins can run the `stages` and `steps` in parallel, while {% data variables.product.prodname_actions %} currently only runs jobs in parallel.
| Jenkins Parallel | {{ site.data.variables.product.prodname_actions }} | | Jenkins Parallel | {% data variables.product.prodname_actions %} |
| ------------- | ------------- | | ------------- | ------------- |
| [`parallel`](https://jenkins.io/doc/book/pipeline/syntax/#parallel) | [`jobs.<job_id>.strategy.max-parallel`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel) | | [`parallel`](https://jenkins.io/doc/book/pipeline/syntax/#parallel) | [`jobs.<job_id>.strategy.max-parallel`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel) |
#### Build matrix #### Build matrix
Both {{ site.data.variables.product.prodname_actions }} and Jenkins let you use a build matrix to define various system combinations. Both {% data variables.product.prodname_actions %} and Jenkins let you use a build matrix to define various system combinations.
| Jenkins | {{ site.data.variables.product.prodname_actions }} | | Jenkins | {% data variables.product.prodname_actions %} |
| ------------- | ------------- | | ------------- | ------------- |
| [`axis`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-axes) | [`strategy/matrix`](/actions/learn-github-actions/managing-complex-workflows/#using-a-build-matrix) <br> [`context`](/actions/reference/context-and-expression-syntax-for-github-actions) | | [`axis`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-axes) | [`strategy/matrix`](/actions/learn-github-actions/managing-complex-workflows/#using-a-build-matrix) <br> [`context`](/actions/reference/context-and-expression-syntax-for-github-actions) |
| [`stages`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-stages) | [`steps-context`](/actions/reference/context-and-expression-syntax-for-github-actions#steps-context) | | [`stages`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-stages) | [`steps-context`](/actions/reference/context-and-expression-syntax-for-github-actions#steps-context) |
@@ -91,9 +91,9 @@ Both {{ site.data.variables.product.prodname_actions }} and Jenkins let you use
#### Using steps to execute tasks #### Using steps to execute tasks
Jenkins groups `steps` together in `stages`. Each of these steps can be a script, function, or command, among others. Similarly, {{ site.data.variables.product.prodname_actions }} uses `jobs` to execute specific groups of `steps`. Jenkins groups `steps` together in `stages`. Each of these steps can be a script, function, or command, among others. Similarly, {% data variables.product.prodname_actions %} uses `jobs` to execute specific groups of `steps`.
| Jenkins steps | {{ site.data.variables.product.prodname_actions }} | | Jenkins steps | {% data variables.product.prodname_actions %} |
| ------------- | ------------- | | ------------- | ------------- |
| [`script`](https://jenkins.io/doc/book/pipeline/syntax/#script) | [`jobs.<job_id>.steps`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idsteps) | | [`script`](https://jenkins.io/doc/book/pipeline/syntax/#script) | [`jobs.<job_id>.steps`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idsteps) |
@@ -107,7 +107,7 @@ Jenkins groups `steps` together in `stages`. Each of these steps can be a script
Jenkins Pipeline Jenkins Pipeline
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} Workflow {% data variables.product.prodname_actions %} Workflow
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -143,7 +143,7 @@ Jenkins Pipeline
Jenkins Pipeline Jenkins Pipeline
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} Workflow {% data variables.product.prodname_actions %} Workflow
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -181,7 +181,7 @@ Jenkins Pipeline
Jenkins Pipeline Jenkins Pipeline
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} Workflow {% data variables.product.prodname_actions %} Workflow
</th> </th>
</tr> </tr>
<tr> <tr>
@@ -224,7 +224,7 @@ Jenkins Pipeline
Jenkins Pipeline Jenkins Pipeline
</th> </th>
<th> <th>
{{ site.data.variables.product.prodname_actions }} Workflow {% data variables.product.prodname_actions %} Workflow
</th> </th>
</tr> </tr>
<tr> <tr>

34
content/actions/learn-github-actions/security-hardening-for-github-actions.md
View File

@@ -1,8 +1,8 @@
--- ---
title: Security hardening for GitHub Actions title: Security hardening for GitHub Actions
shortTitle: Security hardening shortTitle: Security hardening
intro: 'Good security practices for using {{ site.data.variables.product.prodname_actions }} features.' intro: 'Good security practices for using {% data variables.product.prodname_actions %} features.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/getting-started-with-github-actions/security-hardening-for-github-actions - /actions/getting-started-with-github-actions/security-hardening-for-github-actions
versions: versions:
@@ -10,20 +10,20 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Overview ### Overview
This guide explains how to configure security hardening for certain {{ site.data.variables.product.prodname_actions }} features. If the {{ site.data.variables.product.prodname_actions }} concepts are unfamiliar, see "[Core concepts for GitHub Actions](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)." This guide explains how to configure security hardening for certain {% data variables.product.prodname_actions %} features. If the {% data variables.product.prodname_actions %} concepts are unfamiliar, see "[Core concepts for GitHub Actions](/actions/getting-started-with-github-actions/core-concepts-for-github-actions)."
### Using secrets ### Using secrets
Sensitive values should never be stored as plaintext in workflow files, but rather as secrets. [Secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) can be configured at the organization or repository level, and allow you to store sensitive information in {{ site.data.variables.product.product_name }}. Sensitive values should never be stored as plaintext in workflow files, but rather as secrets. [Secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) can be configured at the organization or repository level, and allow you to store sensitive information in {% data variables.product.product_name %}.
Secrets use [Libsodium sealed boxes](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes), so that they are encrypted before reaching {{ site.data.variables.product.product_name }}. This occurs when the secret is submitted [using the UI](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) or through the [REST API](/rest/reference/actions#secrets). This client-side encryption helps the minimize risks related to accidental logging (for example, exception logs and request logs, among others) within {{ site.data.variables.product.product_name }}'s infrastructure. Once the secret is uploaded, {{ site.data.variables.product.product_name }} is then able to decrypt it so that it can be injected into the workflow runtime. Secrets use [Libsodium sealed boxes](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes), so that they are encrypted before reaching {% data variables.product.product_name %}. This occurs when the secret is submitted [using the UI](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) or through the [REST API](/rest/reference/actions#secrets). This client-side encryption helps the minimize risks related to accidental logging (for example, exception logs and request logs, among others) within {% data variables.product.product_name %}'s infrastructure. Once the secret is uploaded, {% data variables.product.product_name %} is then able to decrypt it so that it can be injected into the workflow runtime.
To help prevent accidental disclosure, {{ site.data.variables.product.product_name }} uses a mechanism that attempts to redact any secrets that appear in run logs. This redaction looks for exact matches of any configured secrets, as well as common encodings of the values, such as Base64. However, because there are multiple ways a secret value can be transformed, this redaction is not guaranteed. As a result, there are certain proactive steps and good practices you should follow to help ensure secrets are redacted, and to limit other risks associated with secrets: To help prevent accidental disclosure, {% data variables.product.product_name %} uses a mechanism that attempts to redact any secrets that appear in run logs. This redaction looks for exact matches of any configured secrets, as well as common encodings of the values, such as Base64. However, because there are multiple ways a secret value can be transformed, this redaction is not guaranteed. As a result, there are certain proactive steps and good practices you should follow to help ensure secrets are redacted, and to limit other risks associated with secrets:
- **Never use structured data as a secret** - **Never use structured data as a secret**
- Unstructured data can cause secret redaction within logs to fail, because redaction largely relies on finding an exact match for the specific secret value. For example, do not use a blob of JSON, XML, or YAML (or similar) to encapsulate a secret value, as this significantly reduces the probability the secrets will be properly redacted. Instead, create individual secrets for each sensitive value. - Unstructured data can cause secret redaction within logs to fail, because redaction largely relies on finding an exact match for the specific secret value. For example, do not use a blob of JSON, XML, or YAML (or similar) to encapsulate a secret value, as this significantly reduces the probability the secrets will be properly redacted. Instead, create individual secrets for each sensitive value.
@@ -43,7 +43,7 @@ To help prevent accidental disclosure, {{ site.data.variables.product.product_na
The individual jobs in a workflow can interact with (and compromise) other jobs. For example, a job querying the environment variables used by a later job, writing files to a shared directory that a later job processes, or even more directly by interacting with the Docker socket and inspecting other running containers and executing commands in them. The individual jobs in a workflow can interact with (and compromise) other jobs. For example, a job querying the environment variables used by a later job, writing files to a shared directory that a later job processes, or even more directly by interacting with the Docker socket and inspecting other running containers and executing commands in them.
This means that a compromise of a single action within a workflow can be very significant, as that compromised action would have access to all secrets configured on your repository, and can use the `GITHUB_TOKEN` to write to the repository. Consequently, there is significant risk in sourcing actions from third-party repositories on {{ site.data.variables.product.prodname_dotcom }}. You can help mitigate this risk by following these good practices: This means that a compromise of a single action within a workflow can be very significant, as that compromised action would have access to all secrets configured on your repository, and can use the `GITHUB_TOKEN` to write to the repository. Consequently, there is significant risk in sourcing actions from third-party repositories on {% data variables.product.prodname_dotcom %}. You can help mitigate this risk by following these good practices:
* **Pin actions to a full length commit SHA** * **Pin actions to a full length commit SHA**
@@ -60,13 +60,13 @@ This means that a compromise of a single action within a workflow can be very si
* **Pin actions to a tag only if you trust the creator** * **Pin actions to a tag only if you trust the creator**
Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and is widely used. If you’d like to specify a tag, then be sure that you trust the action's creators. The ‘Verified creator’ badge on {{ site.data.variables.product.prodname_marketplace }} is a useful signal, as it indicates that the action was written by a team whose identity has been verified by {{ site.data.variables.product.prodname_dotcom }}. Note that there is risk to this approach even if you trust the author, because a tag can be moved or deleted if a bad actor gains access to the repository storing the action. Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and is widely used. If you’d like to specify a tag, then be sure that you trust the action's creators. The ‘Verified creator’ badge on {% data variables.product.prodname_marketplace %} is a useful signal, as it indicates that the action was written by a team whose identity has been verified by {% data variables.product.prodname_dotcom %}. Note that there is risk to this approach even if you trust the author, because a tag can be moved or deleted if a bad actor gains access to the repository storing the action.
### Considering cross-repository access ### Considering cross-repository access
{{ site.data.variables.product.product_name }} is intentionally scoped for a single repository at a time. The `GITHUB_TOKEN` used in the workflow environment grants the same level of access as a write-access user, because any write-access user can access this token by creating or modifying workflow files. Users have specific permissions for each repository, so having the `GITHUB_TOKEN` for one repository grant access to another would impact the {{ site.data.variables.product.prodname_dotcom }} permission model if not implemented carefully. Similarly, caution must be taken when adding {{ site.data.variables.product.prodname_dotcom }} authentication tokens to the workflow environment, because this can also affect the {{ site.data.variables.product.prodname_dotcom }} permission model by inadvertently granting broad access to collaborators. {% data variables.product.product_name %} is intentionally scoped for a single repository at a time. The `GITHUB_TOKEN` used in the workflow environment grants the same level of access as a write-access user, because any write-access user can access this token by creating or modifying workflow files. Users have specific permissions for each repository, so having the `GITHUB_TOKEN` for one repository grant access to another would impact the {% data variables.product.prodname_dotcom %} permission model if not implemented carefully. Similarly, caution must be taken when adding {% data variables.product.prodname_dotcom %} authentication tokens to the workflow environment, because this can also affect the {% data variables.product.prodname_dotcom %} permission model by inadvertently granting broad access to collaborators.
We have [a plan on the {{ site.data.variables.product.prodname_dotcom }} roadmap](https://github.com/github/roadmap/issues/74) to support a flow that allows cross-repository access within {{ site.data.variables.product.product_name }}, but this is not yet a supported feature. Currently, the only way to perform privileged cross-repository interactions is to place a {{ site.data.variables.product.prodname_dotcom }} authentication token or SSH key as a secret within the workflow environment. Because many authentication token types do not allow for granular access to specific resources, there is significant risk in using the wrong token type, as it can grant much broader access than intended. We have [a plan on the {% data variables.product.prodname_dotcom %} roadmap](https://github.com/github/roadmap/issues/74) to support a flow that allows cross-repository access within {% data variables.product.product_name %}, but this is not yet a supported feature. Currently, the only way to perform privileged cross-repository interactions is to place a {% data variables.product.prodname_dotcom %} authentication token or SSH key as a secret within the workflow environment. Because many authentication token types do not allow for granular access to specific resources, there is significant risk in using the wrong token type, as it can grant much broader access than intended.
This list describes the recommended approaches for accessing repository data within a workflow, in descending order of preference: This list describes the recommended approaches for accessing repository data within a workflow, in descending order of preference:
@@ -76,8 +76,8 @@ This list describes the recommended approaches for accessing repository data wit
2. **Repository deploy key** 2. **Repository deploy key**
- Deploy keys are one of the only credential types that grant read or write access to a single repository, and can be used to interact with another repository within a workflow. For more information, see "[Managing deploy keys](/developers/overview/managing-deploy-keys#deploy-keys)." - Deploy keys are one of the only credential types that grant read or write access to a single repository, and can be used to interact with another repository within a workflow. For more information, see "[Managing deploy keys](/developers/overview/managing-deploy-keys#deploy-keys)."
- Note that deploy keys can only clone and push to the repository using Git, and cannot be used to interact with the REST or GraphQL API, so they may not be appropriate for your requirements. - Note that deploy keys can only clone and push to the repository using Git, and cannot be used to interact with the REST or GraphQL API, so they may not be appropriate for your requirements.
3. **{{ site.data.variables.product.prodname_github_app }} tokens** 3. **{% data variables.product.prodname_github_app %} tokens**
- {{ site.data.variables.product.prodname_github_apps }} can be installed on select repositories, and even have granular permissions on the resources within them. You could create a {{ site.data.variables.product.prodname_github_app }} internal to your organization, install it on the repositories you need access to within your workflow, and authenticate as the installation within your workflow to access those repositories. - {% data variables.product.prodname_github_apps %} can be installed on select repositories, and even have granular permissions on the resources within them. You could create a {% data variables.product.prodname_github_app %} internal to your organization, install it on the repositories you need access to within your workflow, and authenticate as the installation within your workflow to access those repositories.
4. **Personal access tokens** 4. **Personal access tokens**
- You should never use personal access tokens from your own account. These tokens grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your user account. This indirectly grants broad access to all write-access users of the repository the workflow is in. In addition, if you later leave an organization, workflows using this token will immediately break, and debugging this issue can be challenging. - You should never use personal access tokens from your own account. These tokens grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your user account. This indirectly grants broad access to all write-access users of the repository the workflow is in. In addition, if you later leave an organization, workflows using this token will immediately break, and debugging this issue can be challenging.
- If a personal access token is used, it should be one that was generated for a new account that is only granted access to the specific repositories that are needed for the workflow. Note that this approach is not scalable and should be avoided in favor of alternatives, such as deploy keys. - If a personal access token is used, it should be one that was generated for a new account that is only granted access to the specific repositories that are needed for the workflow. Note that this approach is not scalable and should be avoided in favor of alternatives, such as deploy keys.
@@ -86,11 +86,11 @@ This list describes the recommended approaches for accessing repository data wit
### Hardening for self-hosted runners ### Hardening for self-hosted runners
**{{ site.data.variables.product.prodname_dotcom }}-hosted** runners execute code within ephemeral and clean isolated virtual machines, meaning there is no way to persistently compromise this environment, or otherwise gain access to more information than was placed in this environment during the bootstrap process. **{% data variables.product.prodname_dotcom %}-hosted** runners execute code within ephemeral and clean isolated virtual machines, meaning there is no way to persistently compromise this environment, or otherwise gain access to more information than was placed in this environment during the bootstrap process.
**Self-hosted** runners on {{ site.data.variables.product.product_name }} do not have guarantees around running in ephemeral clean virtual machines, and can be persistently compromised by untrusted code in a workflow. **Self-hosted** runners on {% data variables.product.product_name %} do not have guarantees around running in ephemeral clean virtual machines, and can be persistently compromised by untrusted code in a workflow.
As a result, self-hosted runners should almost [never be used for public repositories](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories) on {{ site.data.variables.product.product_name }}, because any user can open pull requests against the repository and compromise the environment. Similarly, be cautious when using self-hosted runners on private repositories, as anyone who can fork the repository and open a PR (generally those with read-access to the repository) are able to compromise the self-hosted runner environment, including gaining access to secrets and the more privileged `GITHUB_TOKEN` which grants write-access permissions on the repository. As a result, self-hosted runners should almost [never be used for public repositories](/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories) on {% data variables.product.product_name %}, because any user can open pull requests against the repository and compromise the environment. Similarly, be cautious when using self-hosted runners on private repositories, as anyone who can fork the repository and open a PR (generally those with read-access to the repository) are able to compromise the self-hosted runner environment, including gaining access to secrets and the more privileged `GITHUB_TOKEN` which grants write-access permissions on the repository.
You should also consider the environment of the self-hosted runner machines: You should also consider the environment of the self-hosted runner machines:
- What sensitive information resides on the machine configured as a self-hosted runner? For example, private SSH keys, API access tokens, among others. - What sensitive information resides on the machine configured as a self-hosted runner? For example, private SSH keys, API access tokens, among others.

20
content/actions/learn-github-actions/sharing-workflows-with-your-organization.md
View File

@@ -9,12 +9,12 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Overview ### Overview
If you need to share workflows and other {{ site.data.variables.product.prodname_actions }} features with your team, then consider collaborating within a {{ site.data.variables.product.prodname_dotcom }} organization. An organization allows you to centrally store and and manage secrets, artifacts, and self-hosted runners. You can also create workflow templates in the `.github` repository and share them with other users in your organization. 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 and manage secrets, artifacts, and self-hosted runners. You can also create workflow templates in the `.github` repository and share them with other users in your organization.
### Creating a workflow template ### Creating a workflow template
@@ -79,8 +79,8 @@ To add another workflow template, add your files to the same `workflow-templates
This procedure demonstrates how a member of your organization can find and use a workflow template to create a new workflow. An organization's workflow templates can be used by anyone who is a member of the organization. This procedure demonstrates how a member of your organization can find and use a workflow template to create a new workflow. An organization's workflow templates can be used by anyone who is a member of the organization.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
1. If your repository already has existing workflows: In the upper-left corner, click **New workflow**. 1. If your repository already has existing workflows: In the upper-left corner, click **New workflow**.
![Create a new workflow](/assets/images/help/repository/actions-new-workflow.png) ![Create a new workflow](/assets/images/help/repository/actions-new-workflow.png)
1. Your organization's workflow templates are located in their own section titled "Workflows created by _organization name_". Under the name of the template you'd like to use, click **Set up this workflow**. 1. Your organization's workflow templates are located in their own section titled "Workflows created by _organization name_". Under the name of the template you'd like to use, click **Set up this workflow**.
@@ -93,11 +93,11 @@ You can centrally manage your secrets within an organization, and then make them
When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories. When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories.
{{ site.data.reusables.github-actions.permissions-statement-secrets-organization }} {% data reusables.github-actions.permissions-statement-secrets-organization %}
{{ site.data.reusables.organizations.navigate-to-org }} {% data reusables.organizations.navigate-to-org %}
{{ site.data.reusables.organizations.org_settings }} {% data reusables.organizations.org_settings %}
{{ site.data.reusables.github-actions.sidebar-secret }} {% data reusables.github-actions.sidebar-secret %}
1. Click **New secret**. 1. Click **New secret**.
1. Type a name for your secret in the **Name** input box. 1. Type a name for your secret in the **Name** input box.
1. Enter the **Value** for your secret. 1. Enter the **Value** for your secret.
@@ -113,4 +113,4 @@ For more information, see "[Managing access to self-hosted runners using groups]
### Next steps ### Next steps
To continue learning about {{ site.data.variables.product.prodname_actions }}, see "[Security hardening for {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions/security-hardening-for-github-actions)." To continue learning about {% data variables.product.prodname_actions %}, see "[Security hardening for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/security-hardening-for-github-actions)."

10
content/actions/managing-workflow-runs/adding-a-workflow-status-badge.md
View File

@@ -1,18 +1,18 @@
--- ---
title: Adding a workflow status badge title: Adding a workflow status badge
intro: You can display a status badge in your repository to indicate the status of your workflows. intro: You can display a status badge in your repository to indicate the status of your workflows.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{{ site.data.reusables.repositories.actions-workflow-status-badge-into }} {% data reusables.repositories.actions-workflow-status-badge-into %}
If your workflow uses the `name` keyword, you must reference the workflow by name. If the name of your workflow contains white space, you'll need to replace the space with the URL encoded string `%20`. For more information about the `name` keyword, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions#name)." If your workflow uses the `name` keyword, you must reference the workflow by name. If the name of your workflow contains white space, you'll need to replace the space with the URL encoded string `%20`. For more information about the `name` keyword, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#name)."
``` ```
https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

22
content/actions/managing-workflow-runs/canceling-a-workflow.md
View File

@@ -1,29 +1,29 @@
--- ---
title: Canceling a workflow title: Canceling a workflow
intro: 'You can cancel a workflow run that is in progress. When you cancel a workflow run, {{ site.data.variables.product.prodname_dotcom }} cancels all jobs and steps that are a part of that workflow.' intro: 'You can cancel a workflow run that is in progress. When you cancel a workflow run, {% data variables.product.prodname_dotcom %} cancels all jobs and steps that are a part of that workflow.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{{ site.data.reusables.repositories.permissions-statement-write }} {% data reusables.repositories.permissions-statement-write %}
### Canceling a workflow run ### Canceling a workflow run
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. In the upper-right corner of the workflow, click **Cancel workflow**. 1. In the upper-right corner of the workflow, click **Cancel workflow**.
![Cancel check suite button](/assets/images/help/repository/cancel-check-suite.png) ![Cancel check suite button](/assets/images/help/repository/cancel-check-suite.png)
### Steps {{ site.data.variables.product.prodname_dotcom }} takes to cancel a workflow run ### Steps {% data variables.product.prodname_dotcom %} takes to cancel a workflow run
When canceling workflow run, you may be running other software that uses resources that are related to the workflow run. To help you free up resources related to the workflow run, it may help to understand the steps {{ site.data.variables.product.prodname_dotcom }} performs to cancel a workflow run. When canceling workflow run, you may be running other software that uses resources that are related to the workflow run. To help you free up resources related to the workflow run, it may help to understand the steps {% data variables.product.prodname_dotcom %} performs to cancel a workflow run.
1. To cancel the workflow run, the server re-evaluates `if` conditions for all currently running jobs. If the condition evaluates to `true`, the job will not get canceled. For example, the condition `if: always()` would evaluate to true and the job continues to run. When there is no condition, that is the equivalent of the condition `if: success()`, which only runs if the previous step finished successfully. 1. To cancel the workflow run, the server re-evaluates `if` conditions for all currently running jobs. If the condition evaluates to `true`, the job will not get canceled. For example, the condition `if: always()` would evaluate to true and the job continues to run. When there is no condition, that is the equivalent of the condition `if: success()`, which only runs if the previous step finished successfully.
2. For jobs that need to be canceled, the server sends a cancellation message to all the runner machines with jobs that need to be canceled. 2. For jobs that need to be canceled, the server sends a cancellation message to all the runner machines with jobs that need to be canceled.

14
content/actions/managing-workflow-runs/deleting-a-workflow-run.md
View File

@@ -1,20 +1,20 @@
--- ---
title: Deleting a workflow run title: Deleting a workflow run
intro: 'You can delete a workflow run that has been completed, or is more than two weeks old.' intro: 'You can delete a workflow run that has been completed, or is more than two weeks old.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{{ site.data.reusables.repositories.permissions-statement-write }} {% data reusables.repositories.permissions-statement-write %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
1. To delete a workflow run, use the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, and select **Delete workflow run**. 1. To delete a workflow run, use the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, and select **Delete workflow run**.
![Deleting a workflow run](/assets/images/help/settings/workflow-delete-run.png) ![Deleting a workflow run](/assets/images/help/settings/workflow-delete-run.png)

16
content/actions/managing-workflow-runs/downloading-workflow-artifacts.md
View File

@@ -1,20 +1,20 @@
--- ---
title: Downloading workflow artifacts title: Downloading workflow artifacts
intro: You can download artifacts that were archived during a workflow run. Artifacts automatically expire after 90 days. intro: You can download artifacts that were archived during a workflow run. Artifacts automatically expire after 90 days.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{{ site.data.reusables.repositories.permissions-statement-read }} {% data reusables.repositories.permissions-statement-read %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. Under **Artifacts**, click the artifact you want to download. 1. Under **Artifacts**, click the artifact you want to download.
![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png) ![Download artifact drop-down menu](/assets/images/help/repository/artifact-drop-down.png)

12
content/actions/managing-workflow-runs/enabling-debug-logging.md
View File

@@ -1,20 +1,20 @@
--- ---
title: Enabling debug logging title: Enabling debug logging
intro: 'If the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging.' intro: 'If the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
These extra logs are enabled by setting secrets in the repository containing the workflow, so the same permissions requirements will apply: These extra logs are enabled by setting secrets in the repository containing the workflow, so the same permissions requirements will apply:
- {{ site.data.reusables.github-actions.permissions-statement-secrets-repository }} - {% data reusables.github-actions.permissions-statement-secrets-repository %}
- {{ site.data.reusables.github-actions.permissions-statement-secrets-organization }} - {% data reusables.github-actions.permissions-statement-secrets-organization %}
- {{ site.data.reusables.github-actions.permissions-statement-secrets-api }} - {% data reusables.github-actions.permissions-statement-secrets-api %}
For more information on setting secrets, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)." For more information on setting secrets, see "[Creating and using encrypted secrets](/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)."

4
content/actions/managing-workflow-runs/index.md
View File

@@ -15,8 +15,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{% link_in_list /viewing-workflow-run-history %} {% link_in_list /viewing-workflow-run-history %}
{% link_in_list /using-workflow-run-logs %} {% link_in_list /using-workflow-run-logs %}

18
content/actions/managing-workflow-runs/manually-running-a-workflow.md
View File

@@ -1,25 +1,25 @@
--- ---
title: Manually running a workflow title: Manually running a workflow
intro: 'When a workflow is configured to run on the `workflow_dispatch` event, you can run the workflow using the REST API or from the Actions tab on {{ site.data.variables.product.prodname_dotcom }}.' intro: 'When a workflow is configured to run on the `workflow_dispatch` event, you can run the workflow using the REST API or from the Actions tab on {% data variables.product.prodname_dotcom %}.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
To run a workflow manually, the workflow must be configured to run on the `workflow_dispatch` event. For more information, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows)." To run a workflow manually, the workflow must be configured to run on the `workflow_dispatch` event. For more information, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows)."
### Running a workflow on {{ site.data.variables.product.prodname_dotcom }} ### Running a workflow on {% data variables.product.prodname_dotcom %}
To trigger the `workflow_dispatch` event on {{ site.data.variables.product.prodname_dotcom }}, your workflow must be in the default branch. Follow these steps to manually trigger a workflow run. To trigger the `workflow_dispatch` event on {% data variables.product.prodname_dotcom %}, your workflow must be in the default branch. Follow these steps to manually trigger a workflow run.
{{ site.data.reusables.repositories.permissions-statement-read }} {% data reusables.repositories.permissions-statement-read %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
1. In the left sidebar, click the workflow you want to run. 1. In the left sidebar, click the workflow you want to run.
![actions select workflow](/assets/images/actions-select-workflow.png) ![actions select workflow](/assets/images/actions-select-workflow.png)
1. Above the list of workflow runs, select **Run workflow**. 1. Above the list of workflow runs, select **Run workflow**.

16
content/actions/managing-workflow-runs/re-running-a-workflow.md
View File

@@ -1,20 +1,20 @@
--- ---
title: Re-running a workflow title: Re-running a workflow
intro: You can re-run an instance of a workflow. Re-running a workflow uses the same `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) of the original event that triggered the workflow run. intro: You can re-run an instance of a workflow. Re-running a workflow uses the same `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) of the original event that triggered the workflow run.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{{ site.data.reusables.repositories.permissions-statement-read }} {% data reusables.repositories.permissions-statement-read %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**. 1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**.
![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down.png) ![Re-run checks drop-down menu](/assets/images/help/repository/rerun-checks-drop-down.png)

18
content/actions/managing-workflow-runs/removing-workflow-artifacts.md
View File

@@ -1,14 +1,14 @@
--- ---
title: Removing workflow artifacts title: Removing workflow artifacts
intro: 'Artifacts automatically expire after 90 days, but you can always reclaim used {{ site.data.variables.product.prodname_actions }} storage by deleting artifacts before they expire on {{ site.data.variables.product.product_name }}.' intro: 'Artifacts automatically expire after 90 days, but you can always reclaim used {% data variables.product.prodname_actions %} storage by deleting artifacts before they expire on {% data variables.product.product_name %}.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{% warning %} {% warning %}
@@ -16,11 +16,11 @@ versions:
{% endwarning %} {% endwarning %}
{{ site.data.reusables.repositories.permissions-statement-write }} {% data reusables.repositories.permissions-statement-write %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. Under **Artifacts**, click {% octicon "trashcan" aria-label="The trashcan icon" %} next to the artifact you want to remove. 1. Under **Artifacts**, click {% octicon "trashcan" aria-label="The trashcan icon" %} next to the artifact you want to remove.
![Delete artifact drop-down menu](/assets/images/help/repository/actions-delete-artifact.png) ![Delete artifact drop-down menu](/assets/images/help/repository/actions-delete-artifact.png)

62
content/actions/managing-workflow-runs/using-workflow-run-logs.md
View File

@@ -1,38 +1,38 @@
--- ---
title: Using workflow run logs title: Using workflow run logs
intro: 'You can view, search, and download the logs for each job in a workflow run. {{ site.data.variables.product.product_name }} stores full build logs and artifacts for 90 days.' intro: 'You can view, search, and download the logs for each job in a workflow run. {% data variables.product.product_name %} stores full build logs and artifacts for 90 days.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
You can see whether a workflow run is in progress or complete from the workflow run page. You must be logged in to a {{ site.data.variables.product.prodname_dotcom }} account to view workflow run information, including for public repositories. For more information, see "[Access permissions on GitHub](/articles/access-permissions-on-github)." You can see whether a workflow run is in progress or complete from the workflow run page. You must be logged in to a {% data variables.product.prodname_dotcom %} account to view workflow run information, including for public repositories. For more information, see "[Access permissions on GitHub](/articles/access-permissions-on-github)."
If the run is complete, you can see whether the result was a success, failure, canceled, or neutral. If the run failed, you can view and search the build logs to diagnose the failure and re-run the workflow. You can also view billable job execution minutes, or download logs and build artifacts. If the run is complete, you can see whether the result was a success, failure, canceled, or neutral. If the run failed, you can view and search the build logs to diagnose the failure and re-run the workflow. You can also view billable job execution minutes, or download logs and build artifacts.
![Annotated workflow run image](/assets/images/help/repository/annotated-workflow.png) ![Annotated workflow run image](/assets/images/help/repository/annotated-workflow.png)
{{ site.data.variables.product.prodname_actions }} use the Checks API to output statuses, results, and logs for a workflow. {{ site.data.variables.product.prodname_dotcom }} creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. {{ site.data.variables.product.prodname_actions }} are run as a step in a workflow. For more information about the Checks API, see "[Checks](/v3/checks/)." {% data variables.product.prodname_actions %} use the Checks API to output statuses, results, and logs for a workflow. {% data variables.product.prodname_dotcom %} creates a new check suite for each workflow run. The check suite contains a check run for each job in the workflow, and each job includes steps. {% data variables.product.prodname_actions %} are run as a step in a workflow. For more information about the Checks API, see "[Checks](/v3/checks/)."
{{ site.data.reusables.github-actions.invalid-workflow-files }} {% data reusables.github-actions.invalid-workflow-files %}
### Viewing logs to diagnose failures ### Viewing logs to diagnose failures
If your workflow run fails, you can see which step caused the failure and review the failed step's build logs to troubleshoot. You can see the time it took for each step to run. You can also copy a permalink to a specific line in the log file to share with your team. {{ site.data.reusables.repositories.permissions-statement-read }} If your workflow run fails, you can see which step caused the failure and review the failed step's build logs to troubleshoot. You can see the time it took for each step to run. You can also copy a permalink to a specific line in the log file to share with your team. {% data reusables.repositories.permissions-statement-read %}
In addition to the steps configured in the workflow file, {{ site.data.variables.product.prodname_dotcom }} adds two additional steps to each job to set up and complete the job's execution. These steps are logged in the workflow run with the names "Set up job" and "Complete job". In addition to the steps configured in the workflow file, {% data variables.product.prodname_dotcom %} adds two additional steps to each job to set up and complete the job's execution. These steps are logged in the workflow run with the names "Set up job" and "Complete job".
For jobs run on {{ site.data.variables.product.prodname_dotcom }}-hosted runners, "Set up job" records details of the runner's virtual environment, and includes a link to the list of preinstalled tools that were present on the runner machine. For jobs run on {% data variables.product.prodname_dotcom %}-hosted runners, "Set up job" records details of the runner's virtual environment, and includes a link to the list of preinstalled tools that were present on the runner machine.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
{{ site.data.reusables.repositories.navigate-to-job }} {% data reusables.repositories.navigate-to-job %}
6. To expand the log for a failed step, click the step. 6. To expand the log for a failed step, click the step.
![Failed step name](/assets/images/help/repository/failed-check-step.png) ![Failed step name](/assets/images/help/repository/failed-check-step.png)
7. Optionally, to get a link to a specific line in the logs, click on the step's line number. You can copy the link from the address bar of your web browser. 7. Optionally, to get a link to a specific line in the logs, click on the step's line number. You can copy the link from the address bar of your web browser.
@@ -40,13 +40,13 @@ For jobs run on {{ site.data.variables.product.prodname_dotcom }}-hosted runners
### Searching logs ### Searching logs
You can search the build logs for a particular step. When you search logs, only expanded steps are included in the results. {{ site.data.reusables.repositories.permissions-statement-read }} You can search the build logs for a particular step. When you search logs, only expanded steps are included in the results. {% data reusables.repositories.permissions-statement-read %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
{{ site.data.reusables.repositories.navigate-to-job }} {% data reusables.repositories.navigate-to-job %}
6. To expand each step you want to include in your search, click the step. 6. To expand each step you want to include in your search, click the step.
![Step name](/assets/images/help/repository/failed-check-step.png) ![Step name](/assets/images/help/repository/failed-check-step.png)
7. In the upper-right corner of the log output, in the **Search logs** search box, type a search query. 7. In the upper-right corner of the log output, in the **Search logs** search box, type a search query.
@@ -54,12 +54,12 @@ You can search the build logs for a particular step. When you search logs, only
### Downloading logs ### Downloading logs
You can download the log files from your workflow run. You can also download a workflow's artifacts. For more information, see "[Persisting workflow data using artifacts](/actions/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)." {{ site.data.reusables.repositories.permissions-statement-read }} You can download the log files from your workflow run. You can also download a workflow's artifacts. For more information, see "[Persisting workflow data using artifacts](/actions/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts)." {% data reusables.repositories.permissions-statement-read %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. In the left sidebar, select any job. 1. In the left sidebar, select any job.
![Select a workflow job](/assets/images/help/repository/workflow-job.png) ![Select a workflow job](/assets/images/help/repository/workflow-job.png)
2. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} and select **Download log archive**. 2. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} and select **Download log archive**.
@@ -67,12 +67,12 @@ You can download the log files from your workflow run. You can also download a w
### Deleting logs ### Deleting logs
You can delete the log files from your workflow run. {{ site.data.reusables.repositories.permissions-statement-write }} You can delete the log files from your workflow run. {% data reusables.repositories.permissions-statement-write %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}. 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}.
![Kebab-horizontal icon](/assets/images/help/repository/workflow-run-kebab-horizontal-icon.png) ![Kebab-horizontal icon](/assets/images/help/repository/workflow-run-kebab-horizontal-icon.png)
2. To delete the log files, click the **Delete all logs** button and review the confirmation prompt. 2. To delete the log files, click the **Delete all logs** button and review the confirmation prompt.

18
content/actions/managing-workflow-runs/viewing-job-execution-time.md
View File

@@ -1,25 +1,25 @@
--- ---
title: Viewing job execution time title: Viewing job execution time
intro: 'You can view the execution time of a job, including the billable minutes that a job accrued.' intro: 'You can view the execution time of a job, including the billable minutes that a job accrued.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
Billable job execution minutes are only shown for jobs run on private repositories that use {{ site.data.variables.product.prodname_dotcom }}-hosted runners. There are no billable minutes when using {{ site.data.variables.product.prodname_actions }} in public repositories or for jobs run on self-hosted runners. Billable job execution minutes are only shown for jobs run on private repositories that use {% data variables.product.prodname_dotcom %}-hosted runners. There are no billable minutes when using {% data variables.product.prodname_actions %} in public repositories or for jobs run on self-hosted runners.
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}
1. Under the job summary, you can view the job's execution time. To view the billable job execution time, click **Run and billable time details**. 1. Under the job summary, you can view the job's execution time. To view the billable job execution time, click **Run and billable time details**.
![Run and billable time details link](/assets/images/help/repository/view-run-billable-time.png) ![Run and billable time details link](/assets/images/help/repository/view-run-billable-time.png)
{% note %} {% note %}
**Note:** The billable time shown does not include any rounding or minute multipliers. To view your total {{ site.data.variables.product.prodname_actions }} usage, including rounding and minute multipliers, see "[Viewing your {{ site.data.variables.product.prodname_actions }} usage](/github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-github-actions-usage)." **Note:** The billable time shown does not include any rounding or minute multipliers. To view your total {% data variables.product.prodname_actions %} usage, including rounding and minute multipliers, see "[Viewing your {% data variables.product.prodname_actions %} usage](/github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-github-actions-usage)."
{% endnote %} {% endnote %}

16
content/actions/managing-workflow-runs/viewing-workflow-run-history.md
View File

@@ -1,18 +1,18 @@
--- ---
title: Viewing workflow run history title: Viewing workflow run history
intro: You can view logs for each run of a workflow. Logs include the status for each job and step in a workflow. intro: You can view logs for each run of a workflow. Logs include the status for each job and step in a workflow.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
versions: versions:
free-pro-team: '*' free-pro-team: '*'
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
{{ site.data.reusables.repositories.permissions-statement-read }} {% data reusables.repositories.permissions-statement-read %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
{{ site.data.reusables.repositories.navigate-to-workflow }} {% data reusables.repositories.navigate-to-workflow %}
{{ site.data.reusables.repositories.view-run }} {% data reusables.repositories.view-run %}

18
content/actions/quickstart.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Quickstart for GitHub Actions title: Quickstart for GitHub Actions
intro: 'Add a {{ site.data.variables.product.prodname_actions }} workflow to an existing repository in 5 minutes or less.' intro: 'Add a {% data variables.product.prodname_actions %} workflow to an existing repository in 5 minutes or less.'
allowTitleToDifferFromFilename: true allowTitleToDifferFromFilename: true
redirect_from: redirect_from:
- /actions/getting-started-with-github-actions/starting-with-preconfigured-workflow-templates - /actions/getting-started-with-github-actions/starting-with-preconfigured-workflow-templates
@@ -9,16 +9,16 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Introduction ### Introduction
You only need an existing {{ site.data.variables.product.prodname_dotcom }} repository to create and run a {{ site.data.variables.product.prodname_actions }} workflow. In this guide, you'll add a workflow that lints multiple coding languages using the [{{ site.data.variables.product.prodname_dotcom }} Super-Linter action](https://github.com/github/super-linter). The workflow uses Super-Linter to validate your source code every time a new commit is pushed to your repository. You only need an existing {% data variables.product.prodname_dotcom %} repository to create and run a {% data variables.product.prodname_actions %} workflow. In this guide, you'll add a workflow that lints multiple coding languages using the [{% data variables.product.prodname_dotcom %} Super-Linter action](https://github.com/github/super-linter). The workflow uses Super-Linter to validate your source code every time a new commit is pushed to your repository.
### Creating your first workflow ### Creating your first workflow
1. From your repository on {{ site.data.variables.product.prodname_dotcom }}, create a new file in the `.github/workflows` directory named `superlinter.yml`. For more information, see "[Creating new files](/github/managing-files-in-a-repository/creating-new-files)." 1. From your repository on {% data variables.product.prodname_dotcom %}, create a new file in the `.github/workflows` directory named `superlinter.yml`. For more information, see "[Creating new files](/github/managing-files-in-a-repository/creating-new-files)."
2. Copy the following YAML contents into the `superlinter.yml` file. **Note:** If your default branch is not `main`, update the value of `DEFAULT_BRANCH` to match your repository's default branch name. 2. Copy the following YAML contents into the `superlinter.yml` file. **Note:** If your default branch is not `main`, update the value of `DEFAULT_BRANCH` to match your repository's default branch name.
{% raw %} {% raw %}
```yaml ```yaml
@@ -56,7 +56,7 @@ Committing the workflow file in your repository triggers the `push` event and ru
### Viewing your workflow results ### Viewing your workflow results
{{ site.data.reusables.repositories.actions-tab }} {% data reusables.repositories.actions-tab %}
1. In the left sidebar, click the workflow you want to see. 1. In the left sidebar, click the workflow you want to see.
![Workflow list in left sidebar](/assets/images/help/repository/superlinter-workflow-sidebar.png) ![Workflow list in left sidebar](/assets/images/help/repository/superlinter-workflow-sidebar.png)
1. From the list of workflow runs, click the name of the run you want to see. 1. From the list of workflow runs, click the name of the run you want to see.
@@ -68,12 +68,12 @@ Committing the workflow file in your repository triggers the `push` event and ru
### More starter workflows ### More starter workflows
{{ site.data.variables.product.prodname_dotcom }} provides preconfigured workflow templates that you can start from to automate or create a continuous integration workflows. You can browse the full list of workflow templates in the {% if currentVersion == "free-pro-team@latest" %}[actions/starter-workflows](https://github.com/actions/starter-workflows) repository{% else %} `actions/starter-workflows` repository on {{ site.data.variables.product.product_location }}{% endif %}. {% data variables.product.prodname_dotcom %} provides preconfigured workflow templates that you can start from to automate or create a continuous integration workflows. You can browse the full list of workflow templates in the {% if currentVersion == "free-pro-team@latest" %}[actions/starter-workflows](https://github.com/actions/starter-workflows) repository{% else %} `actions/starter-workflows` repository on {% data variables.product.product_location %}{% endif %}.
### Next steps ### Next steps
The super-linter workflow you just added runs any time code is pushed to your repository to help you spot errors and inconsistencies in your code. But, this is only the beginning of what you can do with {{ site.data.variables.product.prodname_actions }}. Your repository can contain multiple workflows that trigger different jobs based on different events. {{ site.data.variables.product.prodname_actions }} can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with {{ site.data.variables.product.prodname_actions }}: The super-linter workflow you just added runs any time code is pushed to your repository to help you spot errors and inconsistencies in your code. But, this is only the beginning of what you can do with {% data variables.product.prodname_actions %}. Your repository can contain multiple workflows that trigger different jobs based on different events. {% data variables.product.prodname_actions %} can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with {% data variables.product.prodname_actions %}:
- "[Learn {{ site.data.variables.product.prodname_actions }}](/actions/learn-github-actions)" for an in-depth tutorial - "[Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)" for an in-depth tutorial
- "[Guides](/actions/guides)" for specific uses cases and examples - "[Guides](/actions/guides)" for specific uses cases and examples
- [github/super-linter](https://github.com/github/super-linter) for more details about configuring the Super-Linter action - [github/super-linter](https://github.com/github/super-linter) for more details about configuring the Super-Linter action

24
content/actions/reference/authentication-in-a-workflow.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Authentication in a workflow title: Authentication in a workflow
intro: '{{ site.data.variables.product.prodname_dotcom }} provides a token that you can use to authenticate on behalf of {{ site.data.variables.product.prodname_actions }}.' intro: '{% data variables.product.prodname_dotcom %} provides a token that you can use to authenticate on behalf of {% data variables.product.prodname_actions %}.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/authenticating-with-the-github_token - /github/automating-your-workflow-with-github-actions/authenticating-with-the-github_token
- /actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token - /actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token
@@ -11,26 +11,26 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
Anyone with `write` access to a repository can create, read, and use secrets. Anyone with `write` access to a repository can create, read, and use secrets.
### About the `GITHUB_TOKEN` secret ### About the `GITHUB_TOKEN` secret
{{ site.data.variables.product.prodname_dotcom }} automatically creates a `GITHUB_TOKEN` secret to use in your workflow. You can use the `GITHUB_TOKEN` to authenticate in a workflow run. {% data variables.product.prodname_dotcom %} automatically creates a `GITHUB_TOKEN` secret to use in your workflow. You can use the `GITHUB_TOKEN` to authenticate in a workflow run.
When you enable {{ site.data.variables.product.prodname_actions }}, {{ site.data.variables.product.prodname_dotcom }} installs a {{ site.data.variables.product.prodname_github_app }} on your repository. The `GITHUB_TOKEN` secret is a {{ site.data.variables.product.prodname_github_app }} installation access token. You can use the installation access token to authenticate on behalf of the {{ site.data.variables.product.prodname_github_app }} installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see "[Permissions for the `GITHUB_TOKEN`](#permissions-for-the-github_token)." When you enable {% data variables.product.prodname_actions %}, {% data variables.product.prodname_dotcom %} installs a {% data variables.product.prodname_github_app %} on your repository. The `GITHUB_TOKEN` secret is a {% data variables.product.prodname_github_app %} installation access token. You can use the installation access token to authenticate on behalf of the {% data variables.product.prodname_github_app %} installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see "[Permissions for the `GITHUB_TOKEN`](#permissions-for-the-github_token)."
Before each job begins, {{ site.data.variables.product.prodname_dotcom }} fetches an installation access token for the job. The token expires when the job is finished. Before each job begins, {% data variables.product.prodname_dotcom %} fetches an installation access token for the job. The token expires when the job is finished.
The token is also available in the `github.token` context. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)." The token is also available in the `github.token` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)."
### Using the `GITHUB_TOKEN` in a workflow ### Using the `GITHUB_TOKEN` in a workflow
To use the `GITHUB_TOKEN` secret, you must reference it in your workflow file. Using a token might include passing the token as an input to an action that requires it, or making authenticated {{ site.data.variables.product.prodname_dotcom }} API calls. To use the `GITHUB_TOKEN` secret, you must reference it in your workflow file. Using a token might include passing the token as an input to an action that requires it, or making authenticated {% data variables.product.prodname_dotcom %} API calls.
{{ site.data.reusables.github-actions.actions-do-not-trigger-workflows }} {% data reusables.github-actions.actions-do-not-trigger-workflows %}
#### Example passing `GITHUB_TOKEN` as an input #### Example passing `GITHUB_TOKEN` as an input
@@ -53,7 +53,7 @@ This example workflow uses the [labeler action](https://github.com/actions/label
#### Example calling the REST API #### Example calling the REST API
You can use the `GITHUB_TOKEN` to make authenticated API calls. This example workflow creates an issue using the {{ site.data.variables.product.prodname_dotcom }} REST API: You can use the `GITHUB_TOKEN` to make authenticated API calls. This example workflow creates an issue using the {% data variables.product.prodname_dotcom %} REST API:
{% raw %} {% raw %}
```yaml ```yaml
@@ -79,7 +79,7 @@ You can use the `GITHUB_TOKEN` to make authenticated API calls. This example wor
### Permissions for the `GITHUB_TOKEN` ### Permissions for the `GITHUB_TOKEN`
For information about the API endpoints {{ site.data.variables.product.prodname_github_apps }} can access with each permission, see "[{{ site.data.variables.product.prodname_github_app }} Permissions](/v3/apps/permissions/)." For information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see "[{% data variables.product.prodname_github_app %} Permissions](/v3/apps/permissions/)."
| Permission | Access type | Access by forked repos | | Permission | Access type | Access by forked repos |
|------------|-------------|--------------------------| |------------|-------------|--------------------------|

44
content/actions/reference/context-and-expression-syntax-for-github-actions.md
View File

@@ -2,7 +2,7 @@
title: Context and expression syntax for GitHub Actions title: Context and expression syntax for GitHub Actions
shortTitle: Context and expression syntax shortTitle: Context and expression syntax
intro: You can access context information and evaluate expressions in workflows and actions. intro: You can access context information and evaluate expressions in workflows and actions.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/contexts-and-expression-syntax-for-github-actions - /articles/contexts-and-expression-syntax-for-github-actions
- /github/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions - /github/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions
@@ -13,8 +13,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About contexts and expressions ### About contexts and expressions
@@ -22,13 +22,13 @@ You can use expressions to programmatically set variables in workflow files and
Expressions are commonly used with the conditional `if` keyword in a workflow file to determine whether a step should run. When an `if` conditional is `true`, the step will run. Expressions are commonly used with the conditional `if` keyword in a workflow file to determine whether a step should run. When an `if` conditional is `true`, the step will run.
You need to use specific syntax to tell {{ site.data.variables.product.prodname_dotcom }} to evaluate an expression rather than treat it as a string. You need to use specific syntax to tell {% data variables.product.prodname_dotcom %} to evaluate an expression rather than treat it as a string.
{% raw %} {% raw %}
`${{ <expression> }}` `${{ <expression> }}`
{% endraw %} {% endraw %}
{{ site.data.reusables.github-actions.expression-syntax-if }} For more information about `if` conditionals, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions/#jobsjob_idif)." {% data reusables.github-actions.expression-syntax-if %} For more information about `if` conditionals, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions/#jobsjob_idif)."
#### Example expression in an `if` conditional #### Example expression in an `if` conditional
@@ -79,7 +79,7 @@ In order to use property dereference syntax, the property name must:
The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)." The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)."
{{ site.data.reusables.github-actions.github-context-warning }} {% data reusables.github-actions.github-context-warning %}
| Property name | Type | Description | | Property name | Type | Description |
|---------------|------|-------------| |---------------|------|-------------|
@@ -88,8 +88,8 @@ The `github` context contains information about the workflow run and the event t
| `github.event_path` | `string` | The path to the full event webhook payload on the runner. | | `github.event_path` | `string` | The path to the full event webhook payload on the runner. |
| `github.workflow` | `string` | The name of the workflow. If the workflow file doesn't specify a `name`, the value of this property is the full path of the workflow file in the repository. | | `github.workflow` | `string` | The name of the workflow. If the workflow file doesn't specify a `name`, the value of this property is the full path of the workflow file in the repository. |
| `github.job` | `string` | The [`job_id`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_id) of the current job. | | `github.job` | `string` | The [`job_id`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_id) of the current job. |
| `github.run_id` | `string` | {{ site.data.reusables.github-actions.run_id_description }} | | `github.run_id` | `string` | {% data reusables.github-actions.run_id_description %} |
| `github.run_number` | `string` | {{ site.data.reusables.github-actions.run_number_description }} | | `github.run_number` | `string` | {% data reusables.github-actions.run_number_description %} |
| `github.actor` | `string` | The login of the user that initiated the workflow run. | | `github.actor` | `string` | The login of the user that initiated the workflow run. |
| `github.repository` | `string` | The owner and repository name. For example, `Codertocat/Hello-World`. | | `github.repository` | `string` | The owner and repository name. For example, `Codertocat/Hello-World`. |
| `github.repository_owner` | `string` | The repository owner's name. For example, `Codertocat`. | | `github.repository_owner` | `string` | The repository owner's name. For example, `Codertocat`. |
@@ -100,16 +100,16 @@ The `github` context contains information about the workflow run and the event t
| `github.base_ref` | `string` | The `base_ref` or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is a `pull_request`. | | `github.base_ref` | `string` | The `base_ref` or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is a `pull_request`. |
| `github.token` | `string` | A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the `GITHUB_TOKEN` secret. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)." | | `github.token` | `string` | A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the `GITHUB_TOKEN` secret. For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token)." |
| `github.workspace` | `string` | The default working directory for steps and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. | | `github.workspace` | `string` | The default working directory for steps and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. |
| `github.action` | `string` | The name of the action currently running. {{ site.data.variables.product.prodname_dotcom }} removes special characters or uses the name `run` when the current step runs a script. If you use the same action more than once in the same job, the name will include a suffix with the sequence number. For example, the first script you run will have the name `run1`, and the second script will be named `run2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. | | `github.action` | `string` | The name of the action currently running. {% data variables.product.prodname_dotcom %} removes special characters or uses the name `run` when the current step runs a script. If you use the same action more than once in the same job, the name will include a suffix with the sequence number. For example, the first script you run will have the name `run1`, and the second script will be named `run2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. |
| `github.action_path` | `string` | The path where your action is located. You can use this path to easily access files located in the same repository as your action. This attribute is only supported in composite run steps actions. | `github.action_path` | `string` | The path where your action is located. You can use this path to easily access files located in the same repository as your action. This attribute is only supported in composite run steps actions.
#### **`env` context** #### **`env` context**
The `env` context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env)." The `env` context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env)."
The `env` context syntax allows you to use the value of an environment variable in your workflow file. If you want to use the value of an environment variable inside a runner, use the runner operating system's normal method for reading environment variables. The `env` context syntax allows you to use the value of an environment variable in your workflow file. If you want to use the value of an environment variable inside a runner, use the runner operating system's normal method for reading environment variables.
You can only use the `env` context in the value of the `with` and `name` keys, or in a step's `if` conditional. For more information on the step syntax, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps)." You can only use the `env` context in the value of the `with` and `name` keys, or in a step's `if` conditional. For more information on the step syntax, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps)."
| Property name | Type | Description | | Property name | Type | Description |
|---------------|------|-------------| |---------------|------|-------------|
@@ -125,10 +125,10 @@ The `job` context contains information about the currently running job.
|---------------|------|-------------| |---------------|------|-------------|
| `job` | `object` | This context changes for each job in a workflow run. You can access this context from any step in a job. | | `job` | `object` | This context changes for each job in a workflow run. You can access this context from any step in a job. |
| `job.status` | `string` | The current status of the job. Possible values are `success`, `failure`, or `cancelled`. | | `job.status` | `string` | The current status of the job. Possible values are `success`, `failure`, or `cancelled`. |
| `job.container` | `object` | Information about the job's container. For more information about containers, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions#jobsjob_idcontainer)." | | `job.container` | `object` | Information about the job's container. For more information about containers, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#jobsjob_idcontainer)." |
| `job.container.network` | `string` | The id of the container network. The runner creates the network used by all containers in a job. | | `job.container.network` | `string` | The id of the container network. The runner creates the network used by all containers in a job. |
| `job.container.id` | `string` | The id of the container. | | `job.container.id` | `string` | The id of the container. |
| `job.services` | `object` | The service containers created for a job. For more information about service containers, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions#jobsjob_idservices)." | | `job.services` | `object` | The service containers created for a job. For more information about service containers, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#jobsjob_idservices)." |
| `job.services.<service id>.id` | `string` | The id of the service container. | | `job.services.<service id>.id` | `string` | The id of the service container. |
| `job.services.<service id>.ports` | `object` | The exposed ports of the service container. | | `job.services.<service id>.ports` | `object` | The exposed ports of the service container. |
| `job.services.<service id>.network` | `string` | The id of the service container network. The runner creates the network used by all containers in a job. | | `job.services.<service id>.network` | `string` | The id of the service container network. The runner creates the network used by all containers in a job. |
@@ -140,7 +140,7 @@ The `steps` context contains information about the steps in the current job that
| Property name | Type | Description | | Property name | Type | Description |
|---------------|------|-------------| |---------------|------|-------------|
| `steps` | `object` | This context changes for each step in a job. You can access this context from any step in a job. | | `steps` | `object` | This context changes for each step in a job. You can access this context from any step in a job. |
| `steps.<step id>.outputs` | `object` | The set of outputs defined for the step. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/articles/metadata-syntax-for-github-actions#outputs)." | | `steps.<step id>.outputs` | `object` | The set of outputs defined for the step. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/articles/metadata-syntax-for-github-actions#outputs)." |
| `steps.<step id>.outputs.<output name>` | `string` | The value of a specific output. | | `steps.<step id>.outputs.<output name>` | `string` | The value of a specific output. |
| `steps.<step id>.outcome` | `string` | The result of a completed step before [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. | | `steps.<step id>.outcome` | `string` | The result of a completed step before [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. |
| `steps.<step id>.conclusion` | `string` | The result of a completed step after [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. | | `steps.<step id>.conclusion` | `string` | The result of a completed step after [`continue-on-error`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error) is applied. Possible values are `success`, `failure`, `cancelled`, or `skipped`. When a `continue-on-error` step fails, the `outcome` is `failure`, but the final `conclusion` is `success`. |
@@ -153,11 +153,11 @@ The `runner` context contains information about the runner that is executing the
|---------------|------|-------------| |---------------|------|-------------|
| `runner.os` | `string` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. | | `runner.os` | `string` | The operating system of the runner executing the job. Possible values are `Linux`, `Windows`, or `macOS`. |
| `runner.temp` | `string` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. | | `runner.temp` | `string` | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. |
| `runner.tool_cache` | `string` | The path of the directory containing some of the preinstalled tools for {{ site.data.variables.product.prodname_dotcom }}-hosted runners. For more information, see "[Specifications for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". | | `runner.tool_cache` | `string` | The path of the directory containing some of the preinstalled tools for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see "[Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/reference/specifications-for-github-hosted-runners/#supported-software)". |
#### **`needs` context** #### **`needs` context**
The `needs` context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)." The `needs` context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)."
| Property name | Type | Description | | Property name | Type | Description |
|---------------|------|-------------| |---------------|------|-------------|
@@ -170,7 +170,7 @@ The `needs` context contains outputs from all jobs that are defined as a depende
To inspect the information that is accessible in each context, you can use this workflow file example. To inspect the information that is accessible in each context, you can use this workflow file example.
{{ site.data.reusables.github-actions.github-context-warning }} {% data reusables.github-actions.github-context-warning %}
**.github/workflows/main.yml** **.github/workflows/main.yml**
{% raw %} {% raw %}
@@ -252,9 +252,9 @@ env:
| `&&` | And | | `&&` | And |
| <code>\|\|</code> | Or | | <code>\|\|</code> | Or |
{{ site.data.variables.product.prodname_dotcom }} performs loose equality comparisons. {% data variables.product.prodname_dotcom %} performs loose equality comparisons.
* If the types do not match, {{ site.data.variables.product.prodname_dotcom }} coerces the type to a number. {{ site.data.variables.product.prodname_dotcom }} casts data types to a number using these conversions: * If the types do not match, {% data variables.product.prodname_dotcom %} coerces the type to a number. {% data variables.product.prodname_dotcom %} casts data types to a number using these conversions:
| Type | Result | | Type | Result |
| --- | --- | | --- | --- |
@@ -264,12 +264,12 @@ env:
| Array | `NaN` | | Array | `NaN` |
| Object | `NaN` | | Object | `NaN` |
* A comparison of one `NaN` to another `NaN` does not result in `true`. For more information, see the "[NaN Mozilla docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN)." * A comparison of one `NaN` to another `NaN` does not result in `true`. For more information, see the "[NaN Mozilla docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN)."
* {{ site.data.variables.product.prodname_dotcom }} ignores case when comparing strings. * {% data variables.product.prodname_dotcom %} ignores case when comparing strings.
* Objects and arrays are only considered equal when they are the same instance. * Objects and arrays are only considered equal when they are the same instance.
### Functions ### Functions
{{ site.data.variables.product.prodname_dotcom }} offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons. {{ site.data.variables.product.prodname_dotcom }} casts data types to a string using these conversions: {% data variables.product.prodname_dotcom %} offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons. {% data variables.product.prodname_dotcom %} casts data types to a string using these conversions:
| Type | Result | | Type | Result |
| --- | --- | | --- | --- |
@@ -393,7 +393,7 @@ jobs:
Returns a single hash for the set of files that matches the `path` pattern. You can provide a single `path` pattern or multiple `path` patterns separated by commas. The `path` is relative to the `GITHUB_WORKSPACE` directory and can only include files inside of the `GITHUB_WORKSPACE`. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. For more information about SHA-256, see "[SHA-2](https://en.wikipedia.org/wiki/SHA-2)." Returns a single hash for the set of files that matches the `path` pattern. You can provide a single `path` pattern or multiple `path` patterns separated by commas. The `path` is relative to the `GITHUB_WORKSPACE` directory and can only include files inside of the `GITHUB_WORKSPACE`. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. For more information about SHA-256, see "[SHA-2](https://en.wikipedia.org/wiki/SHA-2)."
You can use pattern matching characters to match file names. Pattern matching is case-insensitive on Windows. For more information about supported pattern matching characters, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions/#filter-pattern-cheat-sheet)." You can use pattern matching characters to match file names. Pattern matching is case-insensitive on Windows. For more information about supported pattern matching characters, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions/#filter-pattern-cheat-sheet)."
##### Example with a single pattern ##### Example with a single pattern

48
content/actions/reference/encrypted-secrets.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Encrypted secrets title: Encrypted secrets
intro: Encrypted secrets allow you to store sensitive information in your repository or organization. intro: Encrypted secrets allow you to store sensitive information in your repository or organization.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets - /github/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets
- /actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets - /actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets
@@ -11,14 +11,14 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About encrypted secrets ### About encrypted secrets
Secrets are encrypted environment variables that you create in a repository or organization. The secrets you create are available to use in {{ site.data.variables.product.prodname_actions }} workflows. {{ site.data.variables.product.prodname_dotcom }} uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) to help ensure that secrets are encrypted before they reach {{ site.data.variables.product.prodname_dotcom }}, and remain encrypted until you use them in a workflow. Secrets are encrypted environment variables that you create in a repository or organization. The secrets you create are available to use in {% data variables.product.prodname_actions %} workflows. {% data variables.product.prodname_dotcom %} uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) to help ensure that secrets are encrypted before they reach {% data variables.product.prodname_dotcom %}, and remain encrypted until you use them in a workflow.
{{ site.data.reusables.github-actions.secrets-org-level-overview }} {% data reusables.github-actions.secrets-org-level-overview %}
#### Naming your secrets #### Naming your secrets
@@ -29,17 +29,17 @@ The following rules apply to secret names:
* Secret names must not start with a number. * Secret names must not start with a number.
* Secret names must be unique at the level they are created at. For example, a secret created at the organization-level must have a unique name at that level, and a secret created at the repository-level must have a unique name in that repository. If an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence. * Secret names must be unique at the level they are created at. For example, a secret created at the organization-level must have a unique name at that level, and a secret created at the repository-level must have a unique name in that repository. If an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence.
To help ensure that {{ site.data.variables.product.prodname_dotcom }} redacts your secret in logs, avoid using structured data as the values of secrets. For example, avoid creating secrets that contain JSON or encoded Git blobs. To help ensure that {% data variables.product.prodname_dotcom %} redacts your secret in logs, avoid using structured data as the values of secrets. For example, avoid creating secrets that contain JSON or encoded Git blobs.
#### Accessing your secrets #### Accessing your secrets
To make a secret available to an action, you must set the secret as an input or environment variable in the workflow file. Review the action's README file to learn about which inputs and environment variables the action expects. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepsenv)." To make a secret available to an action, you must set the secret as an input or environment variable in the workflow file. Review the action's README file to learn about which inputs and environment variables the action expects. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepsenv)."
You can use and read encrypted secrets in a workflow file if you have access to edit the file. For more information, see "[Access permissions on {{ site.data.variables.product.prodname_dotcom }}](/github/getting-started-with-github/access-permissions-on-github)." You can use and read encrypted secrets in a workflow file if you have access to edit the file. For more information, see "[Access permissions on {% data variables.product.prodname_dotcom %}](/github/getting-started-with-github/access-permissions-on-github)."
{% warning %} {% warning %}
**Warning:** {{ site.data.variables.product.prodname_dotcom }} automatically redacts secrets printed to the log, but you should avoid printing secrets to the log intentionally. **Warning:** {% data variables.product.prodname_dotcom %} automatically redacts secrets printed to the log, but you should avoid printing secrets to the log intentionally.
{% endwarning %} {% endwarning %}
@@ -51,11 +51,11 @@ When generating credentials, we recommend that you grant the minimum permissions
### Creating encrypted secrets for a repository ### Creating encrypted secrets for a repository
{{ site.data.reusables.github-actions.permissions-statement-secrets-repository }} {% data reusables.github-actions.permissions-statement-secrets-repository %}
{{ site.data.reusables.repositories.navigate-to-repo }} {% data reusables.repositories.navigate-to-repo %}
{{ site.data.reusables.repositories.sidebar-settings }} {% data reusables.repositories.sidebar-settings %}
{{ site.data.reusables.github-actions.sidebar-secret }} {% data reusables.github-actions.sidebar-secret %}
1. Click **Add a new secret**. 1. Click **Add a new secret**.
1. Type a name for your secret in the **Name** input box. 1. Type a name for your secret in the **Name** input box.
1. Enter the value for your secret. 1. Enter the value for your secret.
@@ -67,11 +67,11 @@ If your repository can access secrets from the parent organization, then those s
When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories. When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories.
{{ site.data.reusables.github-actions.permissions-statement-secrets-organization }} {% data reusables.github-actions.permissions-statement-secrets-organization %}
{{ site.data.reusables.organizations.navigate-to-org }} {% data reusables.organizations.navigate-to-org %}
{{ site.data.reusables.organizations.org_settings }} {% data reusables.organizations.org_settings %}
{{ site.data.reusables.github-actions.sidebar-secret }} {% data reusables.github-actions.sidebar-secret %}
1. Click **New secret**. 1. Click **New secret**.
1. Type a name for your secret in the **Name** input box. 1. Type a name for your secret in the **Name** input box.
1. Enter the **Value** for your secret. 1. Enter the **Value** for your secret.
@@ -82,9 +82,9 @@ When creating a secret in an organization, you can use a policy to limit which r
You can check which access policies are being applied to a secret in your organization. You can check which access policies are being applied to a secret in your organization.
{{ site.data.reusables.organizations.navigate-to-org }} {% data reusables.organizations.navigate-to-org %}
{{ site.data.reusables.organizations.org_settings }} {% data reusables.organizations.org_settings %}
{{ site.data.reusables.github-actions.sidebar-secret }} {% data reusables.github-actions.sidebar-secret %}
1. The list of secrets includes any configured permissions and policies. For example: 1. The list of secrets includes any configured permissions and policies. For example:
![Secrets list](/assets/images/help/settings/actions-org-secrets-list.png) ![Secrets list](/assets/images/help/settings/actions-org-secrets-list.png)
1. For more details on the configured permissions for each secret, click **Update**. 1. For more details on the configured permissions for each secret, click **Update**.
@@ -93,7 +93,7 @@ You can check which access policies are being applied to a secret in your organi
With the exception of `GITHUB_TOKEN`, secrets are not passed to the runner when a workflow is triggered from a forked repository. With the exception of `GITHUB_TOKEN`, secrets are not passed to the runner when a workflow is triggered from a forked repository.
To provide an action with a secret as an input or environment variable, you can use the `secrets` context to access secrets you've created in your repository. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)" and "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)." To provide an action with a secret as an input or environment variable, you can use the `secrets` context to access secrets you've created in your repository. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)" and "[Workflow syntax for {% data variables.product.prodname_actions %}](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions)."
{% raw %} {% raw %}
```yaml ```yaml
@@ -153,11 +153,11 @@ steps:
Your workflow can have up to 100 secrets. The names of secret environment variables must be unique in a repository. Your workflow can have up to 100 secrets. The names of secret environment variables must be unique in a repository.
Secrets are limited to 64 KB in size. To use secrets that are larger than 64 KB, you can store encrypted secrets in your repository and save the decryption passphrase as a secret on {{ site.data.variables.product.prodname_dotcom }}. For example, you can use `gpg` to encrypt your credentials locally before checking the file in to your repository on {{ site.data.variables.product.prodname_dotcom }}. For more information, see the "[gpg manpage](https://www.gnupg.org/gph/de/manual/r1023.html)." Secrets are limited to 64 KB in size. To use secrets that are larger than 64 KB, you can store encrypted secrets in your repository and save the decryption passphrase as a secret on {% data variables.product.prodname_dotcom %}. For example, you can use `gpg` to encrypt your credentials locally before checking the file in to your repository on {% data variables.product.prodname_dotcom %}. For more information, see the "[gpg manpage](https://www.gnupg.org/gph/de/manual/r1023.html)."
{% warning %} {% warning %}
**Warning**: Be careful that your secrets do not get printed when your action runs. When using this workaround, {{ site.data.variables.product.prodname_dotcom }} does not redact secrets that are printed in logs. **Warning**: Be careful that your secrets do not get printed when your action runs. When using this workaround, {% data variables.product.prodname_dotcom %} does not redact secrets that are printed in logs.
{% endwarning %} {% endwarning %}
@@ -167,7 +167,7 @@ Secrets are limited to 64 KB in size. To use secrets that are larger than 64 KB,
$ gpg --symmetric --cipher-algo AES256 my_secret.json $ gpg --symmetric --cipher-algo AES256 my_secret.json
``` ```
1. You will be prompted to enter a passphrase. Remember the passphrase, because you'll need to create a new secret on {{ site.data.variables.product.prodname_dotcom }} that uses the passphrase as the value. 1. You will be prompted to enter a passphrase. Remember the passphrase, because you'll need to create a new secret on {% data variables.product.prodname_dotcom %} that uses the passphrase as the value.
1. Create a new secret that contains the passphrase. For example, create a new secret with the name `LARGE_SECRET_PASSPHRASE` and set the value of the secret to the passphrase you selected in the step above. 1. Create a new secret that contains the passphrase. For example, create a new secret with the name `LARGE_SECRET_PASSPHRASE` and set the value of the secret to the passphrase you selected in the step above.

34
content/actions/reference/environment-variables.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Environment variables title: Environment variables
intro: '{{ site.data.variables.product.prodname_dotcom }} sets default environment variables for each {{ site.data.variables.product.prodname_actions }} workflow run. You can also set custom environment variables in your workflow file.' intro: '{% data variables.product.prodname_dotcom %} sets default environment variables for each {% data variables.product.prodname_actions %} workflow run. You can also set custom environment variables in your workflow file.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /github/automating-your-workflow-with-github-actions/using-environment-variables - /github/automating-your-workflow-with-github-actions/using-environment-variables
- /actions/automating-your-workflow-with-github-actions/using-environment-variables - /actions/automating-your-workflow-with-github-actions/using-environment-variables
@@ -11,14 +11,14 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About environment variables ### About environment variables
{{ site.data.variables.product.prodname_dotcom }} sets default environment variables that are available to every step in a workflow run. Environment variables are case-sensitive. Commands run in actions or steps can create, read, and modify environment variables. {% data variables.product.prodname_dotcom %} sets default environment variables that are available to every step in a workflow run. Environment variables are case-sensitive. Commands run in actions or steps can create, read, and modify environment variables.
To set custom environment variables, you need to specify the variables in the workflow file. You can define environment variables for a step, job, or entire workflow using the [`jobs.<job_id>.steps.env`](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepsenv), [`jobs.<job_id>.env`](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idenv), and [`env`](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env) keywords. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_dotcom }}](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepsenv)." To set custom environment variables, you need to specify the variables in the workflow file. You can define environment variables for a step, job, or entire workflow using the [`jobs.<job_id>.steps.env`](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepsenv), [`jobs.<job_id>.env`](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idenv), and [`env`](/github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#env) keywords. For more information, see "[Workflow syntax for {% data variables.product.prodname_dotcom %}](/articles/workflow-syntax-for-github-actions/#jobsjob_idstepsenv)."
```yaml ```yaml
steps: steps:
@@ -30,39 +30,39 @@ steps:
Last_Name: Octocat Last_Name: Octocat
``` ```
You can also use the `set-env` workflow command to set an environment variable that the following steps in a workflow can use. The `set-env` command can be used directly by an action or as a shell command in a workflow file using the `run` keyword. For more information, see "[Workflow commands for {{ site.data.variables.product.prodname_actions }}](/actions/reference/workflow-commands-for-github-actions/#setting-an-environment-variable)." You can also use the `set-env` workflow command to set an environment variable that the following steps in a workflow can use. The `set-env` command can be used directly by an action or as a shell command in a workflow file using the `run` keyword. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/reference/workflow-commands-for-github-actions/#setting-an-environment-variable)."
### Default environment variables ### Default environment variables
We strongly recommend that actions use environment variables to access the filesystem rather than using hardcoded file paths. {{ site.data.variables.product.prodname_dotcom }} sets environment variables for actions to use in all runner environments. We strongly recommend that actions use environment variables to access the filesystem rather than using hardcoded file paths. {% data variables.product.prodname_dotcom %} sets environment variables for actions to use in all runner environments.
| Environment variable | Description | | Environment variable | Description |
| ---------------------|------------ | | ---------------------|------------ |
| `CI` | Always set to `true`. | | `CI` | Always set to `true`. |
| `HOME` | The path to the {{ site.data.variables.product.prodname_dotcom }} home directory used to store user data. For example, `/github/home`. | | `HOME` | The path to the {% data variables.product.prodname_dotcom %} home directory used to store user data. For example, `/github/home`. |
| `GITHUB_WORKFLOW` | The name of the workflow. | | `GITHUB_WORKFLOW` | The name of the workflow. |
| `GITHUB_RUN_ID` | {{ site.data.reusables.github-actions.run_id_description }} | | `GITHUB_RUN_ID` | {% data reusables.github-actions.run_id_description %} |
| `GITHUB_RUN_NUMBER` | {{ site.data.reusables.github-actions.run_number_description }} | | `GITHUB_RUN_NUMBER` | {% data reusables.github-actions.run_number_description %} |
| `GITHUB_ACTION` | The unique identifier (`id`) of the action. | | `GITHUB_ACTION` | The unique identifier (`id`) of the action. |
| `GITHUB_ACTIONS` | Always set to `true` when {{ site.data.variables.product.prodname_actions }} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {{ site.data.variables.product.prodname_actions }}. | `GITHUB_ACTIONS` | Always set to `true` when {% data variables.product.prodname_actions %} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {% data variables.product.prodname_actions %}.
| `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. | | `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. |
| `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. | | `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. |
| `GITHUB_EVENT_NAME` | The name of the webhook event that triggered the workflow. | | `GITHUB_EVENT_NAME` | The name of the webhook event that triggered the workflow. |
| `GITHUB_EVENT_PATH` | The path of the file with the complete webhook event payload. For example, `/github/workflow/event.json`. | | `GITHUB_EVENT_PATH` | The path of the file with the complete webhook event payload. For example, `/github/workflow/event.json`. |
| `GITHUB_WORKSPACE` | The {{ site.data.variables.product.prodname_dotcom }} workspace directory path. The workspace directory contains a subdirectory with a copy of your repository if your workflow uses the [actions/checkout](https://github.com/actions/checkout) action. If you don't use the `actions/checkout` action, the directory will be empty. For example, `/home/runner/work/my-repo-name/my-repo-name`. | | `GITHUB_WORKSPACE` | The {% data variables.product.prodname_dotcom %} workspace directory path. The workspace directory contains a subdirectory with a copy of your repository if your workflow uses the [actions/checkout](https://github.com/actions/checkout) action. If you don't use the `actions/checkout` action, the directory will be empty. For example, `/home/runner/work/my-repo-name/my-repo-name`. |
| `GITHUB_SHA` | The commit SHA that triggered the workflow. For example, `ffac537e6cbbf934b08745a378932722df287a53`. | | `GITHUB_SHA` | The commit SHA that triggered the workflow. For example, `ffac537e6cbbf934b08745a378932722df287a53`. |
| `GITHUB_REF` | The branch or tag ref that triggered the workflow. For example, `refs/heads/feature-branch-1`. If neither a branch or tag is available for the event type, the variable will not exist. | | `GITHUB_REF` | The branch or tag ref that triggered the workflow. For example, `refs/heads/feature-branch-1`. If neither a branch or tag is available for the event type, the variable will not exist. |
| `GITHUB_HEAD_REF` | Only set for forked repositories. The branch of the head repository. | `GITHUB_HEAD_REF` | Only set for forked repositories. The branch of the head repository.
| `GITHUB_BASE_REF` | Only set for forked repositories. The branch of the base repository. | `GITHUB_BASE_REF` | Only set for forked repositories. The branch of the base repository.
| `GITHUB_SERVER_URL`| Returns the URL of the {{ site.data.variables.product.product_name }} server. For example: `https://{{ site.data.variables.product.product_url }}`. | `GITHUB_SERVER_URL`| Returns the URL of the {% data variables.product.product_name %} server. For example: `https://{% data variables.product.product_url %}`.
| `GITHUB_API_URL` | Returns the API URL. For example: `{{ site.data.variables.product.api_url_code}}`. | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`.
| `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{{ site.data.variables.product.graphql_url_code }}`. | `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url_code %}`.
### Naming conventions for environment variables ### Naming conventions for environment variables
{% note %} {% note %}
**Note:** {{ site.data.variables.product.prodname_dotcom }} reserves the `GITHUB_` environment variable prefix for internal use by {{ site.data.variables.product.prodname_dotcom }}. Setting an environment variable or secret with the `GITHUB_` prefix will result in an error. **Note:** {% data variables.product.prodname_dotcom %} reserves the `GITHUB_` environment variable prefix for internal use by {% data variables.product.prodname_dotcom %}. Setting an environment variable or secret with the `GITHUB_` prefix will result in an error.
{% endnote %} {% endnote %}

144
content/actions/reference/events-that-trigger-workflows.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Events that trigger workflows title: Events that trigger workflows
intro: 'You can configure your workflows to run when specific activity on {{ site.data.variables.product.product_name }} happens, at a scheduled time, or when an event outside of {{ site.data.variables.product.product_name }} occurs.' intro: 'You can configure your workflows to run when specific activity on {% data variables.product.product_name %} happens, at a scheduled time, or when an event outside of {% data variables.product.product_name %} occurs.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
miniTocMaxHeadingLevel: 4 miniTocMaxHeadingLevel: 4
redirect_from: redirect_from:
- /articles/events-that-trigger-workflows - /articles/events-that-trigger-workflows
@@ -12,14 +12,14 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Configuring workflow events ### Configuring workflow events
You can configure workflows to run for one or more events using the `on` workflow syntax. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions#on)." You can configure workflows to run for one or more events using the `on` workflow syntax. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#on)."
{{ site.data.reusables.github-actions.actions-on-examples }} {% data reusables.github-actions.actions-on-examples %}
{% note %} {% note %}
@@ -35,7 +35,7 @@ The following steps occur to trigger a workflow run:
For example, if the event occurred on a particular repository branch, then the workflow files must be present in the repository on that branch. For example, if the event occurred on a particular repository branch, then the workflow files must be present in the repository on that branch.
1. The workflow files for that commit SHA and Git ref are inspected, and a new workflow run is triggered for any workflows that have `on:` values that match the triggering event. 1. The workflow files for that commit SHA and Git ref are inspected, and a new workflow run is triggered for any workflows that have `on:` values that match the triggering event.
The workflow runs on your repository's code at the same commit SHA and Git ref that triggered the event. When a workflow runs, {{ site.data.variables.product.product_name }} sets the `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) environment variables in the runner environment. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)." The workflow runs on your repository's code at the same commit SHA and Git ref that triggered the event. When a workflow runs, {% data variables.product.product_name %} sets the `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) environment variables in the runner environment. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)."
### Scheduled events ### Scheduled events
@@ -47,7 +47,7 @@ The `schedule` event allows you to trigger a workflow at a scheduled time.
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| n/a | n/a | Last commit on default branch | Default branch | When the scheduled workflow is set to run. A scheduled workflow uses [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). For more information, see "[Triggering a workflow with events](/articles/configuring-a-workflow/#triggering-a-workflow-with-events)." | | n/a | n/a | Last commit on default branch | Default branch | When the scheduled workflow is set to run. A scheduled workflow uses [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). For more information, see "[Triggering a workflow with events](/articles/configuring-a-workflow/#triggering-a-workflow-with-events)." |
{{ site.data.reusables.repositories.actions-scheduled-workflow-example }} {% data reusables.repositories.actions-scheduled-workflow-example %}
Cron syntax has five fields separated by a space, and each field represents a unit of time. Cron syntax has five fields separated by a space, and each field represents a unit of time.
@@ -74,7 +74,7 @@ You can use these operators in any of the five fields:
{% note %} {% note %}
**Note:** {{ site.data.variables.product.prodname_actions }} does not support the non-standard syntax `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`, and `@reboot`. **Note:** {% data variables.product.prodname_actions %} does not support the non-standard syntax `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`, and `@reboot`.
{% endnote %} {% endnote %}
@@ -90,13 +90,13 @@ You can manually trigger workflow runs. To trigger specific workflows in a repos
| ------------------ | ------------ | ------------ | ------------------| | ------------------ | ------------ | ------------ | ------------------|
| [workflow_dispatch](/webhooks/event-payloads/#workflow_dispatch) | n/a | Last commit on the `GITHUB_REF` branch | Branch that received dispatch | | [workflow_dispatch](/webhooks/event-payloads/#workflow_dispatch) | n/a | Last commit on the `GITHUB_REF` branch | Branch that received dispatch |
You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When the workflow runs, you can access the input values in the `github.event.inputs` context. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)." You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When the workflow runs, you can access the input values in the `github.event.inputs` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)."
You can manually trigger a workflow run using the {{ site.data.variables.product.product_name }} API and from {{ site.data.variables.product.product_name }}. For more information, see "[Manually running a workflow](/actions/managing-workflow-runs/manually-running-a-workflow)." You can manually trigger a workflow run using the {% data variables.product.product_name %} API and from {% data variables.product.product_name %}. For more information, see "[Manually running a workflow](/actions/managing-workflow-runs/manually-running-a-workflow)."
When you trigger the event on {{ site.data.variables.product.prodname_dotcom }}, you can provide the `ref` and any `inputs` directly on {{ site.data.variables.product.prodname_dotcom }}. For more information, see "[Using inputs and outputs with an action](/actions/learn-github-actions/finding-and-customizing-actions#using-inputs-and-outputs-with-an-action)." When you trigger the event on {% data variables.product.prodname_dotcom %}, you can provide the `ref` and any `inputs` directly on {% data variables.product.prodname_dotcom %}. For more information, see "[Using inputs and outputs with an action](/actions/learn-github-actions/finding-and-customizing-actions#using-inputs-and-outputs-with-an-action)."
To trigger the custom `workflow_dispatch` webhook event using the REST API, you must send a `POST` request to a {{ site.data.variables.product.prodname_dotcom }} API endpoint and provide the `ref` and any required `inputs`. For more information, see the "[Create a workflow dispatch event](/rest/reference/actions/#create-a-workflow-dispatch-event)" REST API endpoint. To trigger the custom `workflow_dispatch` webhook event using the REST API, you must send a `POST` request to a {% data variables.product.prodname_dotcom %} API endpoint and provide the `ref` and any required `inputs`. For more information, see the "[Create a workflow dispatch event](/rest/reference/actions/#create-a-workflow-dispatch-event)" REST API endpoint.
##### Example workflow configuration ##### Example workflow configuration
@@ -132,11 +132,11 @@ jobs:
| ------------------ | ------------ | ------------ | ------------------| | ------------------ | ------------ | ------------ | ------------------|
| [repository_dispatch](/webhooks/event-payloads/#repository_dispatch) | n/a | Last commit on the `GITHUB_REF` branch | Branch that received dispatch | | [repository_dispatch](/webhooks/event-payloads/#repository_dispatch) | n/a | Last commit on the `GITHUB_REF` branch | Branch that received dispatch |
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
You can use the {{ site.data.variables.product.product_name }} API to trigger a webhook event called [`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {{ site.data.variables.product.prodname_dotcom }}. For more information, see "[Create a repository dispatch event](/v3/repos/#create-a-repository-dispatch-event)." You can use the {% data variables.product.product_name %} API to trigger a webhook event called [`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {% data variables.product.prodname_dotcom %}. For more information, see "[Create a repository dispatch event](/v3/repos/#create-a-repository-dispatch-event)."
To trigger the custom `repository_dispatch` webhook event, you must send a `POST` request to a {{ site.data.variables.product.product_name }} API endpoint and provide an `event_type` name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the `repository_dispatch` event. To trigger the custom `repository_dispatch` webhook event, you must send a `POST` request to a {% data variables.product.product_name %} API endpoint and provide an `event_type` name to describe the activity type. To trigger a workflow run, you must also configure your workflow to use the `repository_dispatch` event.
##### Example ##### Example
@@ -150,19 +150,19 @@ on:
### Webhook events ### Webhook events
You can configure your workflow to run when webhook events are created on {{ site.data.variables.product.product_name }}. Some events have more than one activity type that triggers the event. If more than one activity type triggers the event, you can specify which activity types will trigger the workflow to run. For more information, see "[Webhooks](/webhooks)." You can configure your workflow to run when webhook events are created on {% data variables.product.product_name %}. Some events have more than one activity type that triggers the event. If more than one activity type triggers the event, you can specify which activity types will trigger the workflow to run. For more information, see "[Webhooks](/webhooks)."
#### `check_run` #### `check_run`
Runs your workflow anytime the `check_run` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Check runs](/v3/checks/runs/)." Runs your workflow anytime the `check_run` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check runs](/v3/checks/runs/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`check_run`](/webhooks/event-payloads/#check_run) | - `created`<br/>- `rerequested`<br/>- `completed`<br/>- `requested_action` | Last commit on default branch | Default branch | | [`check_run`](/webhooks/event-payloads/#check_run) | - `created`<br/>- `rerequested`<br/>- `completed`<br/>- `requested_action` | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a check run has been `rerequested` or `requested_action`. For example, you can run a workflow when a check run has been `rerequested` or `requested_action`.
@@ -174,13 +174,13 @@ on:
#### `check_suite` #### `check_suite`
Runs your workflow anytime the `check_suite` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Check suites](/v3/checks/suites/)." Runs your workflow anytime the `check_suite` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Check suites](/v3/checks/suites/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
{% note %} {% note %}
**Note:** To prevent recursive workflows, this event does not trigger workflows if the check suite was created by {{ site.data.variables.product.prodname_actions }}. **Note:** To prevent recursive workflows, this event does not trigger workflows if the check suite was created by {% data variables.product.prodname_actions %}.
{% endnote %} {% endnote %}
@@ -188,7 +188,7 @@ Runs your workflow anytime the `check_suite` event occurs. {{ site.data.reusable
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`check_suite`](/webhooks/event-payloads/#check_suite) | - `completed`<br/>- `requested`<br/>- `rerequested`<br/> | Last commit on default branch | Default branch | | [`check_suite`](/webhooks/event-payloads/#check_suite) | - `completed`<br/>- `requested`<br/>- `rerequested`<br/> | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a check suite has been `rerequested` or `completed`. For example, you can run a workflow when a check suite has been `rerequested` or `completed`.
@@ -217,7 +217,7 @@ on:
Runs your workflow anytime someone deletes a branch or tag, which triggers the `delete` event. For information about the REST API, see "[Delete a reference](/v3/git/refs/#delete-a-reference)." Runs your workflow anytime someone deletes a branch or tag, which triggers the `delete` event. For information about the REST API, see "[Delete a reference](/v3/git/refs/#delete-a-reference)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -264,7 +264,7 @@ on:
Runs your workflow anytime when someone forks a repository, which triggers the `fork` event. For information about the REST API, see "[Create a fork](/v3/repos/forks/#create-a-fork)." Runs your workflow anytime when someone forks a repository, which triggers the `fork` event. For information about the REST API, see "[Create a fork](/v3/repos/forks/#create-a-fork)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -281,7 +281,7 @@ on:
Runs your workflow when someone creates or updates a Wiki page, which triggers the `gollum` event. Runs your workflow when someone creates or updates a Wiki page, which triggers the `gollum` event.
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -296,15 +296,15 @@ on:
#### `issue_comment` #### `issue_comment`
Runs your workflow anytime the `issue_comment` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Issue comments](/v3/issues/comments/)." Runs your workflow anytime the `issue_comment` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Issue comments](/v3/issues/comments/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`issue_comment`](/v3/activity/event_types/#issue_comment) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | | [`issue_comment`](/v3/activity/event_types/#issue_comment) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when an issue comment has been `created` or `deleted`. For example, you can run a workflow when an issue comment has been `created` or `deleted`.
@@ -316,15 +316,15 @@ on:
#### `issues` #### `issues`
Runs your workflow anytime the `issues` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Issues](/v3/issues)." Runs your workflow anytime the `issues` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Issues](/v3/issues)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`issues`](/webhooks/event-payloads/#issues) | - `opened`<br/>- `edited`<br/>- `deleted`<br/>- `transferred`<br/>- `pinned`<br/>- `unpinned`<br/>- `closed`<br/>- `reopened`<br/>- `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `locked`<br/>- `unlocked`<br/>- `milestoned`<br/> - `demilestoned` | Last commit on default branch | Default branch | | [`issues`](/webhooks/event-payloads/#issues) | - `opened`<br/>- `edited`<br/>- `deleted`<br/>- `transferred`<br/>- `pinned`<br/>- `unpinned`<br/>- `closed`<br/>- `reopened`<br/>- `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `locked`<br/>- `unlocked`<br/>- `milestoned`<br/> - `demilestoned` | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when an issue has been `opened`, `edited`, or `milestoned`. For example, you can run a workflow when an issue has been `opened`, `edited`, or `milestoned`.
@@ -336,15 +336,15 @@ on:
#### `label` #### `label`
Runs your workflow anytime the `label` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Labels](/v3/issues/labels/)." Runs your workflow anytime the `label` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Labels](/v3/issues/labels/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`label`](/webhooks/event-payloads/#label) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | | [`label`](/webhooks/event-payloads/#label) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a label has been `created` or `deleted`. For example, you can run a workflow when a label has been `created` or `deleted`.
@@ -356,15 +356,15 @@ on:
#### `milestone` #### `milestone`
Runs your workflow anytime the `milestone` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Milestones](/v3/issues/milestones/)." Runs your workflow anytime the `milestone` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Milestones](/v3/issues/milestones/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`milestone`](/webhooks/event-payloads/#milestone) | - `created`<br/>- `closed`<br/>- `opened`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | | [`milestone`](/webhooks/event-payloads/#milestone) | - `created`<br/>- `closed`<br/>- `opened`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a milestone has been `opened` or `deleted`. For example, you can run a workflow when a milestone has been `opened` or `deleted`.
@@ -376,9 +376,9 @@ on:
#### `page_build` #### `page_build`
Runs your workflow anytime someone pushes to a {{ site.data.variables.product.product_name }} Pages-enabled branch, which triggers the `page_build` event. For information about the REST API, see "[Pages](/v3/repos/pages/)." Runs your workflow anytime someone pushes to a {% data variables.product.product_name %} Pages-enabled branch, which triggers the `page_build` event. For information about the REST API, see "[Pages](/v3/repos/pages/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -393,15 +393,15 @@ on:
#### `project` #### `project`
Runs your workflow anytime the `project` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Projects](/v3/projects/)." Runs your workflow anytime the `project` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Projects](/v3/projects/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`project`](/webhooks/event-payloads/#project) | - `created`<br/>- `updated`<br/>- `closed`<br/>- `reopened`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | | [`project`](/webhooks/event-payloads/#project) | - `created`<br/>- `updated`<br/>- `closed`<br/>- `reopened`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a project has been `created` or `deleted`. For example, you can run a workflow when a project has been `created` or `deleted`.
@@ -413,15 +413,15 @@ on:
#### `project_card` #### `project_card`
Runs your workflow anytime the `project_card` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Project cards](/v3/projects/cards)." Runs your workflow anytime the `project_card` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project cards](/v3/projects/cards)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`project_card`](/webhooks/event-payloads/#project_card) | - `created`<br/>- `moved`<br/>- `converted` to an issue<br/>- `edited`<br/>- `deleted` | Last commit on default branch | Default branch | | [`project_card`](/webhooks/event-payloads/#project_card) | - `created`<br/>- `moved`<br/>- `converted` to an issue<br/>- `edited`<br/>- `deleted` | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a project card has been `opened` or `deleted`. For example, you can run a workflow when a project card has been `opened` or `deleted`.
@@ -433,15 +433,15 @@ on:
#### `project_column` #### `project_column`
Runs your workflow anytime the `project_column` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Project columns](/v3/projects/columns)." Runs your workflow anytime the `project_column` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Project columns](/v3/projects/columns)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`project_column`](/webhooks/event-payloads/#project_column) | - `created`<br/>- `updated`<br/>- `moved`<br/>- `deleted` | Last commit on default branch | Default branch | | [`project_column`](/webhooks/event-payloads/#project_column) | - `created`<br/>- `updated`<br/>- `moved`<br/>- `deleted` | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a project column has been `created` or `deleted`. For example, you can run a workflow when a project column has been `created` or `deleted`.
@@ -455,7 +455,7 @@ on:
Runs your workflow anytime someone makes a private repository public, which triggers the `public` event. For information about the REST API, see "[Edit repositories](/v3/repos/#edit)." Runs your workflow anytime someone makes a private repository public, which triggers the `public` event. For information about the REST API, see "[Edit repositories](/v3/repos/#edit)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -470,7 +470,7 @@ on:
#### `pull_request` #### `pull_request`
Runs your workflow anytime the `pull_request` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Pull requests](/v3/pulls)." Runs your workflow anytime the `pull_request` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull requests](/v3/pulls)."
{% note %} {% note %}
@@ -482,7 +482,7 @@ Runs your workflow anytime the `pull_request` event occurs. {{ site.data.reusabl
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`pull_request`](/webhooks/event-payloads/#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `ready_for_review`<br/>- `locked`<br/>- `unlocked` <br/>- `review_requested` <br/>- `review_request_removed` | Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/:prNumber/merge` | | [`pull_request`](/webhooks/event-payloads/#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `ready_for_review`<br/>- `locked`<br/>- `unlocked` <br/>- `review_requested` <br/>- `review_request_removed` | Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/:prNumber/merge` |
You extend or limit the default activity types using the `types` keyword. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions#onevent_nametypes)." You extend or limit the default activity types using the `types` keyword. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#onevent_nametypes)."
For example, you can run a workflow when a pull request has been `assigned`, `opened`, `synchronize`, or `reopened`. For example, you can run a workflow when a pull request has been `assigned`, `opened`, `synchronize`, or `reopened`.
@@ -492,17 +492,17 @@ on:
types: [assigned, opened, synchronize, reopened] types: [assigned, opened, synchronize, reopened]
``` ```
{{ site.data.reusables.developer-site.pull_request_forked_repos_link }} {% data reusables.developer-site.pull_request_forked_repos_link %}
#### `pull_request_review` #### `pull_request_review`
Runs your workflow anytime the `pull_request_review` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Pull request reviews](/v3/pulls/reviews)." Runs your workflow anytime the `pull_request_review` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Pull request reviews](/v3/pulls/reviews)."
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`pull_request_review`](/webhooks/event-payloads/#pull_request_review) | - `submitted`<br/>- `edited`<br/>- `dismissed` | Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/:prNumber/merge` | | [`pull_request_review`](/webhooks/event-payloads/#pull_request_review) | - `submitted`<br/>- `edited`<br/>- `dismissed` | Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/:prNumber/merge` |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a pull request review has been `edited` or `dismissed`. For example, you can run a workflow when a pull request review has been `edited` or `dismissed`.
@@ -512,17 +512,17 @@ on:
types: [edited, dismissed] types: [edited, dismissed]
``` ```
{{ site.data.reusables.developer-site.pull_request_forked_repos_link }} {% data reusables.developer-site.pull_request_forked_repos_link %}
#### `pull_request_review_comment` #### `pull_request_review_comment`
Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the `pull_request_review_comment` event. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see [Review comments](/v3/pulls/comments). Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the `pull_request_review_comment` event. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see [Review comments](/v3/pulls/comments).
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`pull_request_review_comment`](/webhooks/event-payloads/#pull_request_review_comment) | - `created`<br/>- `edited`<br/>- `deleted`| Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/:prNumber/merge` | | [`pull_request_review_comment`](/webhooks/event-payloads/#pull_request_review_comment) | - `created`<br/>- `edited`<br/>- `deleted`| Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/:prNumber/merge` |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a pull request review comment has been `created` or `deleted`. For example, you can run a workflow when a pull request review comment has been `created` or `deleted`.
@@ -532,7 +532,7 @@ on:
types: [created, deleted] types: [created, deleted]
``` ```
{{ site.data.reusables.developer-site.pull_request_forked_repos_link }} {% data reusables.developer-site.pull_request_forked_repos_link %}
#### `pull_request_target` #### `pull_request_target`
@@ -542,7 +542,7 @@ This event is similar to `pull_request`, except that it runs in the context of t
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`pull_request`](/webhooks/event-payloads/#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `ready_for_review`<br/>- `locked`<br/>- `unlocked` <br/>- `review_requested` <br/>- `review_request_removed` | Last commit on the PR base branch | PR base branch | | [`pull_request`](/webhooks/event-payloads/#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `ready_for_review`<br/>- `locked`<br/>- `unlocked` <br/>- `review_requested` <br/>- `review_request_removed` | Last commit on the PR base branch | PR base branch |
By default, a workflow only runs when a `pull_request_target`'s activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows for more activity types, use the `types` keyword. For more information, see "[Workflow syntax for {{ site.data.variables.product.prodname_actions }}](/articles/workflow-syntax-for-github-actions#onevent_nametypes)." By default, a workflow only runs when a `pull_request_target`'s activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows for more activity types, use the `types` keyword. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#onevent_nametypes)."
For example, you can run a workflow when a pull request has been `assigned`, `opened`, `synchronize`, or `reopened`. For example, you can run a workflow when a pull request has been `assigned`, `opened`, `synchronize`, or `reopened`.
@@ -574,13 +574,13 @@ on:
#### `registry_package` #### `registry_package`
Runs your workflow anytime a package is `published` or `updated`. For more information, see "[Managing packages with {{ site.data.variables.product.prodname_registry }}](/github/managing-packages-with-github-packages)." Runs your workflow anytime a package is `published` or `updated`. For more information, see "[Managing packages with {% data variables.product.prodname_registry %}](/github/managing-packages-with-github-packages)."
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`registry_package`](/webhooks/event-payloads/#package) | - `published`<br/>- `updated` | Commit of the published package | Branch or tag of the published package | | [`registry_package`](/webhooks/event-payloads/#package) | - `published`<br/>- `updated` | Commit of the published package | Branch or tag of the published package |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a package has been `published`. For example, you can run a workflow when a package has been `published`.
@@ -598,13 +598,13 @@ on:
{% endnote %} {% endnote %}
Runs your workflow anytime the `release` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Releases](/v3/repos/releases/)." Runs your workflow anytime the `release` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Releases](/v3/repos/releases/)."
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`release`](/webhooks/event-payloads/#release) | - `published`{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.18" %} <br/>- `unpublished` <br/>- `created` <br/>- `edited` <br/>- `deleted` <br/>- `prereleased`<br/> - `released`{% endif %} | Last commit in the tagged release | Tag of release | | [`release`](/webhooks/event-payloads/#release) | - `published`{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.18" %} <br/>- `unpublished` <br/>- `created` <br/>- `edited` <br/>- `deleted` <br/>- `prereleased`<br/> - `released`{% endif %} | Last commit in the tagged release | Tag of release |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when a release has been `published`. For example, you can run a workflow when a release has been `published`.
@@ -618,7 +618,7 @@ on:
Runs your workflow anytime the status of a Git commit changes, which triggers the `status` event. For information about the REST API, see [Statuses](/v3/repos/statuses/). Runs your workflow anytime the status of a Git commit changes, which triggers the `status` event. For information about the REST API, see [Statuses](/v3/repos/statuses/).
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
@@ -633,15 +633,15 @@ on:
#### `watch` #### `watch`
Runs your workflow anytime the `watch` event occurs. {{ site.data.reusables.developer-site.multiple_activity_types }} For information about the REST API, see "[Starring](/v3/activity/starring/)." Runs your workflow anytime the `watch` event occurs. {% data reusables.developer-site.multiple_activity_types %} For information about the REST API, see "[Starring](/v3/activity/starring/)."
{{ site.data.reusables.github-actions.branch-requirement }} {% data reusables.github-actions.branch-requirement %}
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | | Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
| --------------------- | -------------- | ------------ | -------------| | --------------------- | -------------- | ------------ | -------------|
| [`watch`](/webhooks/event-payloads/#watch) | - `started` | Last commit on default branch | Default branch | | [`watch`](/webhooks/event-payloads/#watch) | - `started` | Last commit on default branch | Default branch |
{{ site.data.reusables.developer-site.limit_workflow_to_activity_types }} {% data reusables.developer-site.limit_workflow_to_activity_types %}
For example, you can run a workflow when someone stars a repository, which is the `started` activity type that triggers the watch event. For example, you can run a workflow when someone stars a repository, which is the `started` activity type that triggers the watch event.
@@ -653,7 +653,7 @@ on:
#### `workflow_run` #### `workflow_run`
{{ site.data.reusables.webhooks.workflow_run_desc }} {% data reusables.webhooks.workflow_run_desc %}
If you need to filter branches from this event, you can use `branches` or `branches-ignore`. If you need to filter branches from this event, you can use `branches` or `branches-ignore`.
@@ -671,6 +671,6 @@ on:
### Triggering new workflows using a personal access token ### Triggering new workflows using a personal access token
{{ site.data.reusables.github-actions.actions-do-not-trigger-workflows }} For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)." {% data reusables.github-actions.actions-do-not-trigger-workflows %} For more information, see "[Authenticating with the GITHUB_TOKEN](/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)."
If you would like to trigger a workflow from a workflow run, you can trigger the event using a personal access token. You'll need to create a personal access token and store it as a secret. To minimize your {{ site.data.variables.product.prodname_actions }} usage costs, ensure that you don't create recursive or unintended workflow runs. For more information, see "[Creating and storing encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)." If you would like to trigger a workflow from a workflow run, you can trigger the event using a personal access token. You'll need to create a personal access token and store it as a secret. To minimize your {% data variables.product.prodname_actions %} usage costs, ensure that you don't create recursive or unintended workflow runs. For more information, see "[Creating and storing encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)."

10
content/actions/reference/index.md
View File

@@ -8,8 +8,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### Workflow syntax ### Workflow syntax
@@ -27,12 +27,12 @@ You can configure workflows to run when specific GitHub events occur, at a sched
### Authentication and secrets ### Authentication and secrets
{{ site.data.variables.product.prodname_dotcom }} provides a token that you can use to authenticate on behalf of {{ site.data.variables.product.prodname_actions }}. You can also store sensitive information as a secret in your organization or repository. {{ site.data.variables.product.prodname_dotcom }} encrypts all secrets. {% data variables.product.prodname_dotcom %} provides a token that you can use to authenticate on behalf of {% data variables.product.prodname_actions %}. You can also store sensitive information as a secret in your organization or repository. {% data variables.product.prodname_dotcom %} encrypts all secrets.
{% link_in_list /authentication-in-a-workflow %} {% link_in_list /authentication-in-a-workflow %}
{% link_in_list /encrypted-secrets %} {% link_in_list /encrypted-secrets %}
### {{ site.data.variables.product.prodname_dotcom }}-hosted runners ### {% data variables.product.prodname_dotcom %}-hosted runners
GitHub offers hosted virtual machines to run workflows. The virtual machine contains an environment with tools, packages, and environment variables for GitHub Actions to use. GitHub offers hosted virtual machines to run workflows. The virtual machine contains an environment with tools, packages, and environment variables for GitHub Actions to use.
@@ -42,7 +42,7 @@ GitHub offers hosted virtual machines to run workflows. The virtual machine cont
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
### Administration ### Administration
When you run workflows on {{ site.data.variables.product.prodname_dotcom }}-hosted runners, there are usage limits and potential usage charges. You can also disable or restrict the usage of {{ site.data.variables.product.prodname_actions }} in a repository and organization. When you run workflows on {% data variables.product.prodname_dotcom %}-hosted runners, there are usage limits and potential usage charges. You can also disable or restrict the usage of {% data variables.product.prodname_actions %} in a repository and organization.
{% link_in_list /usage-limits-billing-and-administration %} {% link_in_list /usage-limits-billing-and-administration %}

50
content/actions/reference/specifications-for-github-hosted-runners.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Specifications for GitHub-hosted runners title: Specifications for GitHub-hosted runners
intro: '{{ site.data.variables.product.prodname_dotcom }} offers hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for {{ site.data.variables.product.prodname_actions }} to use.' intro: '{% data variables.product.prodname_dotcom %} offers hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for {% data variables.product.prodname_actions %} to use.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/virtual-environments-for-github-actions - /articles/virtual-environments-for-github-actions
- /github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions - /github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions
@@ -14,26 +14,26 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About {{ site.data.variables.product.prodname_dotcom }}-hosted runners ### About {% data variables.product.prodname_dotcom %}-hosted runners
A {{ site.data.variables.product.prodname_dotcom }}-hosted runner is a virtual machine hosted by {{ site.data.variables.product.prodname_dotcom }} with the {{ site.data.variables.product.prodname_actions }} runner application installed. {{ site.data.variables.product.prodname_dotcom }} offers runners with Linux, Windows, and macOS operating systems. A {% data variables.product.prodname_dotcom %}-hosted runner is a virtual machine hosted by {% data variables.product.prodname_dotcom %} with the {% data variables.product.prodname_actions %} runner application installed. {% data variables.product.prodname_dotcom %} offers runners with Linux, Windows, and macOS operating systems.
When you use a {{ site.data.variables.product.prodname_dotcom }}-hosted runner, machine maintenance and upgrades are taken care of for you. You can run workflows directly on the virtual machine or in a Docker container. When you use a {% data variables.product.prodname_dotcom %}-hosted runner, machine maintenance and upgrades are taken care of for you. You can run workflows directly on the virtual machine or in a Docker container.
You can specify the runner type for each job in a workflow. Each job in a workflow executes in a fresh instance of the virtual machine. All steps in the job execute in the same instance of the virtual machine, allowing the actions in that job to share information using the filesystem. You can specify the runner type for each job in a workflow. Each job in a workflow executes in a fresh instance of the virtual machine. All steps in the job execute in the same instance of the virtual machine, allowing the actions in that job to share information using the filesystem.
{{ site.data.reusables.github-actions.runner-app-open-source }} {% data reusables.github-actions.runner-app-open-source %}
#### Cloud hosts for {{ site.data.variables.product.prodname_dotcom }}-hosted runners #### Cloud hosts for {% data variables.product.prodname_dotcom %}-hosted runners
{{ site.data.variables.product.prodname_dotcom }} hosts Linux and Windows runners on Standard_DS2_v2 virtual machines in Microsoft Azure with the {{ site.data.variables.product.prodname_actions }} runner application installed. The {{ site.data.variables.product.prodname_dotcom }}-hosted runner application is a fork of the Azure Pipelines Agent. Inbound ICMP packets are blocked for all Azure virtual machines, so ping or traceroute commands might not work. For more information about the Standard_DS2_v2 machine resources, see "[Dv2 and DSv2-series](https://docs.microsoft.com/en-us/azure/virtual-machines/dv2-dsv2-series#dsv2-series)" in the Microsoft Azure documentation. {% data variables.product.prodname_dotcom %} hosts Linux and Windows runners on Standard_DS2_v2 virtual machines in Microsoft Azure with the {% data variables.product.prodname_actions %} runner application installed. The {% data variables.product.prodname_dotcom %}-hosted runner application is a fork of the Azure Pipelines Agent. Inbound ICMP packets are blocked for all Azure virtual machines, so ping or traceroute commands might not work. For more information about the Standard_DS2_v2 machine resources, see "[Dv2 and DSv2-series](https://docs.microsoft.com/en-us/azure/virtual-machines/dv2-dsv2-series#dsv2-series)" in the Microsoft Azure documentation.
{{ site.data.variables.product.prodname_dotcom }} uses [MacStadium](https://www.macstadium.com/) to host the macOS runners. {% data variables.product.prodname_dotcom %} uses [MacStadium](https://www.macstadium.com/) to host the macOS runners.
#### Administrative privileges of {{ site.data.variables.product.prodname_dotcom }}-hosted runners #### Administrative privileges of {% data variables.product.prodname_dotcom %}-hosted runners
The Linux and macOS virtual machines both run using passwordless `sudo`. When you need to execute commands or install tools that require more privileges than the current user, you can use `sudo` without needing to provide a password. For more information, see the "[Sudo Manual](https://www.sudo.ws/man/1.8.27/sudo.man.html)." The Linux and macOS virtual machines both run using passwordless `sudo`. When you need to execute commands or install tools that require more privileges than the current user, you can use `sudo` without needing to provide a password. For more information, see the "[Sudo Manual](https://www.sudo.ws/man/1.8.27/sudo.man.html)."
@@ -47,15 +47,15 @@ Each virtual machine has the same hardware resources available.
- 7 GB of RAM memory - 7 GB of RAM memory
- 14 GB of SSD disk space - 14 GB of SSD disk space
{{ site.data.reusables.github-actions.supported-github-runners }} {% data reusables.github-actions.supported-github-runners %}
{{ site.data.reusables.github-actions.ubuntu-runner-preview }} {% data reusables.github-actions.ubuntu-runner-preview %}
Workflow logs list the runner used to run a job. For more information, see "[Viewing workflow run history](/actions/managing-workflow-runs/viewing-workflow-run-history)." Workflow logs list the runner used to run a job. For more information, see "[Viewing workflow run history](/actions/managing-workflow-runs/viewing-workflow-run-history)."
### Supported software ### Supported software
The software tools included in {{ site.data.variables.product.prodname_dotcom }}-hosted runners are updated weekly. For the latest list of included tools for each runner operating system, see the links below: The software tools included in {% data variables.product.prodname_dotcom %}-hosted runners are updated weekly. For the latest list of included tools for each runner operating system, see the links below:
* [Ubuntu 20.04 LTS](https://github.com/actions/virtual-environments/blob/master/images/linux/Ubuntu2004-README.md) * [Ubuntu 20.04 LTS](https://github.com/actions/virtual-environments/blob/master/images/linux/Ubuntu2004-README.md)
* [Ubuntu 18.04 LTS](https://github.com/actions/virtual-environments/blob/master/images/linux/Ubuntu1804-README.md) * [Ubuntu 18.04 LTS](https://github.com/actions/virtual-environments/blob/master/images/linux/Ubuntu1804-README.md)
@@ -64,9 +64,9 @@ The software tools included in {{ site.data.variables.product.prodname_dotcom }}
* [Windows Server 2016](https://github.com/actions/virtual-environments/blob/master/images/win/Windows2016-Readme.md) * [Windows Server 2016](https://github.com/actions/virtual-environments/blob/master/images/win/Windows2016-Readme.md)
* [MacOS 10.15](https://github.com/actions/virtual-environments/blob/master/images/macos/macos-10.15-Readme.md) * [MacOS 10.15](https://github.com/actions/virtual-environments/blob/master/images/macos/macos-10.15-Readme.md)
{{ site.data.reusables.github-actions.ubuntu-runner-preview }} {% data reusables.github-actions.ubuntu-runner-preview %}
{{ site.data.variables.product.prodname_dotcom }}-hosted runners include the operating system's default built-in tools, in addition to the packages listed in the above references. For example, Ubuntu and macOS runners include `grep`, `find`, and `which`, among other default tools. {% data variables.product.prodname_dotcom %}-hosted runners include the operating system's default built-in tools, in addition to the packages listed in the above references. For example, Ubuntu and macOS runners include `grep`, `find`, and `which`, among other default tools.
Workflow logs include a link to the preinstalled tools on the runner. For more information, see "[Viewing workflow run history](/actions/managing-workflow-runs/viewing-workflow-run-history)." Workflow logs include a link to the preinstalled tools on the runner. For more information, see "[Viewing workflow run history](/actions/managing-workflow-runs/viewing-workflow-run-history)."
@@ -76,11 +76,11 @@ If there is a tool that you'd like to request, please open an issue at [actions/
{% note %} {% note %}
**Note:** If you use an IP address allow list for your {{ site.data.variables.product.prodname_dotcom }} organization or enterprise account, you cannot use {{ site.data.variables.product.prodname_dotcom }}-hosted runners and must instead use self-hosted runners. For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners)." **Note:** If you use an IP address allow list for your {% data variables.product.prodname_dotcom %} organization or enterprise account, you cannot use {% data variables.product.prodname_dotcom %}-hosted runners and must instead use self-hosted runners. For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners)."
{% endnote %} {% endnote %}
Windows and Ubuntu runners are hosted in Azure and have the same IP address ranges as Azure Data centers. Currently, all Windows and Ubuntu {{ site.data.variables.product.prodname_dotcom }}-hosted runners are in the following Azure regions: Windows and Ubuntu runners are hosted in Azure and have the same IP address ranges as Azure Data centers. Currently, all Windows and Ubuntu {% data variables.product.prodname_dotcom %}-hosted runners are in the following Azure regions:
- East US (`eastus`) - East US (`eastus`)
- East US 2 (`eastus2`) - East US 2 (`eastus2`)
@@ -121,29 +121,29 @@ You can find the supported IP address ranges in the `"addressPrefixes"` object.
### File systems ### File systems
{{ site.data.variables.product.prodname_dotcom }} executes actions and shell commands in specific directories on the virtual machine. The file paths on virtual machines are not static. Use the environment variables {{ site.data.variables.product.prodname_dotcom }} provides to construct file paths for the `home`, `workspace`, and `workflow` directories. {% data variables.product.prodname_dotcom %} executes actions and shell commands in specific directories on the virtual machine. The file paths on virtual machines are not static. Use the environment variables {% data variables.product.prodname_dotcom %} provides to construct file paths for the `home`, `workspace`, and `workflow` directories.
| Directory | Environment variable | Description | | Directory | Environment variable | Description |
|-----------|----------------------|-------------| |-----------|----------------------|-------------|
| `home` | `HOME` | Contains user-related data. For example, this directory could contain credentials from a login attempt. | | `home` | `HOME` | Contains user-related data. For example, this directory could contain credentials from a login attempt. |
| `workspace` | `GITHUB_WORKSPACE` | Actions and shell commands execute in this directory. An action can modify the contents of this directory, which subsequent actions can access. | | `workspace` | `GITHUB_WORKSPACE` | Actions and shell commands execute in this directory. An action can modify the contents of this directory, which subsequent actions can access. |
| `workflow/event.json` | `GITHUB_EVENT_PATH` | The `POST` payload of the webhook event that triggered the workflow. {{ site.data.variables.product.prodname_dotcom }} rewrites this each time an action executes to isolate file content between actions. | `workflow/event.json` | `GITHUB_EVENT_PATH` | The `POST` payload of the webhook event that triggered the workflow. {% data variables.product.prodname_dotcom %} rewrites this each time an action executes to isolate file content between actions.
For a list of the environment variables {{ site.data.variables.product.prodname_dotcom }} creates for each workflow, see "[Using environment variables](/github/automating-your-workflow-with-github-actions/using-environment-variables)." For a list of the environment variables {% data variables.product.prodname_dotcom %} creates for each workflow, see "[Using environment variables](/github/automating-your-workflow-with-github-actions/using-environment-variables)."
#### Docker container filesystem #### Docker container filesystem
Actions that run in Docker containers have static directories under the `/github` path. However, we strongly recommend using the default environment variables to construct file paths in Docker containers. Actions that run in Docker containers have static directories under the `/github` path. However, we strongly recommend using the default environment variables to construct file paths in Docker containers.
{{ site.data.variables.product.prodname_dotcom }} reserves the `/github` path prefix and creates three directories for actions. {% data variables.product.prodname_dotcom %} reserves the `/github` path prefix and creates three directories for actions.
- `/github/home` - `/github/home`
- `/github/workspace` - {{ site.data.reusables.repositories.action-root-user-required }} - `/github/workspace` - {% data reusables.repositories.action-root-user-required %}
- `/github/workflow` - `/github/workflow`
{% if currentVersion == "free-pro-team@latest" %} {% if currentVersion == "free-pro-team@latest" %}
### Further reading ### Further reading
- "[Managing billing for {{ site.data.variables.product.prodname_actions }}](/github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions)" - "[Managing billing for {% data variables.product.prodname_actions %}](/github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions)"
{% endif %} {% endif %}

28
content/actions/reference/usage-limits-billing-and-administration.md
View File

@@ -1,23 +1,23 @@
--- ---
title: 'Usage limits, billing, and administration' title: 'Usage limits, billing, and administration'
intro: 'There are usage limits for {{ site.data.variables.product.prodname_actions }} workflows. Usage charges apply to repositories that go beyond the amount of free minutes and storage for a repository.' intro: 'There are usage limits for {% data variables.product.prodname_actions %} workflows. Usage charges apply to repositories that go beyond the amount of free minutes and storage for a repository.'
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /actions/getting-started-with-github-actions/usage-and-billing-information-for-github-actions - /actions/getting-started-with-github-actions/usage-and-billing-information-for-github-actions
versions: versions:
free-pro-team: '*' free-pro-team: '*'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About billing for {{ site.data.variables.product.prodname_actions }} ### About billing for {% data variables.product.prodname_actions %}
{{ site.data.reusables.github-actions.actions-billing }} For more information, see "[About billing for {{ site.data.variables.product.prodname_actions }}](/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions)." {% data reusables.github-actions.actions-billing %} For more information, see "[About billing for {% data variables.product.prodname_actions %}](/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions)."
### Usage limits ### Usage limits
There are some limits on {{ site.data.variables.product.prodname_actions }} usage when using {{ site.data.variables.product.prodname_dotcom }}-hosted runners. These limits are subject to change. There are some limits on {% data variables.product.prodname_actions %} usage when using {% data variables.product.prodname_dotcom %}-hosted runners. These limits are subject to change.
{% note %} {% note %}
@@ -26,8 +26,8 @@ There are some limits on {{ site.data.variables.product.prodname_actions }} usag
{% endnote %} {% endnote %}
- **Job execution time** - Each job in a workflow can run for up to 6 hours of execution time. If a job reaches this limit, the job is terminated and fails to complete. - **Job execution time** - Each job in a workflow can run for up to 6 hours of execution time. If a job reaches this limit, the job is terminated and fails to complete.
{{ site.data.reusables.github-actions.usage-workflow-run-time }} {% data reusables.github-actions.usage-workflow-run-time %}
{{ site.data.reusables.github-actions.usage-api-requests }} {% data reusables.github-actions.usage-api-requests %}
- **Concurrent jobs** - The number of concurrent jobs you can run in your account depends on your GitHub plan, as indicated in the following table. If exceeded, any additional jobs are queued. - **Concurrent jobs** - The number of concurrent jobs you can run in your account depends on your GitHub plan, as indicated in the following table. If exceeded, any additional jobs are queued.
| GitHub plan | Total concurrent jobs | Maximum concurrent macOS jobs | | GitHub plan | Total concurrent jobs | Maximum concurrent macOS jobs |
@@ -36,14 +36,14 @@ There are some limits on {{ site.data.variables.product.prodname_actions }} usag
| Pro | 40 | 5 | | Pro | 40 | 5 |
| Team | 60 | 5 | | Team | 60 | 5 |
| Enterprise | 180 | 50 | | Enterprise | 180 | 50 |
- **Job matrix** - {{ site.data.reusables.github-actions.usage-matrix-limits }} - **Job matrix** - {% data reusables.github-actions.usage-matrix-limits %}
### Usage policy ### Usage policy
In addition to the usage limits, you must ensure that you use {{ site.data.variables.product.prodname_actions }} within the [GitHub Terms of Service](/articles/github-terms-of-service/). For more information on {{ site.data.variables.product.prodname_actions }}-specific terms, see the [GitHub Additional Product Terms](/github/site-policy/github-additional-product-terms#a-actions-usage). In addition to the usage limits, you must ensure that you use {% data variables.product.prodname_actions %} within the [GitHub Terms of Service](/articles/github-terms-of-service/). For more information on {% data variables.product.prodname_actions %}-specific terms, see the [GitHub Additional Product Terms](/github/site-policy/github-additional-product-terms#a-actions-usage).
### Disabling or limiting {{ site.data.variables.product.prodname_actions }} for your repository or organization ### Disabling or limiting {% data variables.product.prodname_actions %} for your repository or organization
{{ site.data.reusables.github-actions.disabling-github-actions }} {% data reusables.github-actions.disabling-github-actions %}
For more information, see "[Disabling or limiting {{ site.data.variables.product.prodname_actions }} for a repository](/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository)" or "[Disabling or limiting {{ site.data.variables.product.prodname_actions }} for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-or-limiting-github-actions-for-your-organization)." For more information, see "[Disabling or limiting {% data variables.product.prodname_actions %} for a repository](/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository)" or "[Disabling or limiting {% data variables.product.prodname_actions %} for your organization](/github/setting-up-and-managing-organizations-and-teams/disabling-or-limiting-github-actions-for-your-organization)."

10
content/actions/reference/workflow-commands-for-github-actions.md
View File

@@ -2,7 +2,7 @@
title: Workflow commands for GitHub Actions title: Workflow commands for GitHub Actions
shortTitle: Workflow commands shortTitle: Workflow commands
intro: You can use workflow commands when running shell commands in a workflow or in an action's code. intro: You can use workflow commands when running shell commands in a workflow or in an action's code.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/development-tools-for-github-actions - /articles/development-tools-for-github-actions
- /github/automating-your-workflow-with-github-actions/development-tools-for-github-actions - /github/automating-your-workflow-with-github-actions/development-tools-for-github-actions
@@ -14,8 +14,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About workflow commands ### About workflow commands
@@ -93,7 +93,7 @@ echo "::set-env name=action_state::yellow"
Sets an action's output parameter. Sets an action's output parameter.
Optionally, you can also declare output parameters in an action's metadata file. For more information, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/articles/metadata-syntax-for-github-actions#outputs)." Optionally, you can also declare output parameters in an action's metadata file. For more information, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/articles/metadata-syntax-for-github-actions#outputs)."
#### Example #### Example
@@ -198,7 +198,7 @@ echo "::pause-logging::"
You can use the `save-state` command to create environment variables for sharing with your workflow's `pre:` or `post:` actions. For example, you can create a file with the `pre:` action, pass the file location to the `main:` action, and then use the `post:` action to delete the file. Alternatively, you could create a file with the `main:` action, pass the file location to the `post:` action, and also use the `post:` action to delete the file. You can use the `save-state` command to create environment variables for sharing with your workflow's `pre:` or `post:` actions. For example, you can create a file with the `pre:` action, pass the file location to the `main:` action, and then use the `post:` action to delete the file. Alternatively, you could create a file with the `main:` action, pass the file location to the `post:` action, and also use the `post:` action to delete the file.
If you have multiple `pre:` or `post:` actions, you can only access the saved value in the action where `save-state` was used. For more information on the `post:` action, see "[Metadata syntax for {{ site.data.variables.product.prodname_actions }}](/actions/creating-actions/metadata-syntax-for-github-actions#post)." If you have multiple `pre:` or `post:` actions, you can only access the saved value in the action where `save-state` was used. For more information on the `post:` action, see "[Metadata syntax for {% data variables.product.prodname_actions %}](/actions/creating-actions/metadata-syntax-for-github-actions#post)."
The `save-state` command can only be run within an action, and is not available to YAML files. The saved value is stored as an environment value with the `STATE_` prefix. The `save-state` command can only be run within an action, and is not available to YAML files. The saved value is stored as an environment value with the `STATE_` prefix.

114
content/actions/reference/workflow-syntax-for-github-actions.md
View File

@@ -2,7 +2,7 @@
title: Workflow syntax for GitHub Actions title: Workflow syntax for GitHub Actions
shortTitle: Workflow syntax shortTitle: Workflow syntax
intro: A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration. intro: A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration.
product: '{{ site.data.reusables.gated-features.actions }}' product: '{% data reusables.gated-features.actions %}'
redirect_from: redirect_from:
- /articles/workflow-syntax-for-github-actions - /articles/workflow-syntax-for-github-actions
- /github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions - /github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions
@@ -12,8 +12,8 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.actions.enterprise-beta }} {% data reusables.actions.enterprise-beta %}
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
### About YAML syntax for workflows ### About YAML syntax for workflows
@@ -23,13 +23,13 @@ You must store workflow files in the `.github/workflows` directory of your repos
### **`name`** ### **`name`**
The name of your workflow. {{ site.data.variables.product.prodname_dotcom }} displays the names of your workflows on your repository's actions page. If you omit `name`, {{ site.data.variables.product.prodname_dotcom }} sets it to the workflow file path relative to the root of the repository. The name of your workflow. {% data variables.product.prodname_dotcom %} displays the names of your workflows on your repository's actions page. If you omit `name`, {% data variables.product.prodname_dotcom %} sets it to the workflow file path relative to the root of the repository.
### **`on`** ### **`on`**
**Required** The name of the {{ site.data.variables.product.prodname_dotcom }} event that triggers the workflow. You can provide a single event `string`, `array` of events, `array` of event `types`, or an event configuration `map` that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see "[Events that trigger workflows](/articles/events-that-trigger-workflows)." **Required** The name of the {% data variables.product.prodname_dotcom %} event that triggers the workflow. You can provide a single event `string`, `array` of events, `array` of event `types`, or an event configuration `map` that schedules a workflow or restricts the execution of a workflow to specific files, tags, or branch changes. For a list of available events, see "[Events that trigger workflows](/articles/events-that-trigger-workflows)."
{{ site.data.reusables.github-actions.actions-on-examples }} {% data reusables.github-actions.actions-on-examples %}
### **`on.<event_name>.types`** ### **`on.<event_name>.types`**
@@ -120,7 +120,7 @@ The `paths-ignore` and `paths` keywords accept glob patterns that use the `*` an
#### Example ignoring paths #### Example ignoring paths
Anytime a path name matches a pattern in `paths-ignore`, the workflow will not run. {{ site.data.variables.product.prodname_dotcom }} evaluates patterns defined in `paths-ignore` against the path name. A workflow with the following path filter will only run on `push` events that include at least one file outside the `docs` directory at the root of the repository. Anytime a path name matches a pattern in `paths-ignore`, the workflow will not run. {% data variables.product.prodname_dotcom %} evaluates patterns defined in `paths-ignore` against the path name. A workflow with the following path filter will only run on `push` events that include at least one file outside the `docs` directory at the root of the repository.
```yaml ```yaml
on: on:
@@ -166,13 +166,13 @@ on:
{% note %} {% note %}
**Note:** If you push more than 1,000 commits, or if {{ site.data.variables.product.prodname_dotcom }} does not generate the diff due to a timeout (diffs that are too large diffs), the workflow will always run. **Note:** If you push more than 1,000 commits, or if {% data variables.product.prodname_dotcom %} does not generate the diff due to a timeout (diffs that are too large diffs), the workflow will always run.
{% endnote %} {% endnote %}
The filter determines if a workflow should run by evaluating the changed files and running them against the `paths-ignore` or `paths` list. If there are no files changed, the workflow will not run. The filter determines if a workflow should run by evaluating the changed files and running them against the `paths-ignore` or `paths` list. If there are no files changed, the workflow will not run.
{{ site.data.variables.product.prodname_dotcom }} generates the list of changed files using two-dot diffs for pushes and three-dot diffs for pull requests: {% data variables.product.prodname_dotcom %} generates the list of changed files using two-dot diffs for pushes and three-dot diffs for pull requests:
- **Pull requests:** Three-dot diffs are a comparison between the most recent version of the topic branch and the commit where the topic branch was last synced with the base branch. - **Pull requests:** Three-dot diffs are a comparison between the most recent version of the topic branch and the commit where the topic branch was last synced with the base branch.
- **Pushes to existing branches:** A two-dot diff compares the head and base SHAs directly with each other. - **Pushes to existing branches:** A two-dot diff compares the head and base SHAs directly with each other.
- **Pushes to new branches:** A two-dot diff against the parent of the ancestor of the deepest commit pushed. - **Pushes to new branches:** A two-dot diff against the parent of the ancestor of the deepest commit pushed.
@@ -181,7 +181,7 @@ For more information, see "[About comparing branches in pull requests](/articles
### **`on.schedule`** ### **`on.schedule`**
{{ site.data.reusables.repositories.actions-scheduled-workflow-example }} {% data reusables.repositories.actions-scheduled-workflow-example %}
For more information about cron syntax, see "[Events that trigger workflows](/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#scheduled-events)." For more information about cron syntax, see "[Events that trigger workflows](/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#scheduled-events)."
@@ -189,7 +189,7 @@ For more information about cron syntax, see "[Events that trigger workflows](/ac
A `map` of environment variables that are available to all jobs and steps in the workflow. You can also set environment variables that are only available to a job or step. For more information, see [`jobs.<job_id>.env`](#jobsjob_idenv) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv). A `map` of environment variables that are available to all jobs and steps in the workflow. You can also set environment variables that are only available to a job or step. For more information, see [`jobs.<job_id>.env`](#jobsjob_idenv) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv).
{{ site.data.reusables.repositories.actions-env-var-note }} {% data reusables.repositories.actions-env-var-note %}
#### Example #### Example
@@ -202,13 +202,13 @@ env:
A `map` of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, see [`jobs.<job_id>.defaults`](#jobsjob_iddefaults). A `map` of default settings that will apply to all jobs in the workflow. You can also set default settings that are only available to a job. For more information, see [`jobs.<job_id>.defaults`](#jobsjob_iddefaults).
{{ site.data.reusables.github-actions.defaults-override }} {% data reusables.github-actions.defaults-override %}
### **`defaults.run`** ### **`defaults.run`**
You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a workflow. You can also set default settings for `run` that are only available to a job. For more information, see [`jobs.<job_id>.defaults.run`](#jobsjob_iddefaultsrun). You cannot use contexts or expressions in this keyword. You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a workflow. You can also set default settings for `run` that are only available to a job. For more information, see [`jobs.<job_id>.defaults.run`](#jobsjob_iddefaultsrun). You cannot use contexts or expressions in this keyword.
{{ site.data.reusables.github-actions.defaults-override }} {% data reusables.github-actions.defaults-override %}
#### Example #### Example
@@ -225,9 +225,9 @@ A workflow run is made up of one or more jobs. Jobs run in parallel by default.
Each job runs in an environment specified by `runs-on`. Each job runs in an environment specified by `runs-on`.
You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {{ site.data.variables.product.prodname_dotcom }}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits. You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {% data variables.product.prodname_dotcom %}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits.
If you need to find the unique identifier of a job running in a workflow run, you can use the {{ site.data.variables.product.prodname_dotcom }} API. For more information, see "[Workflow Jobs](/v3/actions/workflow-jobs)." If you need to find the unique identifier of a job running in a workflow run, you can use the {% data variables.product.prodname_dotcom %} API. For more information, see "[Workflow Jobs](/v3/actions/workflow-jobs)."
### **`jobs.<job_id>`** ### **`jobs.<job_id>`**
@@ -245,7 +245,7 @@ jobs:
### **`jobs.<job_id>.name`** ### **`jobs.<job_id>.name`**
The name of the job displayed on {{ site.data.variables.product.prodname_dotcom }}. The name of the job displayed on {% data variables.product.prodname_dotcom %}.
### **`jobs.<job_id>.needs`** ### **`jobs.<job_id>.needs`**
@@ -272,19 +272,19 @@ The jobs in this example run sequentially:
### **`jobs.<job_id>.runs-on`** ### **`jobs.<job_id>.runs-on`**
**Required** The type of machine to run the job on. The machine can be either a {{ site.data.variables.product.prodname_dotcom }}-hosted runner or a self-hosted runner. **Required** The type of machine to run the job on. The machine can be either a {% data variables.product.prodname_dotcom %}-hosted runner or a self-hosted runner.
{{ site.data.reusables.actions.enterprise-github-hosted-runners }} {% data reusables.actions.enterprise-github-hosted-runners %}
#### {{ site.data.variables.product.prodname_dotcom }}-hosted runners #### {% data variables.product.prodname_dotcom %}-hosted runners
If you use a {{ site.data.variables.product.prodname_dotcom }}-hosted runner, each job runs in a fresh instance of a virtual environment specified by `runs-on`. If you use a {% data variables.product.prodname_dotcom %}-hosted runner, each job runs in a fresh instance of a virtual environment specified by `runs-on`.
Available {{ site.data.variables.product.prodname_dotcom }}-hosted runner types are: Available {% data variables.product.prodname_dotcom %}-hosted runner types are:
{{ site.data.reusables.github-actions.supported-github-runners }} {% data reusables.github-actions.supported-github-runners %}
{{ site.data.reusables.github-actions.ubuntu-runner-preview }} {% data reusables.github-actions.ubuntu-runner-preview %}
##### **Example** ##### **Example**
@@ -292,11 +292,11 @@ Available {{ site.data.variables.product.prodname_dotcom }}-hosted runner types
runs-on: ubuntu-latest runs-on: ubuntu-latest
``` ```
For more information, see "[Virtual environments for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/github/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)." For more information, see "[Virtual environments for {% data variables.product.prodname_dotcom %}-hosted runners](/github/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)."
#### Self-hosted runners #### Self-hosted runners
{{ site.data.reusables.github-actions.self-hosted-runner-labels-runs-on }} {% data reusables.github-actions.self-hosted-runner-labels-runs-on %}
##### **Example** ##### **Example**
@@ -310,9 +310,9 @@ For more information, see "[About self-hosted runners](/github/automating-your-w
A `map` of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see [`jobs.<job_id>.needs`](#jobsjob_idneeds). A `map` of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see [`jobs.<job_id>.needs`](#jobsjob_idneeds).
Job outputs are strings, and job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to {{ site.data.variables.product.prodname_actions }}. Job outputs are strings, and job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to {% data variables.product.prodname_actions %}.
To use job outputs in a dependent job, you can use the `needs` context. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions#needs-context)." To use job outputs in a dependent job, you can use the `needs` context. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#needs-context)."
#### **Example** #### **Example**
@@ -342,7 +342,7 @@ jobs:
A `map` of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see [`env`](#env) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv). A `map` of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see [`env`](#env) and [`jobs.<job_id>.steps.env`](#jobsjob_idstepsenv).
{{ site.data.reusables.repositories.actions-env-var-note }} {% data reusables.repositories.actions-env-var-note %}
#### **Example** #### **Example**
@@ -357,7 +357,7 @@ jobs:
A `map` of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow. For more information, see [`defaults`](#defaults). A `map` of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow. For more information, see [`defaults`](#defaults).
{{ site.data.reusables.github-actions.defaults-override }} {% data reusables.github-actions.defaults-override %}
### **`jobs.<job_id>.defaults.run`** ### **`jobs.<job_id>.defaults.run`**
@@ -365,7 +365,7 @@ Provide default `shell` and `working-directory` to all `run` steps in the job. C
You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a job. You can also set default settings for `run` for the entire workflow. For more information, see [`jobs.defaults.run`](#defaultsrun). You cannot use contexts or expressions in this keyword. You can provide default `shell` and `working-directory` options for all [`run`](#jobsjob_idstepsrun) steps in a job. You can also set default settings for `run` for the entire workflow. For more information, see [`jobs.defaults.run`](#defaultsrun). You cannot use contexts or expressions in this keyword.
{{ site.data.reusables.github-actions.defaults-override }} {% data reusables.github-actions.defaults-override %}
#### Example #### Example
@@ -383,13 +383,13 @@ jobs:
You can use the `if` conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional. You can use the `if` conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.
{{ site.data.reusables.github-actions.expression-syntax-if }} For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." {% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
### **`jobs.<job_id>.steps`** ### **`jobs.<job_id>.steps`**
A job contains a sequence of tasks called `steps`. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. {{ site.data.variables.product.prodname_dotcom }} provides built-in steps to set up and complete a job. A job contains a sequence of tasks called `steps`. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. {% data variables.product.prodname_dotcom %} provides built-in steps to set up and complete a job.
You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {{ site.data.variables.product.prodname_dotcom }}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits. You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "[Usage limits and billing](/actions/reference/usage-limits-billing-and-administration)" for {% data variables.product.prodname_dotcom %}-hosted runners and "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners/#usage-limits)" for self-hosted runner usage limits.
#### Example #### Example
@@ -417,13 +417,13 @@ jobs:
#### **`jobs.<job_id>.steps.id`** #### **`jobs.<job_id>.steps.id`**
A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." A unique identifier for the step. You can use the `id` to reference the step in contexts. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
#### **`jobs.<job_id>.steps.if`** #### **`jobs.<job_id>.steps.if`**
You can use the `if` conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional. You can use the `if` conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.
{{ site.data.reusables.github-actions.expression-syntax-if }} For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." {% data reusables.github-actions.expression-syntax-if %} For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
##### Example using contexts ##### Example using contexts
@@ -438,7 +438,7 @@ steps:
##### Example using status check functions ##### Example using status check functions
The `my backup step` only runs when the previous step of a job fails. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions)." The `my backup step` only runs when the previous step of a job fails. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions)."
```yaml ```yaml
steps: steps:
@@ -451,7 +451,7 @@ steps:
#### **`jobs.<job_id>.steps.name`** #### **`jobs.<job_id>.steps.name`**
A name for your step to display on {{ site.data.variables.product.prodname_dotcom }}. A name for your step to display on {% data variables.product.prodname_dotcom %}.
#### **`jobs.<job_id>.steps.uses`** #### **`jobs.<job_id>.steps.uses`**
@@ -484,7 +484,7 @@ steps:
`{owner}/{repo}@{ref}` `{owner}/{repo}@{ref}`
You can specific branch, ref, or SHA in a public {{ site.data.variables.product.prodname_dotcom }} repository. You can specific branch, ref, or SHA in a public {% data variables.product.prodname_dotcom %} repository.
```yaml ```yaml
jobs: jobs:
@@ -502,7 +502,7 @@ jobs:
`{owner}/{repo}/{path}@{ref}` `{owner}/{repo}/{path}@{ref}`
A subdirectory in a public {{ site.data.variables.product.prodname_dotcom }} repository at a specific branch, ref, or SHA. A subdirectory in a public {% data variables.product.prodname_dotcom %} repository at a specific branch, ref, or SHA.
```yaml ```yaml
jobs: jobs:
@@ -595,11 +595,11 @@ You can override the default shell settings in the runner's operating system usi
| Supported platform | `shell` parameter | Description | Command run internally | | Supported platform | `shell` parameter | Description | Command run internally |
|--------------------|-------------------|-------------|------------------------| |--------------------|-------------------|-------------|------------------------|
| All | `bash` | The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | `bash --noprofile --norc -eo pipefail {0}` | | All | `bash` | The default shell on non-Windows platforms with a fallback to `sh`. When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | `bash --noprofile --norc -eo pipefail {0}` |
| All | `pwsh` | The PowerShell Core. {{ site.data.variables.product.prodname_dotcom }} appends the extension `.ps1` to your script name. | `pwsh -command "& '{0}'"` | | All | `pwsh` | The PowerShell Core. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `pwsh -command "& '{0}'"` |
| All | `python` | Executes the python command. | `python {0}` | | All | `python` | Executes the python command. | `python {0}` |
| Linux / macOS | `sh` | The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path. | `sh -e {0}` | | Linux / macOS | `sh` | The fallback behavior for non-Windows platforms if no shell is provided and `bash` is not found in the path. | `sh -e {0}` |
| Windows | `cmd` | {{ site.data.variables.product.prodname_dotcom }} appends the extension `.cmd` to your script name and substitutes for `{0}`. | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`. | | Windows | `cmd` | {% data variables.product.prodname_dotcom %} appends the extension `.cmd` to your script name and substitutes for `{0}`. | `%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`. |
| Windows | `powershell` | This is the default shell used on Windows. The Desktop PowerShell. {{ site.data.variables.product.prodname_dotcom }} appends the extension `.ps1` to your script name. | `powershell -command "& '{0}'"`. | | Windows | `powershell` | This is the default shell used on Windows. The Desktop PowerShell. {% data variables.product.prodname_dotcom %} appends the extension `.ps1` to your script name. | `powershell -command "& '{0}'"`. |
##### Example running a script using bash ##### Example running a script using bash
@@ -641,11 +641,11 @@ steps:
##### Custom shell ##### Custom shell
You can set the `shell` value to a template string using `command […options] {0} [..more_options]`. {{ site.data.variables.product.prodname_dotcom }} interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at `{0}`. You can set the `shell` value to a template string using `command […options] {0} [..more_options]`. {% data variables.product.prodname_dotcom %} interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at `{0}`.
##### Exit codes and error action preference ##### Exit codes and error action preference
For built-in shell keywords, we provide the following defaults that are executed by {{ site.data.variables.product.prodname_dotcom }}-hosted runners. You should use these guidelines when running shell scripts. For built-in shell keywords, we provide the following defaults that are executed by {% data variables.product.prodname_dotcom %}-hosted runners. You should use these guidelines when running shell scripts.
- `bash`/`sh`: - `bash`/`sh`:
- Fail-fast behavior using `set -e o pipefail`: Default for `bash` and built-in `shell`. It is also the default when you don't provide an option on non-Windows platforms. - Fail-fast behavior using `set -e o pipefail`: Default for `bash` and built-in `shell`. It is also the default when you don't provide an option on non-Windows platforms.
@@ -683,7 +683,7 @@ jobs:
#### **`jobs.<job_id>.steps.with.args`** #### **`jobs.<job_id>.steps.with.args`**
A `string` that defines the inputs for a Docker container. {{ site.data.variables.product.prodname_dotcom }} passes the `args` to the container's `ENTRYPOINT` when the container starts up. An `array of strings` is not supported by this parameter. A `string` that defines the inputs for a Docker container. {% data variables.product.prodname_dotcom %} passes the `args` to the container's `ENTRYPOINT` when the container starts up. An `array of strings` is not supported by this parameter.
##### Example ##### Example
@@ -725,9 +725,9 @@ The `entrypoint` keyword is meant to use with Docker container actions, but you
Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see [`env`](#env) and [`jobs.<job_id>.env`](#jobsjob_idenv). Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see [`env`](#env) and [`jobs.<job_id>.env`](#jobsjob_idenv).
{{ site.data.reusables.repositories.actions-env-var-note }} {% data reusables.repositories.actions-env-var-note %}
Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the `secrets` context. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)" and "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the `secrets` context. For more information, see "[Using environment variables](/actions/automating-your-workflow-with-github-actions/using-environment-variables)" and "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
##### Example ##### Example
@@ -752,7 +752,7 @@ The maximum number of minutes to run the step before killing the process.
### **`jobs.<job_id>.timeout-minutes`** ### **`jobs.<job_id>.timeout-minutes`**
The maximum number of minutes to let a job run before {{ site.data.variables.product.prodname_dotcom }} automatically cancels it. Default: 360 The maximum number of minutes to let a job run before {% data variables.product.prodname_dotcom %} automatically cancels it. Default: 360
### **`jobs.<job_id>.strategy`** ### **`jobs.<job_id>.strategy`**
@@ -762,9 +762,9 @@ A strategy creates a build matrix for your jobs. You can define different variat
You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure. You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure.
{{ site.data.reusables.github-actions.usage-matrix-limits }} {% data reusables.github-actions.usage-matrix-limits %}
Each option you define in the `matrix` has a key and value. The keys you define become properties in the `matrix` context and you can reference the property in other areas of your workflow file. For example, if you define the key `os` that contains an array of operating systems, you can use the `matrix.os` property as the value of the `runs-on` keyword to create a job for each operating system. For more information, see "[Context and expression syntax for {{ site.data.variables.product.prodname_actions }}](/actions/reference/context-and-expression-syntax-for-github-actions)." Each option you define in the `matrix` has a key and value. The keys you define become properties in the `matrix` context and you can reference the property in other areas of your workflow file. For example, if you define the key `os` that contains an array of operating systems, you can use the `matrix.os` property as the value of the `runs-on` keyword to create a job for each operating system. For more information, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)."
The order that you define a `matrix` matters. The first option you define will be the first job that runs in your workflow. The order that you define a `matrix` matters. The first option you define will be the first job that runs in your workflow.
@@ -788,7 +788,7 @@ steps:
``` ```
{% endraw %} {% endraw %}
The `setup-node` action is the recommended way to configure a Node.js version when using {{ site.data.variables.product.prodname_dotcom }}-hosted runners. For more information, see the [`setup-node`](https://github.com/actions/setup-node) action. The `setup-node` action is the recommended way to configure a Node.js version when using {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see the [`setup-node`](https://github.com/actions/setup-node) action.
##### Example running with more than one operating system ##### Example running with more than one operating system
@@ -797,7 +797,7 @@ You can create a matrix to run workflows on more than one runner operating syste
- 2 operating systems specified in the `os` array - 2 operating systems specified in the `os` array
- 3 Node.js versions specified in the `node` array - 3 Node.js versions specified in the `node` array
{{ site.data.reusables.repositories.actions-matrix-builds-os }} {% data reusables.repositories.actions-matrix-builds-os %}
{% raw %} {% raw %}
```yaml ```yaml
@@ -813,7 +813,7 @@ steps:
``` ```
{% endraw %} {% endraw %}
To find supported configuration options for {{ site.data.variables.product.prodname_dotcom }}-hosted runners, see "[Virtual environments for {{ site.data.variables.product.prodname_dotcom }}-hosted runners](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)." To find supported configuration options for {% data variables.product.prodname_dotcom %}-hosted runners, see "[Virtual environments for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners)."
##### Example including additional values into combinations ##### Example including additional values into combinations
@@ -880,11 +880,11 @@ strategy:
### **`jobs.<job_id>.strategy.fail-fast`** ### **`jobs.<job_id>.strategy.fail-fast`**
When set to `true`, {{ site.data.variables.product.prodname_dotcom }} cancels all in-progress jobs if any `matrix` job fails. Default: `true` When set to `true`, {% data variables.product.prodname_dotcom %} cancels all in-progress jobs if any `matrix` job fails. Default: `true`
### **`jobs.<job_id>.strategy.max-parallel`** ### **`jobs.<job_id>.strategy.max-parallel`**
The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. By default, {{ site.data.variables.product.prodname_dotcom }} will maximize the number of jobs run in parallel depending on the available runners on {{ site.data.variables.product.prodname_dotcom }}-hosted virtual machines. The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. By default, {% data variables.product.prodname_dotcom %} will maximize the number of jobs run in parallel depending on the available runners on {% data variables.product.prodname_dotcom %}-hosted virtual machines.
```yaml ```yaml
strategy: strategy:
@@ -1001,7 +1001,7 @@ Additional Docker container resource options. For a list of options, see "[`dock
### **`jobs.<job_id>.services`** ### **`jobs.<job_id>.services`**
{{ site.data.reusables.github-actions.docker-container-os-support }} {% data reusables.github-actions.docker-container-os-support %}
Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers. Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.
@@ -1013,7 +1013,7 @@ For more information about the differences between networking service containers
#### Example using localhost #### Example using localhost
This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. {{ site.data.variables.product.prodname_dotcom }} sets the assigned container port in the {% raw %}`${{job.services.<service_name>.ports}}`{% endraw %} context. In this example, you can access the service container ports using the {% raw %}`${{ job.services.nginx.ports['8080'] }}`{% endraw %} and {% raw %}`${{ job.services.redis.ports['6379'] }}`{% endraw %} contexts. This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. {% data variables.product.prodname_dotcom %} sets the assigned container port in the {% raw %}`${{job.services.<service_name>.ports}}`{% endraw %} context. In this example, you can access the service container ports using the {% raw %}`${{ job.services.nginx.ports['8080'] }}`{% endraw %} and {% raw %}`${{ job.services.redis.ports['6379'] }}`{% endraw %} contexts.
```yaml ```yaml
services: services:

18
content/admin/authentication/allowing-built-in-authentication-for-users-outside-your-identity-provider.md
View File

@@ -24,26 +24,26 @@ Built-in authentication for a specific IdP is disabled by default.
### Configuring built-in authentication for users outside your identity provider ### Configuring built-in authentication for users outside your identity provider
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.authentication }} {% data reusables.enterprise_management_console.authentication %}
4. Select your identity provider. 4. Select your identity provider.
![Select identity provider option](/assets/images/enterprise/management-console/identity-provider-select.gif) ![Select identity provider option](/assets/images/enterprise/management-console/identity-provider-select.gif)
5. Select **Allow creation of accounts with built-in authentication**. 5. Select **Allow creation of accounts with built-in authentication**.
![Select built-in authentication option](/assets/images/enterprise/management-console/built-in-auth-identity-provider-select.png) ![Select built-in authentication option](/assets/images/enterprise/management-console/built-in-auth-identity-provider-select.png)
6. Read the warning, then click **Ok**. 6. Read the warning, then click **Ok**.
{{ site.data.reusables.enterprise_user_management.two_factor_auth_header }} {% data reusables.enterprise_user_management.two_factor_auth_header %}
{{ site.data.reusables.enterprise_user_management.2fa_is_available }} {% data reusables.enterprise_user_management.2fa_is_available %}
### Inviting users outside your identity provider to authenticate to your instance ### Inviting users outside your identity provider to authenticate to your instance
When a user accepts the invitation, they can use their username and password to sign in rather than signing in through the IdP. When a user accepts the invitation, they can use their username and password to sign in rather than signing in through the IdP.
{{ site.data.reusables.enterprise_site_admin_settings.sign-in }} {% data reusables.enterprise_site_admin_settings.sign-in %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.invite-user-sidebar-tab }} {% data reusables.enterprise_site_admin_settings.invite-user-sidebar-tab %}
{{ site.data.reusables.enterprise_site_admin_settings.invite-user-reset-link }} {% data reusables.enterprise_site_admin_settings.invite-user-reset-link %}
### Further reading ### Further reading

2
content/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Authenticating users for your GitHub Enterprise Server instance title: Authenticating users for your GitHub Enterprise Server instance
intro: 'You can use {{ site.data.variables.product.prodname_ghe_server }}''s built-in authentication, or choose between CAS, LDAP, or SAML to integrate your existing accounts and centrally manage user access to {{ site.data.variables.product.product_location_enterprise }}.' intro: 'You can use {% data variables.product.prodname_ghe_server %}''s built-in authentication, or choose between CAS, LDAP, or SAML to integrate your existing accounts and centrally manage user access to {% data variables.product.product_location_enterprise %}.'
redirect_from: redirect_from:
- /enterprise/admin/categories/authentication/ - /enterprise/admin/categories/authentication/
- /enterprise/admin/guides/installation/user-authentication/ - /enterprise/admin/guides/installation/user-authentication/

10
content/admin/authentication/changing-authentication-methods.md
View File

@@ -1,13 +1,13 @@
--- ---
title: Changing authentication methods title: Changing authentication methods
intro: 'You can change the way {{ site.data.variables.product.prodname_ghe_server }} authenticates with your existing accounts at any time.' intro: 'You can change the way {% data variables.product.prodname_ghe_server %} authenticates with your existing accounts at any time.'
redirect_from: redirect_from:
- /enterprise/admin/user-management/changing-authentication-methods - /enterprise/admin/user-management/changing-authentication-methods
- /enterprise/admin/authentication/changing-authentication-methods - /enterprise/admin/authentication/changing-authentication-methods
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
User accounts on {{ site.data.variables.product.product_location_enterprise }} are preserved when you change the authentication method and users will continue to log into the same account as long as their username doesn't change. User accounts on {% data variables.product.product_location_enterprise %} are preserved when you change the authentication method and users will continue to log into the same account as long as their username doesn't change.
If the new method of authentication changes usernames, new accounts will be created. As an administrator, you can rename users through the site admin settings or by using [the User Administration API](/enterprise/{{currentVersion}}/v3/enterprise-admin/users/#rename-an-existing-user). If the new method of authentication changes usernames, new accounts will be created. As an administrator, you can rename users through the site admin settings or by using [the User Administration API](/enterprise/{{currentVersion}}/v3/enterprise-admin/users/#rename-an-existing-user).
@@ -19,7 +19,7 @@ Other issues you should take into consideration include:
* **Team membership:** Only LDAP lets you [control team membership](/enterprise/admin/authentication/using-ldap#configuring-ldap-with-your-github-enterprise-server-instance) from your directory server. * **Team membership:** Only LDAP lets you [control team membership](/enterprise/admin/authentication/using-ldap#configuring-ldap-with-your-github-enterprise-server-instance) from your directory server.
* **User suspension:** When you use LDAP to authenticate, access to {{ site.data.variables.product.prodname_ghe_server }} can be controlled via _restricted groups_. After switching to LDAP, if restricted groups are configured, existing users who are not in one of those groups will be suspended. Suspension will occur either when they log in or during the next LDAP Sync. * **User suspension:** When you use LDAP to authenticate, access to {% data variables.product.prodname_ghe_server %} can be controlled via _restricted groups_. After switching to LDAP, if restricted groups are configured, existing users who are not in one of those groups will be suspended. Suspension will occur either when they log in or during the next LDAP Sync.
* **Group membership:** When you use LDAP to authenticate, users are automatically [suspended and unsuspended](/enterprise/admin/guides/user-management/suspending-and-unsuspending-users) based on restricted group membership and account status with Active Directory. * **Group membership:** When you use LDAP to authenticate, users are automatically [suspended and unsuspended](/enterprise/admin/guides/user-management/suspending-and-unsuspending-users) based on restricted group membership and account status with Active Directory.
@@ -27,6 +27,6 @@ Other issues you should take into consideration include:
* **API authentication:** SAML and CAS only supports API authentication using a [personal access token](/articles/creating-an-access-token-for-command-line-use). Basic authentication is not supported. * **API authentication:** SAML and CAS only supports API authentication using a [personal access token](/articles/creating-an-access-token-for-command-line-use). Basic authentication is not supported.
* **Two-factor authentication:** {{ site.data.reusables.enterprise_user_management.external_auth_disables_2fa }} * **Two-factor authentication:** {% data reusables.enterprise_user_management.external_auth_disables_2fa %}
* **Built-in authentication for users outside your identity provider:** You can invite users to authenticate to {{ site.data.variables.product.product_location_enterprise }} without adding them to your identity provider. For more information, see "[Allowing built-in authentication for users outside your identity provider](/enterprise/{{ currentVersion }}/admin/guides/user-management/allowing-built-in-authentication-for-users-outside-your-identity-provider)." * **Built-in authentication for users outside your identity provider:** You can invite users to authenticate to {% data variables.product.product_location_enterprise %} without adding them to your identity provider. For more information, see "[Allowing built-in authentication for users outside your identity provider](/enterprise/{{ currentVersion }}/admin/guides/user-management/allowing-built-in-authentication-for-users-outside-your-identity-provider)."

8
content/admin/authentication/disabling-unauthenticated-sign-ups.md
View File

@@ -9,9 +9,9 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.privacy }} {% data reusables.enterprise_management_console.privacy %}
3. Unselect **Enable sign-up**. 3. Unselect **Enable sign-up**.
![Enable sign-up checkbox](/assets/images/enterprise/management-console/enable-sign-up.png) ![Enable sign-up checkbox](/assets/images/enterprise/management-console/enable-sign-up.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}

2
content/admin/authentication/index.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Authentication title: Authentication
intro: 'You can use {{ site.data.variables.product.prodname_ghe_server }}''s built-in authentication, or choose between CAS, LDAP, or SAML to integrate your existing accounts and centrally manage user access to {{ site.data.variables.product.product_location_enterprise }}.' intro: 'You can use {% data variables.product.prodname_ghe_server %}''s built-in authentication, or choose between CAS, LDAP, or SAML to integrate your existing accounts and centrally manage user access to {% data variables.product.product_location_enterprise %}.'
redirect_from: redirect_from:
- /enterprise/admin/authentication - /enterprise/admin/authentication
versions: versions:

20
content/admin/authentication/using-built-in-authentication.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Using built-in authentication title: Using built-in authentication
intro: 'When you use the default authentication method, all authentication details are stored within {{ site.data.variables.product.product_location_enterprise }}. Built-in authentication is the default method if you don’t already have an established authentication provider, such as LDAP, SAML, or CAS.' intro: 'When you use the default authentication method, all authentication details are stored within {% data variables.product.product_location_enterprise %}. Built-in authentication is the default method if you don’t already have an established authentication provider, such as LDAP, SAML, or CAS.'
redirect_from: redirect_from:
- /enterprise/admin/user-management/using-built-in-authentication - /enterprise/admin/user-management/using-built-in-authentication
- /enterprise/admin/authentication/using-built-in-authentication - /enterprise/admin/authentication/using-built-in-authentication
@@ -12,14 +12,14 @@ You can create custom messages that users will see on the sign in and sign out p
### Configuring built-in authentication ### Configuring built-in authentication
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.authentication }} {% data reusables.enterprise_management_console.authentication %}
4. Select **Built in authentication**. 4. Select **Built in authentication**.
![Select built-in authentication option](/assets/images/enterprise/management-console/built-in-auth-select.png) ![Select built-in authentication option](/assets/images/enterprise/management-console/built-in-auth-select.png)
{{ site.data.reusables.enterprise_user_management.two_factor_auth_header }} {% data reusables.enterprise_user_management.two_factor_auth_header %}
{{ site.data.reusables.enterprise_user_management.2fa_is_available }} {% data reusables.enterprise_user_management.2fa_is_available %}
### Creating your account and adding users ### Creating your account and adding users
@@ -27,7 +27,7 @@ Once your instance has been created, you'll need to create your own admin accoun
1. On the "Create Admin Account" page at `http(s)://[hostname]/join`, choose your username, password, and email address, then click **Create an account**. 1. On the "Create Admin Account" page at `http(s)://[hostname]/join`, choose your username, password, and email address, then click **Create an account**.
![Create Admin Account](/assets/images/enterprise/site-admin-settings/create-first-admin-acct.png) ![Create Admin Account](/assets/images/enterprise/site-admin-settings/create-first-admin-acct.png)
{{ site.data.reusables.enterprise_site_admin_settings.sign-in }} {% data reusables.enterprise_site_admin_settings.sign-in %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.invite-user-sidebar-tab }} {% data reusables.enterprise_site_admin_settings.invite-user-sidebar-tab %}
{{ site.data.reusables.enterprise_site_admin_settings.invite-user-reset-link }} {% data reusables.enterprise_site_admin_settings.invite-user-reset-link %}

24
content/admin/authentication/using-cas.md
View File

@@ -10,16 +10,16 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
{{ site.data.reusables.enterprise_user_management.built-in-authentication }} {% data reusables.enterprise_user_management.built-in-authentication %}
### Username considerations with CAS ### Username considerations with CAS
{{ site.data.reusables.enterprise_management_console.username_normalization }} {% data reusables.enterprise_management_console.username_normalization %}
{{ site.data.reusables.enterprise_management_console.username_normalization_sample }} {% data reusables.enterprise_management_console.username_normalization_sample %}
{{ site.data.reusables.enterprise_user_management.two_factor_auth_header }} {% data reusables.enterprise_user_management.two_factor_auth_header %}
{{ site.data.reusables.enterprise_user_management.external_auth_disables_2fa }} {% data reusables.enterprise_user_management.external_auth_disables_2fa %}
### CAS attributes ### CAS attributes
@@ -27,19 +27,19 @@ The following attributes are available.
| Attribute name | Type | Description | | Attribute name | Type | Description |
|--------------------------|----------|-------------| |--------------------------|----------|-------------|
| `username` | Required | The {{ site.data.variables.product.prodname_ghe_server }} username. | | `username` | Required | The {% data variables.product.prodname_ghe_server %} username. |
### Configuring CAS ### Configuring CAS
{% warning %} {% warning %}
**Warning:** Before configuring CAS on {{ site.data.variables.product.product_location_enterprise }}, note that users will not be able to use their CAS usernames and passwords to authenticate API requests or Git operations over HTTP/HTTPS. Instead, they will need to [create an access token](/enterprise/{{ currentVersion }}/user/articles/creating-an-access-token-for-command-line-use). **Warning:** Before configuring CAS on {% data variables.product.product_location_enterprise %}, note that users will not be able to use their CAS usernames and passwords to authenticate API requests or Git operations over HTTP/HTTPS. Instead, they will need to [create an access token](/enterprise/{{ currentVersion }}/user/articles/creating-an-access-token-for-command-line-use).
{% endwarning %} {% endwarning %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.authentication }} {% data reusables.enterprise_management_console.authentication %}
3. Select **CAS**. 3. Select **CAS**.
![CAS select](/assets/images/enterprise/management-console/cas-select.png) ![CAS select](/assets/images/enterprise/management-console/cas-select.png)
4. {{ site.data.reusables.enterprise_user_management.built-in-authentication-option }} ![Select CAS built-in authentication checkbox](/assets/images/enterprise/management-console/cas-built-in-authentication.png) 4. {% data reusables.enterprise_user_management.built-in-authentication-option %} ![Select CAS built-in authentication checkbox](/assets/images/enterprise/management-console/cas-built-in-authentication.png)
5. In the **Server URL** field, type the full URL of your CAS server. If your CAS server uses a certificate that can't be validated by {{ site.data.variables.product.prodname_ghe_server }}, you can use the `ghe-ssl-ca-certificate-install` command to install it as a trusted certificate. 5. In the **Server URL** field, type the full URL of your CAS server. If your CAS server uses a certificate that can't be validated by {% data variables.product.prodname_ghe_server %}, you can use the `ghe-ssl-ca-certificate-install` command to install it as a trusted certificate.

82
content/admin/authentication/using-ldap.md
View File

@@ -8,16 +8,16 @@ redirect_from:
- /enterprise/admin/hidden/ldap-sync/ - /enterprise/admin/hidden/ldap-sync/
- /enterprise/admin/user-management/using-ldap - /enterprise/admin/user-management/using-ldap
- /enterprise/admin/authentication/using-ldap - /enterprise/admin/authentication/using-ldap
intro: 'LDAP lets you authenticate {{ site.data.variables.product.prodname_ghe_server }} against your existing accounts and centrally manage repository access. LDAP is a popular application protocol for accessing and maintaining directory information services, and is one of the most common protocols used to integrate third-party software with large company user directories.' intro: 'LDAP lets you authenticate {% data variables.product.prodname_ghe_server %} against your existing accounts and centrally manage repository access. LDAP is a popular application protocol for accessing and maintaining directory information services, and is one of the most common protocols used to integrate third-party software with large company user directories.'
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
{{ site.data.reusables.enterprise_user_management.built-in-authentication }} {% data reusables.enterprise_user_management.built-in-authentication %}
### Supported LDAP services ### Supported LDAP services
{{ site.data.variables.product.prodname_ghe_server }} integrates with these LDAP services: {% data variables.product.prodname_ghe_server %} integrates with these LDAP services:
* Active Directory * Active Directory
* FreeIPA * FreeIPA
@@ -28,51 +28,51 @@ versions:
### Username considerations with LDAP ### Username considerations with LDAP
{{ site.data.reusables.enterprise_management_console.username_normalization }} {% data reusables.enterprise_management_console.username_normalization %}
{{ site.data.reusables.enterprise_management_console.username_normalization_sample }} {% data reusables.enterprise_management_console.username_normalization_sample %}
{{ site.data.reusables.enterprise_user_management.two_factor_auth_header }} {% data reusables.enterprise_user_management.two_factor_auth_header %}
{{ site.data.reusables.enterprise_user_management.2fa_is_available }} {% data reusables.enterprise_user_management.2fa_is_available %}
### Configuring LDAP with {{ site.data.variables.product.product_location_enterprise }} ### Configuring LDAP with {% data variables.product.product_location_enterprise %}
After you configure LDAP, users will be able to sign into your instance with their LDAP credentials. When users sign in for the first time, their profile names, email addresses, and SSH keys will be set with the LDAP attributes from your directory. After you configure LDAP, users will be able to sign into your instance with their LDAP credentials. When users sign in for the first time, their profile names, email addresses, and SSH keys will be set with the LDAP attributes from your directory.
When you configure LDAP access for users via the {{ site.data.variables.enterprise.management_console }}, your user licenses aren't used until the first time a user signs in to your instance. However, if you create an account manually using site admin settings, the user license is immediately accounted for. When you configure LDAP access for users via the {% data variables.enterprise.management_console %}, your user licenses aren't used until the first time a user signs in to your instance. However, if you create an account manually using site admin settings, the user license is immediately accounted for.
{% warning %} {% warning %}
**Warning:** Before configuring LDAP on {{ site.data.variables.product.product_location_enterprise }}, make sure that your LDAP service supports paged results. **Warning:** Before configuring LDAP on {% data variables.product.product_location_enterprise %}, make sure that your LDAP service supports paged results.
{% endwarning %} {% endwarning %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.authentication }} {% data reusables.enterprise_management_console.authentication %}
3. Under "Authentication", select **LDAP**. 3. Under "Authentication", select **LDAP**.
![LDAP select](/assets/images/enterprise/management-console/ldap-select.png) ![LDAP select](/assets/images/enterprise/management-console/ldap-select.png)
4. {{ site.data.reusables.enterprise_user_management.built-in-authentication-option }} ![Select LDAP built-in authentication checkbox](/assets/images/enterprise/management-console/ldap-built-in-authentication.png) 4. {% data reusables.enterprise_user_management.built-in-authentication-option %} ![Select LDAP built-in authentication checkbox](/assets/images/enterprise/management-console/ldap-built-in-authentication.png)
5. Add your configuration settings. 5. Add your configuration settings.
### LDAP attributes ### LDAP attributes
Use these attributes to finish configuring LDAP for {{ site.data.variables.product.product_location_enterprise }}. Use these attributes to finish configuring LDAP for {% data variables.product.product_location_enterprise %}.
| Attribute name | Type | Description | | Attribute name | Type | Description |
|--------------------------|----------|-------------| |--------------------------|----------|-------------|
| `Host` | Required | The LDAP host, e.g. `ldap.example.com` or `10.0.0.30`. If the hostname is only available from your internal network, you may need to configure {{ site.data.variables.product.product_location_enterprise }}'s DNS first so it can resolve the hostname using your internal nameservers. | | `Host` | Required | The LDAP host, e.g. `ldap.example.com` or `10.0.0.30`. If the hostname is only available from your internal network, you may need to configure {% data variables.product.product_location_enterprise %}'s DNS first so it can resolve the hostname using your internal nameservers. |
| `Port` | Required | The port the host's LDAP services are listening on. Examples include: 389 and 636 (for LDAPS). | | `Port` | Required | The port the host's LDAP services are listening on. Examples include: 389 and 636 (for LDAPS). |
| `Encryption` | Required | The encryption method used to secure communications to the LDAP server. Examples include plain (no encryption), SSL/LDAPS (encrypted from the start), and StartTLS (upgrade to encrypted communication once connected). | | `Encryption` | Required | The encryption method used to secure communications to the LDAP server. Examples include plain (no encryption), SSL/LDAPS (encrypted from the start), and StartTLS (upgrade to encrypted communication once connected). |
| `Domain search user` | Optional | The LDAP user that performs user lookups to authenticate other users when they sign in. This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as `cn=Administrator,cn=Users,dc=Example,dc=com`. With Active Directory, you can also use the `[DOMAIN]\[USERNAME]` syntax (e.g. `WINDOWS\Administrator`) for the domain search user with Active Directory. | | `Domain search user` | Optional | The LDAP user that performs user lookups to authenticate other users when they sign in. This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as `cn=Administrator,cn=Users,dc=Example,dc=com`. With Active Directory, you can also use the `[DOMAIN]\[USERNAME]` syntax (e.g. `WINDOWS\Administrator`) for the domain search user with Active Directory. |
| `Domain search password` | Optional | The password for the domain search user. | | `Domain search password` | Optional | The password for the domain search user. |
| `Administrators group` | Optional | Users in this group are promoted to site administrators when signing into your appliance. If you don't configure an LDAP Administrators group, the first LDAP user account that signs into your appliance will be automatically promoted to a site administrator. | | `Administrators group` | Optional | Users in this group are promoted to site administrators when signing into your appliance. If you don't configure an LDAP Administrators group, the first LDAP user account that signs into your appliance will be automatically promoted to a site administrator. |
| `Domain base` | Required | The fully qualified `Distinguished Name` (DN) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. If you specify restricted user groups, only users that belong to those groups will be in scope. We recommend that you specify the top level of your LDAP directory tree as your domain base and use restricted user groups to control access. | | `Domain base` | Required | The fully qualified `Distinguished Name` (DN) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. If you specify restricted user groups, only users that belong to those groups will be in scope. We recommend that you specify the top level of your LDAP directory tree as your domain base and use restricted user groups to control access. |
| `Restricted user groups` | Optional | If specified, only users in these groups will be allowed to log in. You only need to specify the common names (CNs) of the groups, and you can add as many groups as you like. If no groups are specified, *all* users within the scope of the specified domain base will be able to sign in to your {{ site.data.variables.product.prodname_ghe_server }} instance. | | `Restricted user groups` | Optional | If specified, only users in these groups will be allowed to log in. You only need to specify the common names (CNs) of the groups, and you can add as many groups as you like. If no groups are specified, *all* users within the scope of the specified domain base will be able to sign in to your {% data variables.product.prodname_ghe_server %} instance. |
| `User ID` | Required | The LDAP attribute that identifies the LDAP user who attempts authentication. Once a mapping is established, users may change their {{ site.data.variables.product.prodname_ghe_server }} usernames. This field should be `sAMAccountName` for most Active Directory installations, but it may be `uid` for other LDAP solutions, such as OpenLDAP. The default value is `uid`. | | `User ID` | Required | The LDAP attribute that identifies the LDAP user who attempts authentication. Once a mapping is established, users may change their {% data variables.product.prodname_ghe_server %} usernames. This field should be `sAMAccountName` for most Active Directory installations, but it may be `uid` for other LDAP solutions, such as OpenLDAP. The default value is `uid`. |
| `Profile name` | Optional | The name that will appear on the user's {{ site.data.variables.product.prodname_ghe_server }} profile page. Unless LDAP Sync is enabled, users may change their profile names. | | `Profile name` | Optional | The name that will appear on the user's {% data variables.product.prodname_ghe_server %} profile page. Unless LDAP Sync is enabled, users may change their profile names. |
| `Emails` | Optional | The email addresses for a user's {{ site.data.variables.product.prodname_ghe_server }} account. | | `Emails` | Optional | The email addresses for a user's {% data variables.product.prodname_ghe_server %} account. |
| `SSH keys` | Optional | The public SSH keys attached to a user's {{ site.data.variables.product.prodname_ghe_server }} account. The keys must be in OpenSSH format. | | `SSH keys` | Optional | The public SSH keys attached to a user's {% data variables.product.prodname_ghe_server %} account. The keys must be in OpenSSH format. |
| `GPG keys` | Optional | The GPG keys attached to a user's {{ site.data.variables.product.prodname_ghe_server }} account. | | `GPG keys` | Optional | The GPG keys attached to a user's {% data variables.product.prodname_ghe_server %} account. |
| `Disable LDAP authentication for Git operations` | Optional |If selected, [turns off](#disabling-password-authentication-for-git-operations) users' ability to use LDAP passwords to authenticate Git operations. | | `Disable LDAP authentication for Git operations` | Optional |If selected, [turns off](#disabling-password-authentication-for-git-operations) users' ability to use LDAP passwords to authenticate Git operations. |
| `Enable LDAP certificate verification` | Optional |If selected, [turns on](#enabling-ldap-certificate-verification) LDAP certificate verification. | | `Enable LDAP certificate verification` | Optional |If selected, [turns on](#enabling-ldap-certificate-verification) LDAP certificate verification. |
| `Synchronization` | Optional |If selected, [turns on](#enabling-ldap-sync) LDAP Sync. | | `Synchronization` | Optional |If selected, [turns on](#enabling-ldap-sync) LDAP Sync. |
@@ -98,7 +98,7 @@ When this option is selected, the certificate is validated to make sure:
#### Enabling LDAP Sync #### Enabling LDAP Sync
LDAP Sync lets you synchronize {{ site.data.variables.product.prodname_ghe_server }} users and team membership against your established LDAP groups. This lets you establish role-based access control for users from your LDAP server instead of manually within {{ site.data.variables.product.prodname_ghe_server }}. For more information, see "[Creating teams](/enterprise/{{ currentVersion }}/admin/guides/user-management/creating-teams#creating-teams-with-ldap-sync-enabled)." LDAP Sync lets you synchronize {% data variables.product.prodname_ghe_server %} users and team membership against your established LDAP groups. This lets you establish role-based access control for users from your LDAP server instead of manually within {% data variables.product.prodname_ghe_server %}. For more information, see "[Creating teams](/enterprise/{{ currentVersion }}/admin/guides/user-management/creating-teams#creating-teams-with-ldap-sync-enabled)."
To enable LDAP Sync, in your LDAP settings, select **Synchronize Emails**, **Synchronize SSH Keys**, or **Synchronize GPG Keys** . To enable LDAP Sync, in your LDAP settings, select **Synchronize Emails**, **Synchronize SSH Keys**, or **Synchronize GPG Keys** .
@@ -130,7 +130,7 @@ A synchronization job will also run at the specified time interval to perform th
- If LDAP member entries have been removed from the LDAP group, remove the corresponding users from the team. If the user loses access to any repositories as a result, delete any private forks the user has of those repositories. - If LDAP member entries have been removed from the LDAP group, remove the corresponding users from the team. If the user loses access to any repositories as a result, delete any private forks the user has of those repositories.
- If LDAP member entries have been added to the LDAP group, add the corresponding users to the team. If the user regains access to any repositories as a result, restore any private forks of the repositories that were deleted because the user lost access in the past 90 days. - If LDAP member entries have been added to the LDAP group, add the corresponding users to the team. If the user regains access to any repositories as a result, restore any private forks of the repositories that were deleted because the user lost access in the past 90 days.
{{ site.data.reusables.enterprise_user_management.ldap-sync-nested-teams }} {% data reusables.enterprise_user_management.ldap-sync-nested-teams %}
{% warning %} {% warning %}
@@ -141,15 +141,15 @@ When LDAP Sync is enabled, site admins and organization owners can search the LD
This has the potential to disclose sensitive organizational information to contractors or other unprivileged users, including: This has the potential to disclose sensitive organizational information to contractors or other unprivileged users, including:
- The existence of specific LDAP Groups visible to the *Domain search user*. - The existence of specific LDAP Groups visible to the *Domain search user*.
- Members of the LDAP group who have {{ site.data.variables.product.prodname_ghe_server }} user accounts, which is disclosed when creating a team synced with that LDAP group. - Members of the LDAP group who have {% data variables.product.prodname_ghe_server %} user accounts, which is disclosed when creating a team synced with that LDAP group.
If disclosing such information is not desired, your company or organization should restrict the permissions of the configured *Domain search user* in the admin console. If such restriction isn't possible, contact {{ site.data.variables.contact.contact_ent_support }}. If disclosing such information is not desired, your company or organization should restrict the permissions of the configured *Domain search user* in the admin console. If such restriction isn't possible, contact {% data variables.contact.contact_ent_support %}.
{% endwarning %} {% endwarning %}
#### Supported LDAP group object classes #### Supported LDAP group object classes
{{ site.data.variables.product.prodname_ghe_server }} supports these LDAP group object classes. Groups can be nested. {% data variables.product.prodname_ghe_server %} supports these LDAP group object classes. Groups can be nested.
- `group` - `group`
- `groupOfNames` - `groupOfNames`
@@ -160,8 +160,8 @@ If disclosing such information is not desired, your company or organization shou
You can view the full list of LDAP users who have access to your instance and provision new users. You can view the full list of LDAP users who have access to your instance and provision new users.
{{ site.data.reusables.enterprise_site_admin_settings.sign-in }} {% data reusables.enterprise_site_admin_settings.sign-in %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
3. In the left sidebar, click **LDAP users**. 3. In the left sidebar, click **LDAP users**.
![LDAP users tab](/assets/images/enterprise/site-admin-settings/ldap-users-tab.png) ![LDAP users tab](/assets/images/enterprise/site-admin-settings/ldap-users-tab.png)
4. To search for a user, type a full or partial username and click **Search**. Existing users will be displayed in search results. If a user doesn’t exist, click **Create** to provision the new user account. 4. To search for a user, type a full or partial username and click **Search**. Existing users will be displayed in search results. If a user doesn’t exist, click **Create** to provision the new user account.
@@ -169,27 +169,27 @@ You can view the full list of LDAP users who have access to your instance and pr
### Updating LDAP accounts ### Updating LDAP accounts
Unless [LDAP Sync is enabled](#enabling-ldap-sync), changes to LDAP accounts are not automatically synchronized with {{ site.data.variables.product.prodname_ghe_server }}. Unless [LDAP Sync is enabled](#enabling-ldap-sync), changes to LDAP accounts are not automatically synchronized with {% data variables.product.prodname_ghe_server %}.
* To use a new LDAP admin group, users must be manually promoted and demoted on {{ site.data.variables.product.prodname_ghe_server }} to reflect changes in LDAP. * To use a new LDAP admin group, users must be manually promoted and demoted on {% data variables.product.prodname_ghe_server %} to reflect changes in LDAP.
* To add or remove LDAP accounts in LDAP admin groups, [promote or demote the accounts on {{ site.data.variables.product.prodname_ghe_server }}](/enterprise/{{ currentVersion }}/admin/guides/user-management/promoting-or-demoting-a-site-administrator). * To add or remove LDAP accounts in LDAP admin groups, [promote or demote the accounts on {% data variables.product.prodname_ghe_server %}](/enterprise/{{ currentVersion }}/admin/guides/user-management/promoting-or-demoting-a-site-administrator).
* To remove LDAP accounts, [suspend the {{ site.data.variables.product.prodname_ghe_server }} accounts](/enterprise/{{ currentVersion }}/admin/guides/user-management/suspending-and-unsuspending-users). * To remove LDAP accounts, [suspend the {% data variables.product.prodname_ghe_server %} accounts](/enterprise/{{ currentVersion }}/admin/guides/user-management/suspending-and-unsuspending-users).
#### Manually syncing LDAP accounts #### Manually syncing LDAP accounts
{{ site.data.reusables.enterprise_site_admin_settings.sign-in }} {% data reusables.enterprise_site_admin_settings.sign-in %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.search-user }} {% data reusables.enterprise_site_admin_settings.search-user %}
{{ site.data.reusables.enterprise_site_admin_settings.click-user }} {% data reusables.enterprise_site_admin_settings.click-user %}
{{ site.data.reusables.enterprise_site_admin_settings.admin-top-tab }} {% data reusables.enterprise_site_admin_settings.admin-top-tab %}
{{ site.data.reusables.enterprise_site_admin_settings.admin-tab }} {% data reusables.enterprise_site_admin_settings.admin-tab %}
5. Under "LDAP," click **Sync now** to manually update the account with data from your LDAP server. 5. Under "LDAP," click **Sync now** to manually update the account with data from your LDAP server.
![LDAP sync now button](/assets/images/enterprise/site-admin-settings/ldap-sync-now-button.png) ![LDAP sync now button](/assets/images/enterprise/site-admin-settings/ldap-sync-now-button.png)
You can also [use the API to trigger a manual sync](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#ldap). You can also [use the API to trigger a manual sync](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#ldap).
### Revoking access to {{ site.data.variables.product.product_location_enterprise }} ### Revoking access to {% data variables.product.product_location_enterprise %}
If [LDAP Sync is enabled](#enabling-ldap-sync), removing a user's LDAP credentials will suspend their account after the next synchronization run. If [LDAP Sync is enabled](#enabling-ldap-sync), removing a user's LDAP credentials will suspend their account after the next synchronization run.
If LDAP Sync is **not** enabled, you must manually suspend the {{ site.data.variables.product.prodname_ghe_server }} account after you remove the LDAP credentials. For more information, see "[Suspending and unsuspending users](/enterprise/{{ currentVersion }}/admin/guides/user-management/suspending-and-unsuspending-users)". If LDAP Sync is **not** enabled, you must manually suspend the {% data variables.product.prodname_ghe_server %} account after you remove the LDAP credentials. For more information, see "[Suspending and unsuspending users](/enterprise/{{ currentVersion }}/admin/guides/user-management/suspending-and-unsuspending-users)".

72
content/admin/authentication/using-saml.md
View File

@@ -5,22 +5,22 @@ redirect_from:
- /enterprise/admin/articles/about-saml-authentication/ - /enterprise/admin/articles/about-saml-authentication/
- /enterprise/admin/user-management/using-saml - /enterprise/admin/user-management/using-saml
- /enterprise/admin/authentication/using-saml - /enterprise/admin/authentication/using-saml
intro: 'SAML is an XML-based standard for authentication and authorization. {{ site.data.variables.product.prodname_ghe_server }} can act as a service provider (SP) with your internal SAML identity provider (IdP).' intro: 'SAML is an XML-based standard for authentication and authorization. {% data variables.product.prodname_ghe_server %} can act as a service provider (SP) with your internal SAML identity provider (IdP).'
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
{{ site.data.reusables.enterprise_user_management.built-in-authentication }} {% data reusables.enterprise_user_management.built-in-authentication %}
### Supported SAML services ### Supported SAML services
{{ site.data.reusables.saml.saml-supported-idps }} {% data reusables.saml.saml-supported-idps %}
{{ site.data.reusables.saml.saml-single-logout-not-supported }} {% data reusables.saml.saml-single-logout-not-supported %}
### Username considerations with SAML ### Username considerations with SAML
Each {{ site.data.variables.product.prodname_ghe_server }} username is determined by one of the following assertions in the SAML response, ordered by priority: Each {% data variables.product.prodname_ghe_server %} username is determined by one of the following assertions in the SAML response, ordered by priority:
- The custom username attribute, if defined and present - The custom username attribute, if defined and present
- An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` assertion, if present - An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` assertion, if present
@@ -29,24 +29,24 @@ Each {{ site.data.variables.product.prodname_ghe_server }} username is determine
The `NameID` element is required even if other attributes are present. The `NameID` element is required even if other attributes are present.
A mapping is created between the `NameID` and the {{ site.data.variables.product.prodname_ghe_server }} username, so the `NameID` should be persistent, unique, and not subject to change for the lifecyle of the user. A mapping is created between the `NameID` and the {% data variables.product.prodname_ghe_server %} username, so the `NameID` should be persistent, unique, and not subject to change for the lifecyle of the user.
{% note %} {% note %}
**Note**: If the `NameID` for a user does change on the IdP, the user will see an error message when they try to sign in to your {{ site.data.variables.product.prodname_ghe_server }} instance. {% if currentVersion ver_gt "enterprise-server@2.21" %}To restore the user's access, you'll need to update the user account's `NameID` mapping. For more information, see "[Updating a user's SAML `NameID`](#updating-a-users-saml-nameid)."{% else %} For more information, see "[Error: 'Another user already owns the account'](#error-another-user-already-owns-the-account)."{% endif %} **Note**: If the `NameID` for a user does change on the IdP, the user will see an error message when they try to sign in to your {% data variables.product.prodname_ghe_server %} instance. {% if currentVersion ver_gt "enterprise-server@2.21" %}To restore the user's access, you'll need to update the user account's `NameID` mapping. For more information, see "[Updating a user's SAML `NameID`](#updating-a-users-saml-nameid)."{% else %} For more information, see "[Error: 'Another user already owns the account'](#error-another-user-already-owns-the-account)."{% endif %}
{% endnote %} {% endnote %}
{{ site.data.reusables.enterprise_management_console.username_normalization }} {% data reusables.enterprise_management_console.username_normalization %}
{{ site.data.reusables.enterprise_management_console.username_normalization_sample }} {% data reusables.enterprise_management_console.username_normalization_sample %}
{{ site.data.reusables.enterprise_user_management.two_factor_auth_header }} {% data reusables.enterprise_user_management.two_factor_auth_header %}
{{ site.data.reusables.enterprise_user_management.external_auth_disables_2fa }} {% data reusables.enterprise_user_management.external_auth_disables_2fa %}
### SAML metadata ### SAML metadata
Your {{ site.data.variables.product.prodname_ghe_server }} instances's service provider metadata is available at `http(s)://[hostname]/saml/metadata`. Your {% data variables.product.prodname_ghe_server %} instances's service provider metadata is available at `http(s)://[hostname]/saml/metadata`.
To configure your identity provider manually, the Assertion Consumer Service (ACS) URL is `http(s)://[hostname]/saml/consume`. It uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding. To configure your identity provider manually, the Assertion Consumer Service (ACS) URL is `http(s)://[hostname]/saml/consume`. It uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding.
@@ -56,9 +56,9 @@ These attributes are available. You can change the attribute names in the [manag
| Default attribute name | Type | Description | | Default attribute name | Type | Description |
|-----------------|----------|-------------| |-----------------|----------|-------------|
| `NameID` | Required | A persistent user identifier. Any persistent name identifier format may be used. The `NameID` element will be used for a {{ site.data.variables.product.prodname_ghe_server }} username unless one of the alternative assertions is provided. | | `NameID` | Required | A persistent user identifier. Any persistent name identifier format may be used. The `NameID` element will be used for a {% data variables.product.prodname_ghe_server %} username unless one of the alternative assertions is provided. |
| `administrator` | Optional | When the value is 'true', the user will automatically be promoted as an administrator. Any other value or a non-existent value will demote the user to a normal user account. | | `administrator` | Optional | When the value is 'true', the user will automatically be promoted as an administrator. Any other value or a non-existent value will demote the user to a normal user account. |
| `username` | Optional | The {{ site.data.variables.product.prodname_ghe_server }} username. | | `username` | Optional | The {% data variables.product.prodname_ghe_server %} username. |
| `full_name` | Optional | The name of the user displayed on their profile page. Users may change their names after provisioning. | | `full_name` | Optional | The name of the user displayed on their profile page. Users may change their names after provisioning. |
| `emails` | Optional | The email addresses for the user. More than one can be specified. | | `emails` | Optional | The email addresses for the user. More than one can be specified. |
| `public_keys` | Optional | The public SSH keys for the user. More than one can be specified. | | `public_keys` | Optional | The public SSH keys for the user. More than one can be specified. |
@@ -66,28 +66,28 @@ These attributes are available. You can change the attribute names in the [manag
### Configuring SAML settings ### Configuring SAML settings
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.authentication }} {% data reusables.enterprise_management_console.authentication %}
3. Select **SAML**. 3. Select **SAML**.
![SAML authentication](/assets/images/enterprise/management-console/auth-select-saml.png) ![SAML authentication](/assets/images/enterprise/management-console/auth-select-saml.png)
4. {{ site.data.reusables.enterprise_user_management.built-in-authentication-option }} ![Select SAML built-in authentication checkbox](/assets/images/enterprise/management-console/saml-built-in-authentication.png) 4. {% data reusables.enterprise_user_management.built-in-authentication-option %} ![Select SAML built-in authentication checkbox](/assets/images/enterprise/management-console/saml-built-in-authentication.png)
5. Optionally, to enable unsolicited response SSO, select **IdP initiated SSO**. By default, {{ site.data.variables.product.prodname_ghe_server }} will reply to an unsolicited Identity Provider (IdP) initiated request with an `AuthnRequest` back to the IdP. 5. Optionally, to enable unsolicited response SSO, select **IdP initiated SSO**. By default, {% data variables.product.prodname_ghe_server %} will reply to an unsolicited Identity Provider (IdP) initiated request with an `AuthnRequest` back to the IdP.
![SAML idP SSO](/assets/images/enterprise/management-console/saml-idp-sso.png) ![SAML idP SSO](/assets/images/enterprise/management-console/saml-idp-sso.png)
{% tip %} {% tip %}
**Note**: We recommend keeping this value **unselected**. You should enable this feature **only** in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by {{ site.data.variables.contact.enterprise_support }}. **Note**: We recommend keeping this value **unselected**. You should enable this feature **only** in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by {% data variables.contact.enterprise_support %}.
{% endtip %} {% endtip %}
5. Select **Disable administrator demotion/promotion** if you **do not** want your SAML provider to determine administrator rights for users on {{ site.data.variables.product.product_location_enterprise }}. 5. Select **Disable administrator demotion/promotion** if you **do not** want your SAML provider to determine administrator rights for users on {% data variables.product.product_location_enterprise %}.
![SAML disable admin config](/assets/images/enterprise/management-console/disable-admin-demotion-promotion.png) ![SAML disable admin config](/assets/images/enterprise/management-console/disable-admin-demotion-promotion.png)
6. In the **Single sign-on URL** field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to [configure {{ site.data.variables.product.product_location_enterprise }} to use internal nameservers](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-dns-nameservers/). 6. In the **Single sign-on URL** field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to [configure {% data variables.product.product_location_enterprise %} to use internal nameservers](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-dns-nameservers/).
![SAML authentication](/assets/images/enterprise/management-console/saml-single-sign-url.png) ![SAML authentication](/assets/images/enterprise/management-console/saml-single-sign-url.png)
7. Optionally, in the **Issuer** field, type your SAML issuer's name. This verifies the authenticity of messages sent to {{ site.data.variables.product.product_location_enterprise }}. 7. Optionally, in the **Issuer** field, type your SAML issuer's name. This verifies the authenticity of messages sent to {% data variables.product.product_location_enterprise %}.
![SAML issuer](/assets/images/enterprise/management-console/saml-issuer.png) ![SAML issuer](/assets/images/enterprise/management-console/saml-issuer.png)
8. In the **Signature Method** and **Digest Method** drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from {{ site.data.variables.product.product_location_enterprise }}. Specify the format with the **Name Identifier Format** drop-down menu. 8. In the **Signature Method** and **Digest Method** drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from {% data variables.product.product_location_enterprise %}. Specify the format with the **Name Identifier Format** drop-down menu.
![SAML method](/assets/images/enterprise/management-console/saml-method.png) ![SAML method](/assets/images/enterprise/management-console/saml-method.png)
9. Under **Verification certificate**, click **Choose File** and choose a certificate to validate SAML responses from the IdP. 9. Under **Verification certificate**, click **Choose File** and choose a certificate to validate SAML responses from the IdP.
![SAML authentication](/assets/images/enterprise/management-console/saml-verification-cert.png) ![SAML authentication](/assets/images/enterprise/management-console/saml-verification-cert.png)
@@ -98,12 +98,12 @@ These attributes are available. You can change the attribute names in the [manag
### Updating a user's SAML `NameID` ### Updating a user's SAML `NameID`
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
2. In the left sidebar, click **All users**. 2. In the left sidebar, click **All users**.
!["All users" sidebar item in site administrator settings](/assets/images/enterprise/site-admin-settings/all-users.png) !["All users" sidebar item in site administrator settings](/assets/images/enterprise/site-admin-settings/all-users.png)
3. In the list of users, click the username you'd like to update the `NameID` mapping for. 3. In the list of users, click the username you'd like to update the `NameID` mapping for.
![Username in list of instance user accounts](/assets/images/enterprise/site-admin-settings/all-users-click-username.png) ![Username in list of instance user accounts](/assets/images/enterprise/site-admin-settings/all-users-click-username.png)
{{ site.data.reusables.enterprise_site_admin_settings.security-tab }} {% data reusables.enterprise_site_admin_settings.security-tab %}
5. To the right of "Update SAML NameID", click **Edit** . 5. To the right of "Update SAML NameID", click **Edit** .
!["Edit" button under "SAML authentication" and to the right of "Update SAML NameID"](/assets/images/enterprise/site-admin-settings/update-saml-nameid-edit.png) !["Edit" button under "SAML authentication" and to the right of "Update SAML NameID"](/assets/images/enterprise/site-admin-settings/update-saml-nameid-edit.png)
6. In the "NameID" field, type the new `NameID` for the user. 6. In the "NameID" field, type the new `NameID` for the user.
@@ -113,7 +113,7 @@ These attributes are available. You can change the attribute names in the [manag
{% endif %} {% endif %}
### Revoking access to {{ site.data.variables.product.product_location_enterprise }} ### Revoking access to {% data variables.product.product_location_enterprise %}
If you remove a user from your identity provider, you must also manually suspend them. Otherwise, they'll continue to be able to authenticate using access tokens or SSH keys. For more information, see "[Suspending and unsuspending users](/enterprise/admin/guides/user-management/suspending-and-unsuspending-users)". If you remove a user from your identity provider, you must also manually suspend them. Otherwise, they'll continue to be able to authenticate using access tokens or SSH keys. For more information, see "[Suspending and unsuspending users](/enterprise/admin/guides/user-management/suspending-and-unsuspending-users)".
@@ -122,7 +122,7 @@ If you remove a user from your identity provider, you must also manually suspend
The response message must fulfill the following requirements: The response message must fulfill the following requirements:
- The `<Destination>` element must be provided on the root response document and match the ACS URL only when the root response document is signed. If the assertion is signed, it will be ignored. - The `<Destination>` element must be provided on the root response document and match the ACS URL only when the root response document is signed. If the assertion is signed, it will be ignored.
- The `<Audience>` element must always be provided as part of the `<AudienceRestriction>` element. It must match the `EntityId` for {{ site.data.variables.product.prodname_ghe_server }}. This is the URL to the {{ site.data.variables.product.prodname_ghe_server }} instance, such as `https://ghe.corp.example.com`. - The `<Audience>` element must always be provided as part of the `<AudienceRestriction>` element. It must match the `EntityId` for {% data variables.product.prodname_ghe_server %}. This is the URL to the {% data variables.product.prodname_ghe_server %} instance, such as `https://ghe.corp.example.com`.
- Each assertion in the response **must** be protected by a digital signature. This can be accomplished by signing each individual `<Assertion>` element or by signing the `<Response>` element. - Each assertion in the response **must** be protected by a digital signature. This can be accomplished by signing each individual `<Assertion>` element or by signing the `<Response>` element.
- A `<NameID>` element must be provided as part of the `<Subject>` element. Any persistent name identifier format may be used. - A `<NameID>` element must be provided as part of the `<Subject>` element. Any persistent name identifier format may be used.
- The `Recipient` attribute must be present and set to the ACS URL. For example: - The `Recipient` attribute must be present and set to the ACS URL. For example:
@@ -147,21 +147,21 @@ The response message must fulfill the following requirements:
### Troubleshooting SAML authentication ### Troubleshooting SAML authentication
{{ site.data.variables.product.prodname_ghe_server }} logs error messages for failed SAML authentication in the authentication log at _/var/log/github/auth.log_. For more information about SAML response requirements, see "[Response message requirements](#response-message-requirements)." {% data variables.product.prodname_ghe_server %} logs error messages for failed SAML authentication in the authentication log at _/var/log/github/auth.log_. For more information about SAML response requirements, see "[Response message requirements](#response-message-requirements)."
#### Error: "Another user already owns the account" #### Error: "Another user already owns the account"
When a user signs in to {{ site.data.variables.product.prodname_ghe_server }} for the first time with SAML authentication, {{ site.data.variables.product.prodname_ghe_server }} creates a user account on the instance and maps the SAML `NameID` to the account. When a user signs in to {% data variables.product.prodname_ghe_server %} for the first time with SAML authentication, {% data variables.product.prodname_ghe_server %} creates a user account on the instance and maps the SAML `NameID` to the account.
When the user signs in again, {{ site.data.variables.product.prodname_ghe_server }} compares the account's `NameID` mapping to the IdP's response. If the `NameID` in the IdP's response no longer matches the `NameID` that {{ site.data.variables.product.prodname_ghe_server }} expects for the user, the sign-in will fail. The user will see the following message. When the user signs in again, {% data variables.product.prodname_ghe_server %} compares the account's `NameID` mapping to the IdP's response. If the `NameID` in the IdP's response no longer matches the `NameID` that {% data variables.product.prodname_ghe_server %} expects for the user, the sign-in will fail. The user will see the following message.
> Another user already owns the account. Please have your administrator check the authentication log. > Another user already owns the account. Please have your administrator check the authentication log.
The message typically indicates that the person's username or email address has changed on the IdP. {% if currentVersion ver_gt "enterprise-server@2.21" %}Ensure that the `NameID` mapping for the user account on {{ site.data.variables.product.prodname_ghe_server }} matches the user's `NameID` on your IdP. For more information, see "[Updating a user's SAML `NameID`](#updating-a-users-saml-nameid)."{% else %}For help updating the `NameID` mapping, contact {{ site.data.variables.contact.contact_ent_support }}.{% endif %} The message typically indicates that the person's username or email address has changed on the IdP. {% if currentVersion ver_gt "enterprise-server@2.21" %}Ensure that the `NameID` mapping for the user account on {% data variables.product.prodname_ghe_server %} matches the user's `NameID` on your IdP. For more information, see "[Updating a user's SAML `NameID`](#updating-a-users-saml-nameid)."{% else %}For help updating the `NameID` mapping, contact {% data variables.contact.contact_ent_support %}.{% endif %}
#### Error: Recipient in SAML response was blank or not valid #### Error: Recipient in SAML response was blank or not valid
If the `Recipient` does not match the ACS URL for your {{ site.data.variables.product.prodname_ghe_server }} instance, one of the following two error messages will appear in the authentication log when a user attempts to authenticate. If the `Recipient` does not match the ACS URL for your {% data variables.product.prodname_ghe_server %} instance, one of the following two error messages will appear in the authentication log when a user attempts to authenticate.
``` ```
Recipient in the SAML response must not be blank. Recipient in the SAML response must not be blank.
@@ -171,7 +171,7 @@ Recipient in the SAML response must not be blank.
Recipient in the SAML response was not valid. Recipient in the SAML response was not valid.
``` ```
Ensure that you set the value for `Recipient` on your IdP to the full ACS URL for your {{ site.data.variables.product.prodname_ghe_server }} instance. For example, `https://ghe.corp.example.com/saml/consume`. Ensure that you set the value for `Recipient` on your IdP to the full ACS URL for your {% data variables.product.prodname_ghe_server %} instance. For example, `https://ghe.corp.example.com/saml/consume`.
#### Error: "SAML Response is not signed or has been modified" #### Error: "SAML Response is not signed or has been modified"
@@ -181,7 +181,7 @@ If your IdP does not sign the SAML response, or the signature does not match the
SAML Response is not signed or has been modified. SAML Response is not signed or has been modified.
``` ```
Ensure that you configure signed assertions for the {{ site.data.variables.product.prodname_ghe_server }} application on your IdP. Ensure that you configure signed assertions for the {% data variables.product.prodname_ghe_server %} application on your IdP.
#### Error: "Audience is invalid" or "No assertion found" #### Error: "Audience is invalid" or "No assertion found"
@@ -191,4 +191,4 @@ If the IdP's response has a missing or incorrect value for `Audience`, the follo
Audience is invalid. Audience attribute does not match https://<em>YOUR-INSTANCE-URL</em> Audience is invalid. Audience attribute does not match https://<em>YOUR-INSTANCE-URL</em>
``` ```
Ensure that you set the value for `Audience` on your IdP to the `EntityId` for your {{ site.data.variables.product.prodname_ghe_server }} instance, which is the full URL to your {{ site.data.variables.product.prodname_ghe_server }} instance. For example, `https://ghe.corp.example.com`. Ensure that you set the value for `Audience` on your IdP to the `EntityId` for your {% data variables.product.prodname_ghe_server %} instance, which is the full URL to your {% data variables.product.prodname_ghe_server %} instance. For example, `https://ghe.corp.example.com`.

16
content/admin/configuration/accessing-the-administrative-shell-ssh.md
View File

@@ -10,14 +10,14 @@ redirect_from:
- /enterprise/admin/2.15/articles/troubleshooting-ssh-permission-denied-publickey/ - /enterprise/admin/2.15/articles/troubleshooting-ssh-permission-denied-publickey/
- /enterprise/admin/installation/accessing-the-administrative-shell-ssh - /enterprise/admin/installation/accessing-the-administrative-shell-ssh
- /enterprise/admin/configuration/accessing-the-administrative-shell-ssh - /enterprise/admin/configuration/accessing-the-administrative-shell-ssh
intro: 'SSH access allows you to run the {{ site.data.variables.product.prodname_ghe_server }} command line utilities and is useful for troubleshooting, running backups, and configuring replication.' intro: 'SSH access allows you to run the {% data variables.product.prodname_ghe_server %} command line utilities and is useful for troubleshooting, running backups, and configuring replication.'
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### About administrative shell access ### About administrative shell access
If you have SSH access to the administrative shell, you can run {{ site.data.variables.product.prodname_ghe_server }}'s command line utilities. SSH access is also useful for troubleshooting, running backups, and configuring replication. Administrative SSH access is managed separately from Git SSH access and is accessible only via port 122. If you have SSH access to the administrative shell, you can run {% data variables.product.prodname_ghe_server %}'s command line utilities. SSH access is also useful for troubleshooting, running backups, and configuring replication. Administrative SSH access is managed separately from Git SSH access and is accessible only via port 122.
### Enabling access to the administrative shell via SSH ### Enabling access to the administrative shell via SSH
@@ -29,11 +29,11 @@ To enable administrative SSH access, you must add your SSH public key to your in
{% endtip %} {% endtip %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
3. Under "SSH access", paste your key into the text box, then click **Add key**. 3. Under "SSH access", paste your key into the text box, then click **Add key**.
![Text box and button for adding an SSH key](/assets/images/enterprise/settings/add-authorized-ssh-key-admin-shell.png) ![Text box and button for adding an SSH key](/assets/images/enterprise/settings/add-authorized-ssh-key-admin-shell.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### Connecting to the administrative shell over SSH ### Connecting to the administrative shell over SSH
@@ -47,7 +47,7 @@ admin@github-example-com:~$ █
#### Troubleshooting SSH connection problems #### Troubleshooting SSH connection problems
If you encounter the `Permission denied (publickey)` error when you try to connect to {{ site.data.variables.product.product_location_enterprise }} via SSH, confirm that you are connecting over port 122. You may need to explicitly specify which private SSH key to use. If you encounter the `Permission denied (publickey)` error when you try to connect to {% data variables.product.product_location_enterprise %} via SSH, confirm that you are connecting over port 122. You may need to explicitly specify which private SSH key to use.
To specify a private SSH key using the command line, run `ssh` with the `-i` argument. To specify a private SSH key using the command line, run `ssh` with the `-i` argument.
@@ -66,8 +66,8 @@ Host <em>hostname</em>
### Accessing the administrative shell using the local console ### Accessing the administrative shell using the local console
In an emergency situation, for example if SSH is unavailable, you can access the administrative shell locally. Sign in as the `admin` user and use the password established during initial setup of {{ site.data.variables.product.prodname_ghe_server }}. In an emergency situation, for example if SSH is unavailable, you can access the administrative shell locally. Sign in as the `admin` user and use the password established during initial setup of {% data variables.product.prodname_ghe_server %}.
### Access limitations for the administrative shell ### Access limitations for the administrative shell
Administrative shell access is permitted for troubleshooting and performing documented operations procedures only. Modifying system and application files, running programs, or installing unsupported software packages may void your support contract. Please contact {{ site.data.variables.contact.contact_ent_support }} if you have a question about the activities allowed by your support contract. Administrative shell access is permitted for troubleshooting and performing documented operations procedures only. Modifying system and application files, running programs, or installing unsupported software packages may void your support contract. Please contact {% data variables.contact.contact_ent_support %} if you have a question about the activities allowed by your support contract.

38
content/admin/configuration/accessing-the-management-console.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Accessing the management console title: Accessing the management console
intro: 'Use the {{ site.data.variables.enterprise.management_console }} to set up and configure {{ site.data.variables.product.product_location }}, schedule maintenance windows, troubleshoot issues, and manage your license.' intro: 'Use the {% data variables.enterprise.management_console %} to set up and configure {% data variables.product.product_location %}, schedule maintenance windows, troubleshoot issues, and manage your license.'
redirect_from: redirect_from:
- /enterprise/admin/articles/about-the-management-console/ - /enterprise/admin/articles/about-the-management-console/
- /enterprise/admin/articles/management-console-for-emergency-recovery/ - /enterprise/admin/articles/management-console-for-emergency-recovery/
@@ -14,37 +14,37 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### About the {{ site.data.variables.enterprise.management_console }} ### About the {% data variables.enterprise.management_console %}
Use the {{ site.data.variables.enterprise.management_console }} for basic administrative activities: Use the {% data variables.enterprise.management_console %} for basic administrative activities:
- **Initial setup**: Walk through the initial setup process when first launching {{ site.data.variables.product.product_location_enterprise }} by visiting {{ site.data.variables.product.product_location_enterprise }}'s IP address in your browser. - **Initial setup**: Walk through the initial setup process when first launching {% data variables.product.product_location_enterprise %} by visiting {% data variables.product.product_location_enterprise %}'s IP address in your browser.
- **Configuring basic settings for your instance**: Configure DNS, hostname, SSL, user authentication, email, monitoring services, and log forwarding on the Settings page. - **Configuring basic settings for your instance**: Configure DNS, hostname, SSL, user authentication, email, monitoring services, and log forwarding on the Settings page.
- **Scheduling maintenance windows**: Take your {{ site.data.variables.product.product_location_enterprise }} offline while performing maintenance using the {{ site.data.variables.enterprise.management_console }} or administrative shell. - **Scheduling maintenance windows**: Take your {% data variables.product.product_location_enterprise %} offline while performing maintenance using the {% data variables.enterprise.management_console %} or administrative shell.
- **Troubleshooting**: Generate a support bundle or view high level diagnostic information. - **Troubleshooting**: Generate a support bundle or view high level diagnostic information.
- **License management**: View or update your {{ site.data.variables.product.prodname_enterprise }} license. - **License management**: View or update your {% data variables.product.prodname_enterprise %} license.
You can always reach the {{ site.data.variables.enterprise.management_console }} using {{ site.data.variables.product.product_location_enterprise }}'s IP address, even when the instance is in maintenance mode, or there is a critical application failure or hostname or SSL misconfiguration. You can always reach the {% data variables.enterprise.management_console %} using {% data variables.product.product_location_enterprise %}'s IP address, even when the instance is in maintenance mode, or there is a critical application failure or hostname or SSL misconfiguration.
To access the {{ site.data.variables.enterprise.management_console }}, you must use the administrator password established during initial setup of {{ site.data.variables.product.product_location_enterprise }}. You must also be able to connect to the virtual machine host on port 8443. If you're having trouble reaching the {{ site.data.variables.enterprise.management_console }}, please check intermediate firewall and security group configurations. To access the {% data variables.enterprise.management_console %}, you must use the administrator password established during initial setup of {% data variables.product.product_location_enterprise %}. You must also be able to connect to the virtual machine host on port 8443. If you're having trouble reaching the {% data variables.enterprise.management_console %}, please check intermediate firewall and security group configurations.
### Accessing the {{ site.data.variables.enterprise.management_console }} as a site administrator ### Accessing the {% data variables.enterprise.management_console %} as a site administrator
The first time that you access the {{ site.data.variables.enterprise.management_console }} as a site administrator, you must upload your {{ site.data.variables.product.prodname_enterprise }} license file to authenticate into the app. For more information, see "[Managing your {{ site.data.variables.product.prodname_enterprise}} license](/enterprise/{{ currentVersion }}/admin/guides/installation/managing-your-github-enterprise-license)." The first time that you access the {% data variables.enterprise.management_console %} as a site administrator, you must upload your {% data variables.product.prodname_enterprise %} license file to authenticate into the app. For more information, see "[Managing your {% data variables.product.prodname_enterprise %} license](/enterprise/{{ currentVersion }}/admin/guides/installation/managing-your-github-enterprise-license)."
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.type-management-console-password }} {% data reusables.enterprise_management_console.type-management-console-password %}
### Accessing the {{ site.data.variables.enterprise.management_console }} as an unauthenticated user ### Accessing the {% data variables.enterprise.management_console %} as an unauthenticated user
1. Visit this URL in your browser, replacing `hostname` with your actual {{ site.data.variables.product.prodname_ghe_server }} hostname or IP address: 1. Visit this URL in your browser, replacing `hostname` with your actual {% data variables.product.prodname_ghe_server %} hostname or IP address:
```shell ```shell
http(s)://HOSTNAME/setup http(s)://HOSTNAME/setup
``` ```
{{ site.data.reusables.enterprise_management_console.type-management-console-password }} {% data reusables.enterprise_management_console.type-management-console-password %}
### Unlocking the {{ site.data.variables.enterprise.management_console }} after failed login attempts ### Unlocking the {% data variables.enterprise.management_console %} after failed login attempts
The {{ site.data.variables.enterprise.management_console }} locks after ten failed login attempts are made in the span of ten minutes. You must wait for the login screen to automatically unlock before attempting to log in again. The login screen automatically unlocks as soon as the previous ten minute period contains fewer than ten failed login attempts. The counter resets after a successful login occurs. The {% data variables.enterprise.management_console %} locks after ten failed login attempts are made in the span of ten minutes. You must wait for the login screen to automatically unlock before attempting to log in again. The login screen automatically unlocks as soon as the previous ten minute period contains fewer than ten failed login attempts. The counter resets after a successful login occurs.
To immediately unlock the {{ site.data.variables.enterprise.management_console }}, use the `ghe-reactivate-admin-login` command via the administrative shell. For more information, see "[Command line utilities](/enterprise/{{ currentVersion }}/admin/guides/installation/command-line-utilities#ghe-reactivate-admin-login)" and "[Accessing the administrative shell (SSH)](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-administrative-shell-ssh/)." To immediately unlock the {% data variables.enterprise.management_console %}, use the `ghe-reactivate-admin-login` command via the administrative shell. For more information, see "[Command line utilities](/enterprise/{{ currentVersion }}/admin/guides/installation/command-line-utilities#ghe-reactivate-admin-login)" and "[Accessing the administrative shell (SSH)](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-administrative-shell-ssh/)."

86
content/admin/configuration/command-line-utilities.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Command-line utilities title: Command-line utilities
intro: '{{ site.data.variables.product.prodname_ghe_server }} includes a variety of utilities to help resolve particular problems or perform specific tasks.' intro: '{% data variables.product.prodname_ghe_server %} includes a variety of utilities to help resolve particular problems or perform specific tasks.'
redirect_from: redirect_from:
- /enterprise/admin/articles/viewing-all-services/ - /enterprise/admin/articles/viewing-all-services/
- /enterprise/admin/articles/command-line-utilities/ - /enterprise/admin/articles/command-line-utilities/
@@ -16,10 +16,10 @@ You can execute these commands from anywhere on the VM after signing in as an SS
#### ghe-announce #### ghe-announce
This utility sets a banner at the top of every {{ site.data.variables.product.prodname_enterprise }} page. You can use it to broadcast a message to your users. This utility sets a banner at the top of every {% data variables.product.prodname_enterprise %} page. You can use it to broadcast a message to your users.
{% if currentVersion ver_gt "enterprise-server@2.21" %} {% if currentVersion ver_gt "enterprise-server@2.21" %}
You can also set an announcement banner using the enterprise settings on {{ site.data.variables.product.product_name }}. For more information, see "[Customizing user messages on your instance](/enterprise/admin/user-management/customizing-user-messages-on-your-instance#creating-a-global-announcement-banner)." You can also set an announcement banner using the enterprise settings on {% data variables.product.product_name %}. For more information, see "[Customizing user messages on your instance](/enterprise/admin/user-management/customizing-user-messages-on-your-instance#creating-a-global-announcement-banner)."
{% endif %} {% endif %}
```shell ```shell
@@ -48,11 +48,11 @@ ghe-cleanup-caches
``` ```
#### ghe-cleanup-settings #### ghe-cleanup-settings
This utility wipes all existing {{ site.data.variables.enterprise.management_console }} settings. This utility wipes all existing {% data variables.enterprise.management_console %} settings.
{% tip %} {% tip %}
**Tip**: {{ site.data.reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command }} **Tip**: {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %}
{% endtip %} {% endtip %}
@@ -62,7 +62,7 @@ ghe-cleanup-settings
#### ghe-config #### ghe-config
With this utility, you can both retrieve and modify the configuration settings of {{ site.data.variables.product.product_location_enterprise }}. With this utility, you can both retrieve and modify the configuration settings of {% data variables.product.product_location_enterprise %}.
```shell ```shell
$ ghe-config <em>core.github-hostname</em> $ ghe-config <em>core.github-hostname</em>
@@ -89,7 +89,7 @@ $ ghe-config app.github.rate_limiting_exempt_users "<em>hubot</em> <em>github-ac
#### ghe-config-apply #### ghe-config-apply
This utility applies {{ site.data.variables.enterprise.management_console }} settings, reloads system services, prepares a storage device, reloads application services, and runs any pending database migrations. It is equivalent to clicking **Save settings** in the {{ site.data.variables.enterprise.management_console }}'s web UI or to sending a POST request to [the `/setup/api/configure` endpoint](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#management-console). This utility applies {% data variables.enterprise.management_console %} settings, reloads system services, prepares a storage device, reloads application services, and runs any pending database migrations. It is equivalent to clicking **Save settings** in the {% data variables.enterprise.management_console %}'s web UI or to sending a POST request to [the `/setup/api/configure` endpoint](/enterprise/{{ currentVersion }}/user/rest/reference/enterprise-admin#management-console).
You will probably never need to run this manually, but it's available if you want to automate the process of saving your settings via SSH. You will probably never need to run this manually, but it's available if you want to automate the process of saving your settings via SSH.
@@ -99,7 +99,7 @@ ghe-config-apply
#### ghe-console #### ghe-console
This utility opens the GitHub Rails console on your {{ site.data.variables.product.prodname_enterprise }} appliance. {{ site.data.reusables.command_line.use_with_support_only }} This utility opens the GitHub Rails console on your {% data variables.product.prodname_enterprise %} appliance. {% data reusables.command_line.use_with_support_only %}
```shell ```shell
ghe-console ghe-console
@@ -107,7 +107,7 @@ ghe-console
#### ghe-dbconsole #### ghe-dbconsole
This utility opens a MySQL database session on your {{ site.data.variables.product.prodname_enterprise }} appliance. {{ site.data.reusables.command_line.use_with_support_only }} This utility opens a MySQL database session on your {% data variables.product.prodname_enterprise %} appliance. {% data reusables.command_line.use_with_support_only %}
```shell ```shell
ghe-dbconsole ghe-dbconsole
@@ -157,7 +157,7 @@ $ ghe-es-index-status -do | column -ts,
#### ghe-legacy-github-services-report #### ghe-legacy-github-services-report
This utility lists repositories on your appliance that use {{ site.data.variables.product.prodname_dotcom }} Services, an integration method that will be discontinued on October 1, 2018. Users on your appliance may have set up {{ site.data.variables.product.prodname_dotcom }} Services to create notifications for pushes to certain repositories. For more information, see "[Announcing the deprecation of {{ site.data.variables.product.prodname_dotcom }} Services](https://developer.github.com/changes/2018-04-25-github-services-deprecation/)" on {{ site.data.variables.product.prodname_blog }} or "[Replacing {{ site.data.variables.product.prodname_dotcom }} Services](/v3/guides/replacing-github-services/)." For more information about this command or for additional options, use the `-h` flag. This utility lists repositories on your appliance that use {% data variables.product.prodname_dotcom %} Services, an integration method that will be discontinued on October 1, 2018. Users on your appliance may have set up {% data variables.product.prodname_dotcom %} Services to create notifications for pushes to certain repositories. For more information, see "[Announcing the deprecation of {% data variables.product.prodname_dotcom %} Services](https://developer.github.com/changes/2018-04-25-github-services-deprecation/)" on {% data variables.product.prodname_blog %} or "[Replacing {% data variables.product.prodname_dotcom %} Services](/v3/guides/replacing-github-services/)." For more information about this command or for additional options, use the `-h` flag.
```shell ```shell
ghe-legacy-github-services-report ghe-legacy-github-services-report
@@ -174,7 +174,7 @@ ghe-logs-tail
#### ghe-maintenance #### ghe-maintenance
This utility allows you to control the state of the installation's maintenance mode. It's designed to be used primarily by the {{ site.data.variables.enterprise.management_console }} behind-the-scenes, but it can be used directly. This utility allows you to control the state of the installation's maintenance mode. It's designed to be used primarily by the {% data variables.enterprise.management_console %} behind-the-scenes, but it can be used directly.
```shell ```shell
ghe-maintenance -h ghe-maintenance -h
@@ -237,7 +237,7 @@ ghe-org-admin-promote -a
#### ghe-reactivate-admin-login #### ghe-reactivate-admin-login
Use this command to immediately unlock the {{ site.data.variables.enterprise.management_console }} after 10 failed login attempts in the span of 10 minutes. Use this command to immediately unlock the {% data variables.enterprise.management_console %} after 10 failed login attempts in the span of 10 minutes.
```shell ```shell
$ ghe-reactivate-admin-login $ ghe-reactivate-admin-login
@@ -254,7 +254,7 @@ This utility can help identify whether the Resque server is having problems proc
* Webhooks are not being triggered. * Webhooks are not being triggered.
* The web interface is not updating after a Git push. * The web interface is not updating after a Git push.
If you suspect Resque is failing, contact {{ site.data.variables.contact.contact_ent_support }} for help. If you suspect Resque is failing, contact {% data variables.contact.contact_ent_support %} for help.
With this command, you can also pause or resume jobs in the queue. With this command, you can also pause or resume jobs in the queue.
@@ -271,7 +271,7 @@ $ ghe-resque-info -r <em>QUEUE</em>
This utility can help map SAML records. This utility can help map SAML records.
To create a CSV file containing all the SAML mapping for your {{ site.data.variables.product.product_name }} users: To create a CSV file containing all the SAML mapping for your {% data variables.product.product_name %} users:
```shell ```shell
$ ghe-saml-mapping-csv -d $ ghe-saml-mapping-csv -d
``` ```
@@ -321,13 +321,13 @@ The service names returned from this command can be used with [`systemctl`](http
$ sudo systemctl restart github-resqued $ sudo systemctl restart github-resqued
``` ```
Stopping services will cause downtime on your installation, so we recommend you contact {{ site.data.variables.contact.contact_ent_support }} before stopping or restarting any service. Stopping services will cause downtime on your installation, so we recommend you contact {% data variables.contact.contact_ent_support %} before stopping or restarting any service.
{% endtip %} {% endtip %}
#### ghe-set-password #### ghe-set-password
With `ghe-set-password`, you can set a new password to authenticate into the [{{ site.data.variables.enterprise.management_console }}](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-management-console). With `ghe-set-password`, you can set a new password to authenticate into the [{% data variables.enterprise.management_console %}](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-management-console).
```shell ```shell
ghe-set-password <new_password> ghe-set-password <new_password>
@@ -369,7 +369,7 @@ existing keys in /etc/ssh/ssh_host_* and generate new ones. [y/N]
#### ghe-ssh-weak-fingerprints #### ghe-ssh-weak-fingerprints
This utility returns a report of known weak SSH keys stored on the {{ site.data.variables.product.prodname_enterprise }} appliance. You can optionally revoke user keys as a bulk action. The utility will report weak system keys, which you must manually revoke in the [{{ site.data.variables.enterprise.management_console }}](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-management-console). This utility returns a report of known weak SSH keys stored on the {% data variables.product.prodname_enterprise %} appliance. You can optionally revoke user keys as a bulk action. The utility will report weak system keys, which you must manually revoke in the [{% data variables.enterprise.management_console %}](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-management-console).
```shell ```shell
# Print a report of weak user and system SSH keys # Print a report of weak user and system SSH keys
@@ -381,7 +381,7 @@ $ ghe-ssh-weak-fingerprints --revoke
#### ghe-ssl-acme #### ghe-ssl-acme
This utility allows you to install a Let's Encrypt certificate on your {{ site.data.variables.product.prodname_enterprise }} appliance. For more information, see "[Configuring TLS](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-tls)." This utility allows you to install a Let's Encrypt certificate on your {% data variables.product.prodname_enterprise %} appliance. For more information, see "[Configuring TLS](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-tls)."
You can use the `-x` flag to remove the ACME configuration. You can use the `-x` flag to remove the ACME configuration.
@@ -391,11 +391,11 @@ ghe-ssl-acme -e
#### ghe-ssl-ca-certificate-install #### ghe-ssl-ca-certificate-install
This utility allows you to install a custom root CA certificate on your {{ site.data.variables.product.prodname_enterprise }} server. The certificate must be in PEM format. Furthermore, if your certificate provider includes multiple CA certificates in a single file, you must separate them into individual files that you then pass to `ghe-ssl-ca-certificate-install` one at a time. This utility allows you to install a custom root CA certificate on your {% data variables.product.prodname_enterprise %} server. The certificate must be in PEM format. Furthermore, if your certificate provider includes multiple CA certificates in a single file, you must separate them into individual files that you then pass to `ghe-ssl-ca-certificate-install` one at a time.
Run this utility to add a certificate chain for S/MIME commit signature verification. For more information, see "[About commit signature verification](/enterprise/{{ currentVersion }}/user/articles/about-commit-signature-verification/)." Run this utility to add a certificate chain for S/MIME commit signature verification. For more information, see "[About commit signature verification](/enterprise/{{ currentVersion }}/user/articles/about-commit-signature-verification/)."
Run this utility when {{ site.data.variables.product.product_location_enterprise }} is unable to connect to another server because the latter is using a self-signed SSL certificate or an SSL certificate for which it doesn't provide the necessary CA bundle. One way to confirm this is to run `openssl s_client -connect host:port -verify 0 -CApath /etc/ssl/certs` from {{ site.data.variables.product.product_location_enterprise }}. If the remote server's SSL certificate can be verified, your `SSL-Session` should have a return code of 0, as shown below. Run this utility when {% data variables.product.product_location_enterprise %} is unable to connect to another server because the latter is using a self-signed SSL certificate or an SSL certificate for which it doesn't provide the necessary CA bundle. One way to confirm this is to run `openssl s_client -connect host:port -verify 0 -CApath /etc/ssl/certs` from {% data variables.product.product_location_enterprise %}. If the remote server's SSL certificate can be verified, your `SSL-Session` should have a return code of 0, as shown below.
``` ```
SSL-Session: SSL-Session:
@@ -453,7 +453,7 @@ $ ghe-storage-extend
#### ghe-version #### ghe-version
This utility prints the version, platform, and build of {{ site.data.variables.product.product_location_enterprise }}. This utility prints the version, platform, and build of {% data variables.product.product_location_enterprise %}.
```shell ```shell
$ ghe-version $ ghe-version
@@ -486,7 +486,7 @@ ghe-webhook-logs --global
#### ghe-cluster-status #### ghe-cluster-status
Check the health of your nodes and services in a cluster deployment of {{ site.data.variables.product.prodname_ghe_server }}. Check the health of your nodes and services in a cluster deployment of {% data variables.product.prodname_ghe_server %}.
```shell ```shell
$ ghe-cluster-status $ ghe-cluster-status
@@ -496,7 +496,7 @@ $ ghe-cluster-status
This utility creates a support bundle tarball containing important logs from each of the nodes in either a Geo-replication or Clustering configuration. This utility creates a support bundle tarball containing important logs from each of the nodes in either a Geo-replication or Clustering configuration.
By default, the command creates the tarball in */tmp*, but you can also have it `cat` the tarball to `STDOUT` for easy streaming over SSH. This is helpful in the case where the web UI is unresponsive or downloading a support bundle from */setup/support* doesn't work. You must use this command if you want to generate an *extended* bundle, containing older logs. You can also use this command to upload the cluster support bundle directly to {{ site.data.variables.product.prodname_enterprise }} support. By default, the command creates the tarball in */tmp*, but you can also have it `cat` the tarball to `STDOUT` for easy streaming over SSH. This is helpful in the case where the web UI is unresponsive or downloading a support bundle from */setup/support* doesn't work. You must use this command if you want to generate an *extended* bundle, containing older logs. You can also use this command to upload the cluster support bundle directly to {% data variables.product.prodname_enterprise %} support.
To create a standard bundle: To create a standard bundle:
```shell ```shell
@@ -508,12 +508,12 @@ To create an extended bundle:
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-cluster-support-bundle -x -o' > cluster-support-bundle.tgz $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-cluster-support-bundle -x -o' > cluster-support-bundle.tgz
``` ```
To send a bundle to {{ site.data.variables.contact.github_support }}: To send a bundle to {% data variables.contact.github_support %}:
```shell ```shell
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-cluster-support-bundle -u' $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-cluster-support-bundle -u'
``` ```
To send a bundle to {{ site.data.variables.contact.github_support }} and associate the bundle with a ticket: To send a bundle to {% data variables.contact.github_support %} and associate the bundle with a ticket:
```shell ```shell
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-cluster-support-bundle -t <em>ticket-id</em>' $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-cluster-support-bundle -t <em>ticket-id</em>'
``` ```
@@ -530,7 +530,7 @@ ghe-cluster-failover
#### ghe-dpages #### ghe-dpages
This utility allows you to manage the distributed {{ site.data.variables.product.prodname_pages }} server. This utility allows you to manage the distributed {% data variables.product.prodname_pages %} server.
```shell ```shell
ghe-dpages ghe-dpages
@@ -541,7 +541,7 @@ To show a summary of repository location and health:
ghe-dpages status ghe-dpages status
``` ```
To evacuate a {{ site.data.variables.product.prodname_pages }} storage service before evacuating a cluster node: To evacuate a {% data variables.product.prodname_pages %} storage service before evacuating a cluster node:
``` shell ``` shell
ghe-dpages evacuate pages-server-<uuid> ghe-dpages evacuate pages-server-<uuid>
``` ```
@@ -600,7 +600,7 @@ ghe-repo <em>username</em>/<em>reponame</em>
#### ghe-repo-gc #### ghe-repo-gc
This utility manually repackages a repository network to optimize pack storage. If you have a large repository, running this command may help reduce its overall size. {{ site.data.variables.product.prodname_enterprise }} automatically runs this command throughout your interaction with a repository network. This utility manually repackages a repository network to optimize pack storage. If you have a large repository, running this command may help reduce its overall size. {% data variables.product.prodname_enterprise %} automatically runs this command throughout your interaction with a repository network.
You can add the optional `--prune` argument to remove unreachable Git objects that aren't referenced from a branch, tag, or any other ref. This is particularly useful for immediately removing [previously expunged sensitive information](/enterprise/user/articles/remove-sensitive-data/). You can add the optional `--prune` argument to remove unreachable Git objects that aren't referenced from a branch, tag, or any other ref. This is particularly useful for immediately removing [previously expunged sensitive information](/enterprise/user/articles/remove-sensitive-data/).
@@ -612,7 +612,7 @@ ghe-repo-gc <em>username</em>/<em>reponame</em>
#### ghe-migrator #### ghe-migrator
`ghe-migrator` is a hi-fidelity tool to help you migrate from one GitHub instance to another. You can consolidate your instances or move your organization, users, teams, and repositories from GitHub.com to {{ site.data.variables.product.prodname_enterprise }}. `ghe-migrator` is a hi-fidelity tool to help you migrate from one GitHub instance to another. You can consolidate your instances or move your organization, users, teams, and repositories from GitHub.com to {% data variables.product.prodname_enterprise %}.
For more information, please see our guide on [migrating user, organization, and repository data](/enterprise/admin/guides/migrations/). For more information, please see our guide on [migrating user, organization, and repository data](/enterprise/admin/guides/migrations/).
@@ -657,7 +657,7 @@ git-import-rewrite
This utility performs a variety of checks and gathers information about your installation that you can send to support to help diagnose problems you're having. This utility performs a variety of checks and gathers information about your installation that you can send to support to help diagnose problems you're having.
Currently, this utility's output is similar to downloading the diagnostics info in the {{ site.data.variables.enterprise.management_console }}, but may have additional improvements added to it over time that aren't available in the web UI. For more information, see "[Creating and sharing diagnostic files](/enterprise/admin/guides/enterprise-support/providing-data-to-github-support#creating-and-sharing-diagnostic-files)." Currently, this utility's output is similar to downloading the diagnostics info in the {% data variables.enterprise.management_console %}, but may have additional improvements added to it over time that aren't available in the web UI. For more information, see "[Creating and sharing diagnostic files](/enterprise/admin/guides/enterprise-support/providing-data-to-github-support#creating-and-sharing-diagnostic-files)."
```shell ```shell
ghe-diagnostics ghe-diagnostics
@@ -665,10 +665,10 @@ ghe-diagnostics
#### ghe-support-bundle #### ghe-support-bundle
{{ site.data.reusables.enterprise_enterprise_support.use_ghe_cluster_support_bundle }} {% data reusables.enterprise_enterprise_support.use_ghe_cluster_support_bundle %}
This utility creates a support bundle tarball containing important logs from your instance. This utility creates a support bundle tarball containing important logs from your instance.
By default, the command creates the tarball in */tmp*, but you can also have it `cat` the tarball to `STDOUT` for easy streaming over SSH. This is helpful in the case where the web UI is unresponsive or downloading a support bundle from */setup/support* doesn't work. You must use this command if you want to generate an *extended* bundle, containing older logs. You can also use this command to upload the support bundle directly to {{ site.data.variables.product.prodname_enterprise }} support. By default, the command creates the tarball in */tmp*, but you can also have it `cat` the tarball to `STDOUT` for easy streaming over SSH. This is helpful in the case where the web UI is unresponsive or downloading a support bundle from */setup/support* doesn't work. You must use this command if you want to generate an *extended* bundle, containing older logs. You can also use this command to upload the support bundle directly to {% data variables.product.prodname_enterprise %} support.
To create a standard bundle: To create a standard bundle:
```shell ```shell
@@ -680,12 +680,12 @@ To create an extended bundle:
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -x -o' > support-bundle.tgz $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -x -o' > support-bundle.tgz
``` ```
To send a bundle to {{ site.data.variables.contact.github_support }}: To send a bundle to {% data variables.contact.github_support %}:
```shell ```shell
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -u' $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -u'
``` ```
To send a bundle to {{ site.data.variables.contact.github_support }} and associate the bundle with a ticket: To send a bundle to {% data variables.contact.github_support %} and associate the bundle with a ticket:
```shell ```shell
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -t <em>ticket-id</em>' $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -t <em>ticket-id</em>'
@@ -693,9 +693,9 @@ $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-support-bundle -t <em>ticket-id</em
#### ghe-support-upload #### ghe-support-upload
This utility sends information from your appliance to {{ site.data.variables.product.prodname_enterprise }} support. You can either specify a local file, or provide a stream of up to 100MB of data via `STDIN`. The uploaded data can optionally be associated with a support ticket. This utility sends information from your appliance to {% data variables.product.prodname_enterprise %} support. You can either specify a local file, or provide a stream of up to 100MB of data via `STDIN`. The uploaded data can optionally be associated with a support ticket.
To send a file to {{ site.data.variables.contact.github_support }} and associate the file with a ticket: To send a file to {% data variables.contact.github_support %} and associate the file with a ticket:
```shell ```shell
ghe-support-upload -f <em>path/to/your/file</em> -t <em>ticket-id</em> ghe-support-upload -f <em>path/to/your/file</em> -t <em>ticket-id</em>
``` ```
@@ -705,13 +705,13 @@ To upload data via `STDIN` and associating the data with a ticket:
<em>ghe-repl-status -vv</em> | ghe-support-upload -t <em>ticket-id</em> -d "<em>Verbose Replication Status</em>" <em>ghe-repl-status -vv</em> | ghe-support-upload -t <em>ticket-id</em> -d "<em>Verbose Replication Status</em>"
``` ```
In this example, `ghe-repl-status -vv` sends verbose status information from a replica appliance. You should replace `ghe-repl-status -vv` with the specific data you'd like to stream to `STDIN`, and `Verbose Replication Status` with a brief description of the data. {{ site.data.reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command }} In this example, `ghe-repl-status -vv` sends verbose status information from a replica appliance. You should replace `ghe-repl-status -vv` with the specific data you'd like to stream to `STDIN`, and `Verbose Replication Status` with a brief description of the data. {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %}
### Upgrading {{ site.data.variables.product.prodname_ghe_server }} ### Upgrading {% data variables.product.prodname_ghe_server %}
#### ghe-upgrade #### ghe-upgrade
This utility installs or verifies an upgrade package. You can also use this utility to roll back a patch release if an upgrade fails or is interrupted. For more information, see "[Upgrading {{ site.data.variables.product.prodname_ghe_server }}](/enterprise/{{ currentVersion }}/admin/guides/installation/upgrading-github-enterprise-server/)." This utility installs or verifies an upgrade package. You can also use this utility to roll back a patch release if an upgrade fails or is interrupted. For more information, see "[Upgrading {% data variables.product.prodname_ghe_server %}](/enterprise/{{ currentVersion }}/admin/guides/installation/upgrading-github-enterprise-server/)."
To verify an upgrade package: To verify an upgrade package:
```shell ```shell
@@ -723,7 +723,7 @@ To install an upgrade package:
ghe-upgrade <em>UPGRADE-PACKAGE-FILENAME</em> ghe-upgrade <em>UPGRADE-PACKAGE-FILENAME</em>
``` ```
{{ site.data.reusables.enterprise_installation.command-line-utilities-ghe-upgrade-rollback }} {% data reusables.enterprise_installation.command-line-utilities-ghe-upgrade-rollback %}
#### ghe-upgrade-scheduler #### ghe-upgrade-scheduler
@@ -747,11 +747,11 @@ $ ghe-upgrade-scheduler -r <em>UPGRADE PACKAGE FILENAME</em>
#### ghe-update-check #### ghe-update-check
This utility will check to see if a new patch release of {{ site.data.variables.product.prodname_enterprise }} is available. If it is, and if space is available on your instance, it will download the package. By default, it's saved to */var/lib/ghe-updates*. An administrator can then [perform the upgrade](/enterprise/admin/guides/installation/updating-the-virtual-machine-and-physical-resources/). This utility will check to see if a new patch release of {% data variables.product.prodname_enterprise %} is available. If it is, and if space is available on your instance, it will download the package. By default, it's saved to */var/lib/ghe-updates*. An administrator can then [perform the upgrade](/enterprise/admin/guides/installation/updating-the-virtual-machine-and-physical-resources/).
A file containing the status of the download is available at */var/lib/ghe-updates/ghe-update-check.status*. A file containing the status of the download is available at */var/lib/ghe-updates/ghe-update-check.status*.
To check for the latest {{ site.data.variables.product.prodname_enterprise }} release, use the `-i` switch. To check for the latest {% data variables.product.prodname_enterprise %} release, use the `-i` switch.
```shell ```shell
$ ssh -p 122 admin@<em>hostname</em> -- 'ghe-update-check' $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-update-check'
@@ -761,7 +761,7 @@ $ ssh -p 122 admin@<em>hostname</em> -- 'ghe-update-check'
#### ghe-license-usage #### ghe-license-usage
This utility exports a list of the installation's users in JSON format. If your instance is connected to {{ site.data.variables.product.prodname_ghe_cloud }}, {{ site.data.variables.product.prodname_ghe_server }} uses this information for reporting licensing information to {{ site.data.variables.product.prodname_ghe_cloud }}. For more information, see "[Connecting {{ site.data.variables.product.prodname_ghe_server }} to {{ site.data.variables.product.prodname_ghe_cloud }} ](/enterprise/admin/installation/connecting-github-enterprise-server-to-github-enterprise-cloud)." This utility exports a list of the installation's users in JSON format. If your instance is connected to {% data variables.product.prodname_ghe_cloud %}, {% data variables.product.prodname_ghe_server %} uses this information for reporting licensing information to {% data variables.product.prodname_ghe_cloud %}. For more information, see "[Connecting {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} ](/enterprise/admin/installation/connecting-github-enterprise-server-to-github-enterprise-cloud)."
By default, the list of users in the resulting JSON file is encrypted. Use the `-h` flag for more options. By default, the list of users in the resulting JSON file is encrypted. Use the `-h` flag for more options.

20
content/admin/configuration/configuring-a-hostname.md
View File

@@ -9,20 +9,20 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
If you configure a hostname instead of a hard-coded IP address, you will be able to change the physical hardware that {{ site.data.variables.product.product_location_enterprise }} runs on without affecting users or client software. If you configure a hostname instead of a hard-coded IP address, you will be able to change the physical hardware that {% data variables.product.product_location_enterprise %} runs on without affecting users or client software.
The hostname setting in the {{ site.data.variables.enterprise.management_console }} should be set to an appropriate fully qualified domain name (FQDN) which is resolvable on the internet or within your internal network. For example, your hostname setting could be `github.companyname.com.` We also recommend enabling subdomain isolation for the chosen hostname to mitigate several cross-site scripting style vulnerabilities. For more information on hostname settings, see [Section 2.1 of the HTTP RFC](https://tools.ietf.org/html/rfc1123#section-2). The hostname setting in the {% data variables.enterprise.management_console %} should be set to an appropriate fully qualified domain name (FQDN) which is resolvable on the internet or within your internal network. For example, your hostname setting could be `github.companyname.com.` We also recommend enabling subdomain isolation for the chosen hostname to mitigate several cross-site scripting style vulnerabilities. For more information on hostname settings, see [Section 2.1 of the HTTP RFC](https://tools.ietf.org/html/rfc1123#section-2).
{{ site.data.reusables.enterprise_installation.changing-hostname-not-supported }} {% data reusables.enterprise_installation.changing-hostname-not-supported %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.hostname-menu-item }} {% data reusables.enterprise_management_console.hostname-menu-item %}
4. Type the hostname you'd like to set for {{ site.data.variables.product.product_location_enterprise }}. 4. Type the hostname you'd like to set for {% data variables.product.product_location_enterprise %}.
![Field for setting a hostname](/assets/images/enterprise/management-console/hostname-field.png) ![Field for setting a hostname](/assets/images/enterprise/management-console/hostname-field.png)
5. To test the DNS and SSL settings for the new hostname, click **Test domain settings**. 5. To test the DNS and SSL settings for the new hostname, click **Test domain settings**.
![Test domain settings button](/assets/images/enterprise/management-console/test-domain-settings.png) ![Test domain settings button](/assets/images/enterprise/management-console/test-domain-settings.png)
{{ site.data.reusables.enterprise_management_console.test-domain-settings-failure }} {% data reusables.enterprise_management_console.test-domain-settings-failure %}
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
After you configure a hostname, we recommend that you enable subdomain isolation for {{ site.data.variables.product.product_location_enterprise }}. For more information, see "[Enabling subdomain isolation](/enterprise/{{ currentVersion }}/admin/guides/installation/enabling-subdomain-isolation/)." After you configure a hostname, we recommend that you enable subdomain isolation for {% data variables.product.product_location_enterprise %}. For more information, see "[Enabling subdomain isolation](/enterprise/{{ currentVersion }}/admin/guides/installation/enabling-subdomain-isolation/)."

2
content/admin/configuration/configuring-advanced-security-features.md
View File

@@ -1,7 +1,7 @@
--- ---
title: Configuring Advanced Security features title: Configuring Advanced Security features
shortTitle: Configuring Advanced Security shortTitle: Configuring Advanced Security
intro: 'You can enable or disable {{ site.data.variables.product.prodname_advanced_security }} features, such as {{ site.data.variables.product.prodname_code_scanning }}, on your instance.' intro: 'You can enable or disable {% data variables.product.prodname_advanced_security %} features, such as {% data variables.product.prodname_code_scanning %}, on your instance.'
mapTopic: true mapTopic: true
redirect_from: redirect_from:
- /enterprise/admin/configuration/configuring-advanced-security-features - /enterprise/admin/configuration/configuring-advanced-security-features

14
content/admin/configuration/configuring-an-outbound-web-proxy-server.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring an outbound web proxy server title: Configuring an outbound web proxy server
intro: 'A proxy server provides an additional level of security for {{ site.data.variables.product.product_location_enterprise }}.' intro: 'A proxy server provides an additional level of security for {% data variables.product.product_location_enterprise %}.'
redirect_from: redirect_from:
- /enterprise/admin/guides/installation/configuring-a-proxy-server/ - /enterprise/admin/guides/installation/configuring-a-proxy-server/
- /enterprise/admin/installation/configuring-an-outbound-web-proxy-server - /enterprise/admin/installation/configuring-an-outbound-web-proxy-server
@@ -8,19 +8,19 @@ redirect_from:
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
When a proxy server is enabled for {{ site.data.variables.product.product_location_enterprise }}, outbound messages sent by {{ site.data.variables.product.prodname_ghe_server }} are first sent through the proxy server, unless the destination host is added as an HTTP proxy exclusion. Types of outbound messages include outgoing webhooks, uploading bundles, and fetching legacy avatars. The proxy server's URL is the protocol, domain or IP address, plus the port number, for example `http://127.0.0.1:8123`. When a proxy server is enabled for {% data variables.product.product_location_enterprise %}, outbound messages sent by {% data variables.product.prodname_ghe_server %} are first sent through the proxy server, unless the destination host is added as an HTTP proxy exclusion. Types of outbound messages include outgoing webhooks, uploading bundles, and fetching legacy avatars. The proxy server's URL is the protocol, domain or IP address, plus the port number, for example `http://127.0.0.1:8123`.
{% note %} {% note %}
**Note:** To connect {{ site.data.variables.product.product_location_enterprise }} to {{ site.data.variables.product.prodname_dotcom_the_website }}, your proxy configuration must allow connectivity to `github.com` and `api.github.com`. For more information, see "[Connecting {{ site.data.variables.product.prodname_ghe_server }} to {{ site.data.variables.product.prodname_dotcom_the_website }}](/enterprise/{{ currentVersion }}/admin/guides/developer-workflow/connecting-github-enterprise-server-to-github-com)." **Note:** To connect {% data variables.product.product_location_enterprise %} to {% data variables.product.prodname_dotcom_the_website %}, your proxy configuration must allow connectivity to `github.com` and `api.github.com`. For more information, see "[Connecting {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_dotcom_the_website %}](/enterprise/{{ currentVersion }}/admin/guides/developer-workflow/connecting-github-enterprise-server-to-github-com)."
{% endnote %} {% endnote %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.privacy }} {% data reusables.enterprise_management_console.privacy %}
4. Under **HTTP Proxy Server**, type the URL of your proxy server. 4. Under **HTTP Proxy Server**, type the URL of your proxy server.
![Field to type the HTTP Proxy Server URL](/assets/images/enterprise/management-console/http-proxy-field.png) ![Field to type the HTTP Proxy Server URL](/assets/images/enterprise/management-console/http-proxy-field.png)
5. Optionally, under **HTTP Proxy Exclusion**, type any hosts that do not require proxy access, separating hosts with commas. 5. Optionally, under **HTTP Proxy Exclusion**, type any hosts that do not require proxy access, separating hosts with commas.
![Field to type any HTTP Proxy Exclusions](/assets/images/enterprise/management-console/http-proxy-exclusion-field.png) ![Field to type any HTTP Proxy Exclusions](/assets/images/enterprise/management-console/http-proxy-exclusion-field.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}

12
content/admin/configuration/configuring-applications.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring applications title: Configuring applications
intro: 'You can configure internal application settings for {{ site.data.variables.product.product_location_enterprise }}.' intro: 'You can configure internal application settings for {% data variables.product.product_location_enterprise %}.'
redirect_from: redirect_from:
- /enterprise/admin/installation/configuring-applications - /enterprise/admin/installation/configuring-applications
- /enterprise/admin/configuration/configuring-applications - /enterprise/admin/configuration/configuring-applications
@@ -10,12 +10,12 @@ versions:
### Adjusting image caching ### Adjusting image caching
You can choose the amount of time that {{ site.data.variables.product.product_location_enterprise }} caches avatars. When you increase the cache time, you increase the amount of time a user's avatar will take to load. Configuring the cache time with too low a value can overload {{ site.data.variables.product.product_location_enterprise }} work processes. You can choose the amount of time that {% data variables.product.product_location_enterprise %} caches avatars. When you increase the cache time, you increase the amount of time a user's avatar will take to load. Configuring the cache time with too low a value can overload {% data variables.product.product_location_enterprise %} work processes.
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
3. In the left sidebar, click **Applications**. 3. In the left sidebar, click **Applications**.
![Applications tab in the settings sidebar](/assets/images/enterprise/management-console/sidebar-applications.png) ![Applications tab in the settings sidebar](/assets/images/enterprise/management-console/sidebar-applications.png)
4. Under "Avatar image cache time (seconds)", type the number of seconds that you would like {{ site.data.variables.product.product_location_enterprise }} to cache avatar images. 4. Under "Avatar image cache time (seconds)", type the number of seconds that you would like {% data variables.product.product_location_enterprise %} to cache avatar images.
![Avatar image caching form field](/assets/images/enterprise/management-console/add-image-caching-value-field.png) ![Avatar image caching form field](/assets/images/enterprise/management-console/add-image-caching-value-field.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}

34
content/admin/configuration/configuring-backups-on-your-appliance.md
View File

@@ -12,26 +12,26 @@ redirect_from:
- /enterprise/admin/guides/installation/backups-and-disaster-recovery/ - /enterprise/admin/guides/installation/backups-and-disaster-recovery/
- /enterprise/admin/installation/configuring-backups-on-your-appliance - /enterprise/admin/installation/configuring-backups-on-your-appliance
- /enterprise/admin/configuration/configuring-backups-on-your-appliance - /enterprise/admin/configuration/configuring-backups-on-your-appliance
intro: 'As part of a disaster recovery plan, you can protect production data on {{ site.data.variables.product.product_location_enterprise }} by configuring automated backups.' intro: 'As part of a disaster recovery plan, you can protect production data on {% data variables.product.product_location_enterprise %} by configuring automated backups.'
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### About {{ site.data.variables.product.prodname_enterprise_backup_utilities }} ### About {% data variables.product.prodname_enterprise_backup_utilities %}
{{ site.data.variables.product.prodname_enterprise_backup_utilities }} is a backup system you install on a separate host, which takes backup snapshots of {{ site.data.variables.product.product_location_enterprise }} at regular intervals over a secure SSH network connection. You can use a snapshot to restore an existing {{ site.data.variables.product.prodname_ghe_server }} instance to a previous state from the backup host. {% data variables.product.prodname_enterprise_backup_utilities %} is a backup system you install on a separate host, which takes backup snapshots of {% data variables.product.product_location_enterprise %} at regular intervals over a secure SSH network connection. You can use a snapshot to restore an existing {% data variables.product.prodname_ghe_server %} instance to a previous state from the backup host.
Only data added since the last snapshot will transfer over the network and occupy additional physical storage space. To minimize performance impact, backups are performed online under the lowest CPU/IO priority. You do not need to schedule a maintenance window to perform a backup. Only data added since the last snapshot will transfer over the network and occupy additional physical storage space. To minimize performance impact, backups are performed online under the lowest CPU/IO priority. You do not need to schedule a maintenance window to perform a backup.
For more detailed information on features, requirements, and advanced usage, see the [{{ site.data.variables.product.prodname_enterprise_backup_utilities }} README](https://github.com/github/backup-utils#readme). For more detailed information on features, requirements, and advanced usage, see the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#readme).
### Prerequisites ### Prerequisites
To use {{ site.data.variables.product.prodname_enterprise_backup_utilities }}, you must have a Linux or Unix host system separate from {{ site.data.variables.product.product_location_enterprise }}. To use {% data variables.product.prodname_enterprise_backup_utilities %}, you must have a Linux or Unix host system separate from {% data variables.product.product_location_enterprise %}.
You can also integrate {{ site.data.variables.product.prodname_enterprise_backup_utilities }} into an existing environment for long-term permanent storage of critical data. You can also integrate {% data variables.product.prodname_enterprise_backup_utilities %} into an existing environment for long-term permanent storage of critical data.
We recommend that the backup host and {{ site.data.variables.product.product_location_enterprise }} be geographically distant from each other. This ensures that backups are available for recovery in the event of a major disaster or network outage at the primary site. We recommend that the backup host and {% data variables.product.product_location_enterprise %} be geographically distant from each other. This ensures that backups are available for recovery in the event of a major disaster or network outage at the primary site.
Physical storage requirements will vary based on Git repository disk usage and expected growth patterns: Physical storage requirements will vary based on Git repository disk usage and expected growth patterns:
@@ -43,7 +43,7 @@ Physical storage requirements will vary based on Git repository disk usage and e
More resources may be required depending on your usage, such as user activity and selected integrations. More resources may be required depending on your usage, such as user activity and selected integrations.
### Installing {{ site.data.variables.product.prodname_enterprise_backup_utilities }} ### Installing {% data variables.product.prodname_enterprise_backup_utilities %}
{% note %} {% note %}
@@ -51,15 +51,15 @@ More resources may be required depending on your usage, such as user activity an
{% endnote %} {% endnote %}
1. Download the latest [{{ site.data.variables.product.prodname_enterprise_backup_utilities }} release](https://github.com/github/backup-utils/releases) and extract the file with the `tar` command. 1. Download the latest [{% data variables.product.prodname_enterprise_backup_utilities %} release](https://github.com/github/backup-utils/releases) and extract the file with the `tar` command.
```shell ```shell
$ tar -xzvf /path/to/github-backup-utils-v<em>MAJOR.MINOR.PATCH</em>.tar.gz $ tar -xzvf /path/to/github-backup-utils-v<em>MAJOR.MINOR.PATCH</em>.tar.gz
``` ```
2. Copy the included `backup.config-example` file to `backup.config` and open in an editor. 2. Copy the included `backup.config-example` file to `backup.config` and open in an editor.
3. Set the `GHE_HOSTNAME` value to your primary {{ site.data.variables.product.prodname_ghe_server }} instance's hostname or IP address. 3. Set the `GHE_HOSTNAME` value to your primary {% data variables.product.prodname_ghe_server %} instance's hostname or IP address.
4. Set the `GHE_DATA_DIR` value to the filesystem location where you want to store backup snapshots. 4. Set the `GHE_DATA_DIR` value to the filesystem location where you want to store backup snapshots.
5. Open your primary instance's settings page at `https://HOSTNAME/setup/settings` and add the backup host's SSH key to the list of authorized SSH keys. For more information, see [Accessing the administrative shell (SSH)](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-administrative-shell-ssh/). 5. Open your primary instance's settings page at `https://HOSTNAME/setup/settings` and add the backup host's SSH key to the list of authorized SSH keys. For more information, see [Accessing the administrative shell (SSH)](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-administrative-shell-ssh/).
5. Verify SSH connectivity with {{ site.data.variables.product.product_location_enterprise }} with the `ghe-host-check` command. 5. Verify SSH connectivity with {% data variables.product.product_location_enterprise %} with the `ghe-host-check` command.
```shell ```shell
$ bin/ghe-host-check $ bin/ghe-host-check
``` ```
@@ -68,19 +68,19 @@ More resources may be required depending on your usage, such as user activity an
$ bin/ghe-backup $ bin/ghe-backup
``` ```
For more information on advanced usage, see the [{{ site.data.variables.product.prodname_enterprise_backup_utilities }} README](https://github.com/github/backup-utils#readme). For more information on advanced usage, see the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#readme).
### Scheduling a backup ### Scheduling a backup
You can schedule regular backups on the backup host using the `cron(8)` command or a similar command scheduling service. The configured backup frequency will dictate the worst case recovery point objective (RPO) in your recovery plan. For example, if you have scheduled the backup to run every day at midnight, you could lose up to 24 hours of data in a disaster scenario. We recommend starting with an hourly backup schedule, guaranteeing a worst case maximum of one hour of data loss if the primary site data is destroyed. You can schedule regular backups on the backup host using the `cron(8)` command or a similar command scheduling service. The configured backup frequency will dictate the worst case recovery point objective (RPO) in your recovery plan. For example, if you have scheduled the backup to run every day at midnight, you could lose up to 24 hours of data in a disaster scenario. We recommend starting with an hourly backup schedule, guaranteeing a worst case maximum of one hour of data loss if the primary site data is destroyed.
If backup attempts overlap, the `ghe-backup` command will abort with an error message, indicating the existence of a simultaneous backup. If this occurs, we recommended decreasing the frequency of your scheduled backups. For more information, see the "Scheduling backups" section of the [{{ site.data.variables.product.prodname_enterprise_backup_utilities }} README](https://github.com/github/backup-utils#scheduling-backups). If backup attempts overlap, the `ghe-backup` command will abort with an error message, indicating the existence of a simultaneous backup. If this occurs, we recommended decreasing the frequency of your scheduled backups. For more information, see the "Scheduling backups" section of the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#scheduling-backups).
### Restoring a backup ### Restoring a backup
In the event of prolonged outage or catastrophic event at the primary site, you can restore {{ site.data.variables.product.product_location_enterprise }} by provisioning another {{ site.data.variables.product.prodname_enterprise }} appliance and performing a restore from the backup host. You must add the backup host's SSH key to the target {{ site.data.variables.product.prodname_enterprise }} appliance as an authorized SSH key before restoring an appliance. In the event of prolonged outage or catastrophic event at the primary site, you can restore {% data variables.product.product_location_enterprise %} by provisioning another {% data variables.product.prodname_enterprise %} appliance and performing a restore from the backup host. You must add the backup host's SSH key to the target {% data variables.product.prodname_enterprise %} appliance as an authorized SSH key before restoring an appliance.
To restore {{ site.data.variables.product.product_location_enterprise }} from the last successful snapshot, use the `ghe-restore` command. You should see output similar to this: To restore {% data variables.product.product_location_enterprise %} from the last successful snapshot, use the `ghe-restore` command. You should see output similar to this:
```shell ```shell
$ ghe-restore -c 169.154.1.1 $ ghe-restore -c 169.154.1.1
@@ -101,11 +101,11 @@ $ ghe-restore -c 169.154.1.1
{% note %} {% note %}
**Note:** The network settings are excluded from the backup snapshot. You must manually configure the network on the target {{ site.data.variables.product.prodname_ghe_server }} appliance as required for your environment. **Note:** The network settings are excluded from the backup snapshot. You must manually configure the network on the target {% data variables.product.prodname_ghe_server %} appliance as required for your environment.
{% endnote %} {% endnote %}
You can use these additional options with `ghe-restore` command: You can use these additional options with `ghe-restore` command:
- The `-c` flag overwrites the settings, certificate, and license data on the target host even if it is already configured. Omit this flag if you are setting up a staging instance for testing purposes and you wish to retain the existing configuration on the target. For more information, see the "Using using backup and restore commands" section of the [{{ site.data.variables.product.prodname_enterprise_backup_utilities }} README](https://github.com/github/backup-utils#using-the-backup-and-restore-commands). - The `-c` flag overwrites the settings, certificate, and license data on the target host even if it is already configured. Omit this flag if you are setting up a staging instance for testing purposes and you wish to retain the existing configuration on the target. For more information, see the "Using using backup and restore commands" section of the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#using-the-backup-and-restore-commands).
- The `-s` flag allows you to select a different backup snapshot. - The `-s` flag allows you to select a different backup snapshot.

20
content/admin/configuration/configuring-built-in-firewall-rules.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring built-in firewall rules title: Configuring built-in firewall rules
intro: 'You can view default firewall rules and customize rules for {{ site.data.variables.product.product_location_enterprise }}.' intro: 'You can view default firewall rules and customize rules for {% data variables.product.product_location_enterprise %}.'
redirect_from: redirect_from:
- /enterprise/admin/guides/installation/configuring-firewall-settings/ - /enterprise/admin/guides/installation/configuring-firewall-settings/
- /enterprise/admin/installation/configuring-built-in-firewall-rules - /enterprise/admin/installation/configuring-built-in-firewall-rules
@@ -9,17 +9,17 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### About {{ site.data.variables.product.product_location_enterprise }}'s firewall ### About {% data variables.product.product_location_enterprise %}'s firewall
{{ site.data.variables.product.prodname_ghe_server }} uses Ubuntu's Uncomplicated Firewall (UFW) on the virtual appliance. For more information see "[UFW](https://help.ubuntu.com/community/UFW)" in the Ubuntu documentation. {{ site.data.variables.product.prodname_ghe_server }} automatically updates the firewall allowlist of allowed services with each release. {% data variables.product.prodname_ghe_server %} uses Ubuntu's Uncomplicated Firewall (UFW) on the virtual appliance. For more information see "[UFW](https://help.ubuntu.com/community/UFW)" in the Ubuntu documentation. {% data variables.product.prodname_ghe_server %} automatically updates the firewall allowlist of allowed services with each release.
After you install {{ site.data.variables.product.prodname_ghe_server }}, all required network ports are automatically opened to accept connections. Every non-required port is automatically configured as `deny`, and the default outgoing policy is configured as `allow`. Stateful tracking is enabled for any new connections; these are typically network packets with the `SYN` bit set. For more information, see "[Network ports](/enterprise/admin/guides/installation/network-ports)." After you install {% data variables.product.prodname_ghe_server %}, all required network ports are automatically opened to accept connections. Every non-required port is automatically configured as `deny`, and the default outgoing policy is configured as `allow`. Stateful tracking is enabled for any new connections; these are typically network packets with the `SYN` bit set. For more information, see "[Network ports](/enterprise/admin/guides/installation/network-ports)."
The UFW firewall also opens several other ports that are required for {{ site.data.variables.product.prodname_ghe_server }} to operate properly. For more information on the UFW ruleset, see [the UFW README](https://bazaar.launchpad.net/~jdstrand/ufw/0.30-oneiric/view/head:/README#L213). The UFW firewall also opens several other ports that are required for {% data variables.product.prodname_ghe_server %} to operate properly. For more information on the UFW ruleset, see [the UFW README](https://bazaar.launchpad.net/~jdstrand/ufw/0.30-oneiric/view/head:/README#L213).
### Viewing the default firewall rules ### Viewing the default firewall rules
{{ site.data.reusables.enterprise_installation.ssh-into-instance }} {% data reusables.enterprise_installation.ssh-into-instance %}
2. To view the default firewall rules, use the `sudo ufw status` command. You should see output similar to this: 2. To view the default firewall rules, use the `sudo ufw status` command. You should see output similar to this:
```shell ```shell
$ sudo ufw status $ sudo ufw status
@@ -52,7 +52,7 @@ The UFW firewall also opens several other ports that are required for {{ site.da
{% warning %} {% warning %}
**Warning:** Before you add custom firewall rules, back up your current rules in case you need to reset to a known working state. If you're locked out of your server, contact {{ site.data.variables.contact.contact_ent_support }} to reconfigure the original firewall rules. Restoring the original firewall rules involves downtime for your server. **Warning:** Before you add custom firewall rules, back up your current rules in case you need to reset to a known working state. If you're locked out of your server, contact {% data variables.contact.contact_ent_support %} to reconfigure the original firewall rules. Restoring the original firewall rules involves downtime for your server.
{% endwarning %} {% endwarning %}
@@ -66,7 +66,7 @@ The UFW firewall also opens several other ports that are required for {{ site.da
$ sudo cp -r /lib/ufw ~/ufw.backup $ sudo cp -r /lib/ufw ~/ufw.backup
``` ```
After you upgrade {{ site.data.variables.product.product_location_enterprise }}, you must reapply your custom firewall rules. We recommend that you create a script to reapply your firewall custom rules. After you upgrade {% data variables.product.product_location_enterprise %}, you must reapply your custom firewall rules. We recommend that you create a script to reapply your firewall custom rules.
### Restoring the default firewall rules ### Restoring the default firewall rules
@@ -74,11 +74,11 @@ If something goes wrong after you change the firewall rules, you can reset the r
{% warning %} {% warning %}
**Warning:** If you didn't back up the original rules before making changes to the firewall, contact {{ site.data.variables.contact.contact_ent_support }} for further assistance. **Warning:** If you didn't back up the original rules before making changes to the firewall, contact {% data variables.contact.contact_ent_support %} for further assistance.
{% endwarning %} {% endwarning %}
{{ site.data.reusables.enterprise_installation.ssh-into-instance }} {% data reusables.enterprise_installation.ssh-into-instance %}
2. To restore the previous backup rules, copy them back to the firewall with the `cp` command. 2. To restore the previous backup rules, copy them back to the firewall with the `cp` command.
```shell ```shell
$ sudo cp -f ~/ufw.backup/*rules /lib/ufw $ sudo cp -f ~/ufw.backup/*rules /lib/ufw

88
content/admin/configuration/configuring-code-scanning-for-your-appliance.md
View File

@@ -1,8 +1,8 @@
--- ---
title: Configuring code scanning for your appliance title: Configuring code scanning for your appliance
shortTitle: Configuring code scanning shortTitle: Configuring code scanning
intro: 'You can enable, configure and disable {{ site.data.variables.product.prodname_code_scanning }} for {{ site.data.variables.product.product_location_enterprise }}. {{ site.data.variables.product.prodname_code_scanning_capc}} allows users to scan code for vulnerabilities and errors.' intro: 'You can enable, configure and disable {% data variables.product.prodname_code_scanning %} for {% data variables.product.product_location_enterprise %}. {% data variables.product.prodname_code_scanning_capc %} allows users to scan code for vulnerabilities and errors.'
product: '{{ site.data.reusables.gated-features.code-scanning }}' product: '{% data reusables.gated-features.code-scanning %}'
miniTocMaxHeadingLevel: 4 miniTocMaxHeadingLevel: 4
redirect_from: redirect_from:
- /enterprise/admin/configuration/configuring-code-scanning-for-your-appliance - /enterprise/admin/configuration/configuring-code-scanning-for-your-appliance
@@ -10,76 +10,76 @@ versions:
enterprise-server: '>=2.22' enterprise-server: '>=2.22'
--- ---
{{ site.data.reusables.code-scanning.beta }} {% data reusables.code-scanning.beta %}
### About {{ site.data.variables.product.prodname_code_scanning }} ### About {% data variables.product.prodname_code_scanning %}
{{ site.data.reusables.code-scanning.about-code-scanning }} {% data reusables.code-scanning.about-code-scanning %}
The table below summarizes the available types of analysis for {{ site.data.variables.product.prodname_code_scanning }}, and provides links on enabling the feature for individual repositories. The table below summarizes the available types of analysis for {% data variables.product.prodname_code_scanning %}, and provides links on enabling the feature for individual repositories.
{{ site.data.reusables.code-scanning.enabling-options }} {% data reusables.code-scanning.enabling-options %}
For the users of {{ site.data.variables.product.product_location_enterprise }} to be able to enable and use {{ site.data.variables.product.prodname_code_scanning }} in their repositories, you need, as a site administrator, to enable this feature for the whole appliance. For the users of {% data variables.product.product_location_enterprise %} to be able to enable and use {% data variables.product.prodname_code_scanning %} in their repositories, you need, as a site administrator, to enable this feature for the whole appliance.
### How do I know if {{ site.data.variables.product.prodname_code_scanning }} is enabled for my appliance ### How do I know if {% data variables.product.prodname_code_scanning %} is enabled for my appliance
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
1. Check if there is an **{{ site.data.variables.product.prodname_advanced_security }}** entry in the left sidebar. 1. Check if there is an **{% data variables.product.prodname_advanced_security %}** entry in the left sidebar.
![Advanced Security sidebar](/assets/images/enterprise/management-console/sidebar-advanced-security.png) ![Advanced Security sidebar](/assets/images/enterprise/management-console/sidebar-advanced-security.png)
If you can't see **{{ site.data.variables.product.prodname_advanced_security }}** in the sidebar, it means that your license doesn't include support for {{ site.data.variables.product.prodname_advanced_security }} features including {{ site.data.variables.product.prodname_code_scanning }}. The {{ site.data.variables.product.prodname_advanced_security }} license gives you and your users access to features that help you make your repositories and code more secure. If you can't see **{% data variables.product.prodname_advanced_security %}** in the sidebar, it means that your license doesn't include support for {% data variables.product.prodname_advanced_security %} features including {% data variables.product.prodname_code_scanning %}. The {% data variables.product.prodname_advanced_security %} license gives you and your users access to features that help you make your repositories and code more secure.
### Enabling {{ site.data.variables.product.prodname_code_scanning }} ### Enabling {% data variables.product.prodname_code_scanning %}
{{ site.data.reusables.enterprise_management_console.enable-disable-code-scanning }} {% data reusables.enterprise_management_console.enable-disable-code-scanning %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.advanced-security-tab }} {% data reusables.enterprise_management_console.advanced-security-tab %}
1. Under "{{ site.data.variables.product.prodname_advanced_security }}," click **{{ site.data.variables.product.prodname_code_scanning_capc }}**. 1. Under "{% data variables.product.prodname_advanced_security %}," click **{% data variables.product.prodname_code_scanning_capc %}**.
![Checkbox to enable or disable {{ site.data.variables.product.prodname_code_scanning }}](/assets/images/enterprise/management-console/enable-code-scanning-checkbox.png) ![Checkbox to enable or disable {% data variables.product.prodname_code_scanning %}](/assets/images/enterprise/management-console/enable-code-scanning-checkbox.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### Running {{ site.data.variables.product.prodname_code_scanning }} using {{ site.data.variables.product.prodname_actions }} ### Running {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_actions %}
#### Setting up a self-hosted runner #### Setting up a self-hosted runner
If you are enrolled in the {{ site.data.variables.product.prodname_actions }} beta, then {{ site.data.variables.product.prodname_ghe_server }} can run {{ site.data.variables.product.prodname_code_scanning}} using a {{ site.data.variables.product.prodname_actions }} workflow. First, you need to provision one or more self-hosted {{ site.data.variables.product.prodname_actions }} runners in your environment. You can provision self-hosted runners at the repository, organization, or enterprise account level. For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners)" and "[Adding self-hosted runners](/actions/hosting-your-own-runners/adding-self-hosted-runners)." If you are enrolled in the {% data variables.product.prodname_actions %} beta, then {% data variables.product.prodname_ghe_server %} can run {% data variables.product.prodname_code_scanning %} using a {% data variables.product.prodname_actions %} workflow. First, you need to provision one or more self-hosted {% data variables.product.prodname_actions %} runners in your environment. You can provision self-hosted runners at the repository, organization, or enterprise account level. For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners/about-self-hosted-runners)" and "[Adding self-hosted runners](/actions/hosting-your-own-runners/adding-self-hosted-runners)."
You must ensure that Git is in the PATH variable on any self-hosted runners you use to run {{ site.data.variables.product.prodname_codeql }} actions. You must ensure that Git is in the PATH variable on any self-hosted runners you use to run {% data variables.product.prodname_codeql %} actions.
#### Provisioning the action #### Provisioning the action
To run {{ site.data.variables.product.prodname_code_scanning}} on {{ site.data.variables.product.prodname_ghe_server }} with {{ site.data.variables.product.prodname_actions }}, the appropriate action must be available locally. You can make the action available in three ways. To run {% data variables.product.prodname_code_scanning %} on {% data variables.product.prodname_ghe_server %} with {% data variables.product.prodname_actions %}, the appropriate action must be available locally. You can make the action available in three ways.
- **Recommended** You can use [{{ site.data.variables.product.prodname_github_connect }}](/enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud) to automatically download actions from {{ site.data.variables.product.prodname_dotcom_the_website }}. The machine that hosts your instance must be able to access {{ site.data.variables.product.prodname_dotcom_the_website }}. This approach ensures that you get the latest software automatically. For more information, see "[Configuring {{ site.data.variables.product.prodname_github_connect }} to sync {{ site.data.variables.product.prodname_actions }}](/enterprise/admin/configuration/configuring-code-scanning-for-your-appliance#configuring-github-connect-to-sync-github-actions)." - **Recommended** You can use [{% data variables.product.prodname_github_connect %}](/enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud) to automatically download actions from {% data variables.product.prodname_dotcom_the_website %}. The machine that hosts your instance must be able to access {% data variables.product.prodname_dotcom_the_website %}. This approach ensures that you get the latest software automatically. For more information, see "[Configuring {% data variables.product.prodname_github_connect %} to sync {% data variables.product.prodname_actions %}](/enterprise/admin/configuration/configuring-code-scanning-for-your-appliance#configuring-github-connect-to-sync-github-actions)."
- If you want to use the {{ site.data.variables.product.prodname_codeql_workflow }}, you can sync the repository from {{ site.data.variables.product.prodname_dotcom_the_website }} to {{ site.data.variables.product.prodname_ghe_server }}, by using the {{ site.data.variables.product.prodname_codeql }} Action sync tool available at [https://github.com/github/codeql-action-sync-tool](https://github.com/github/codeql-action-sync-tool/). You can use this tool regardless of whether {{ site.data.variables.product.product_location_enterprise }} or your {{ site.data.variables.product.prodname_actions }} runners have access to the internet, as long as you can access both {{ site.data.variables.product.product_location_enterprise }} and {{ site.data.variables.product.prodname_dotcom_the_website }} simultaneously on your computer. - If you want to use the {% data variables.product.prodname_codeql_workflow %}, you can sync the repository from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %}, by using the {% data variables.product.prodname_codeql %} Action sync tool available at [https://github.com/github/codeql-action-sync-tool](https://github.com/github/codeql-action-sync-tool/). You can use this tool regardless of whether {% data variables.product.product_location_enterprise %} or your {% data variables.product.prodname_actions %} runners have access to the internet, as long as you can access both {% data variables.product.product_location_enterprise %} and {% data variables.product.prodname_dotcom_the_website %} simultaneously on your computer.
- You can create a local copy of the action's repository on your server, by cloning the {{ site.data.variables.product.prodname_dotcom_the_website }} repository with the action. For example, if you want to use the {{ site.data.variables.product.prodname_codeql }} action, you can create a repository in your instance called `github/codeql-action`, then clone the [repository](https://github.com/github/codeql-action) from {{ site.data.variables.product.prodname_dotcom_the_website }}, and then push that repository to your instance's `github/codeql-action` repository. You will also need to download any of the releases from the repository on {{ site.data.variables.product.prodname_dotcom_the_website }} and upload them to your instance's `github/codeql-action` repository as releases. - You can create a local copy of the action's repository on your server, by cloning the {% data variables.product.prodname_dotcom_the_website %} repository with the action. For example, if you want to use the {% data variables.product.prodname_codeql %} action, you can create a repository in your instance called `github/codeql-action`, then clone the [repository](https://github.com/github/codeql-action) from {% data variables.product.prodname_dotcom_the_website %}, and then push that repository to your instance's `github/codeql-action` repository. You will also need to download any of the releases from the repository on {% data variables.product.prodname_dotcom_the_website %} and upload them to your instance's `github/codeql-action` repository as releases.
##### Configuring {{ site.data.variables.product.prodname_github_connect }} to sync {{ site.data.variables.product.prodname_actions }} ##### Configuring {% data variables.product.prodname_github_connect %} to sync {% data variables.product.prodname_actions %}
1. If you want to download action workflows on demand from {{ site.data.variables.product.prodname_dotcom_the_website }}, you need to enable {{ site.data.variables.product.prodname_github_connect }}. For more information, see "[Enabling {{ site.data.variables.product.prodname_github_connect }}](/enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud#enabling-github-connect)." 1. If you want to download action workflows on demand from {% data variables.product.prodname_dotcom_the_website %}, you need to enable {% data variables.product.prodname_github_connect %}. For more information, see "[Enabling {% data variables.product.prodname_github_connect %}](/enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud#enabling-github-connect)."
2. You'll also need to enable {{ site.data.variables.product.prodname_actions }} for {{ site.data.variables.product.product_location_enterprise }}. For more information, see "[Enabling {{ site.data.variables.product.prodname_actions }} and configuring storage](/enterprise/admin/github-actions/enabling-github-actions-and-configuring-storage)." 2. You'll also need to enable {% data variables.product.prodname_actions %} for {% data variables.product.product_location_enterprise %}. For more information, see "[Enabling {% data variables.product.prodname_actions %} and configuring storage](/enterprise/admin/github-actions/enabling-github-actions-and-configuring-storage)."
3. The next step is to configure access to actions on {{ site.data.variables.product.prodname_dotcom_the_website }} using {{ site.data.variables.product.prodname_github_connect }}. For more information, see "[Enabling automatic access to {{ site.data.variables.product.prodname_dotcom_the_website }} actions using {{ site.data.variables.product.prodname_github_connect }}](/enterprise/admin/github-actions/enabling-automatic-access-to-githubcom-actions-using-github-connect)." 3. The next step is to configure access to actions on {% data variables.product.prodname_dotcom_the_website %} using {% data variables.product.prodname_github_connect %}. For more information, see "[Enabling automatic access to {% data variables.product.prodname_dotcom_the_website %} actions using {% data variables.product.prodname_github_connect %}](/enterprise/admin/github-actions/enabling-automatic-access-to-githubcom-actions-using-github-connect)."
4. Add a self-hosted runner to your repository, organization, or enterprise account. For more information, see "[Adding self-hosted runners](/actions/hosting-your-own-runners/adding-self-hosted-runners)." 4. Add a self-hosted runner to your repository, organization, or enterprise account. For more information, see "[Adding self-hosted runners](/actions/hosting-your-own-runners/adding-self-hosted-runners)."
After you configure a self-hosted runner, users can enable {{ site.data.variables.product.prodname_code_scanning }} for individual repositories on {{ site.data.variables.product.product_location_enterprise }}. For more information, see "[Enabling {{ site.data.variables.product.prodname_code_scanning }} for a repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository)." After you configure a self-hosted runner, users can enable {% data variables.product.prodname_code_scanning %} for individual repositories on {% data variables.product.product_location_enterprise %}. For more information, see "[Enabling {% data variables.product.prodname_code_scanning %} for a repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository)."
### Running {{ site.data.variables.product.prodname_code_scanning }} using the {{ site.data.variables.product.prodname_codeql_runner }} ### Running {% data variables.product.prodname_code_scanning %} using the {% data variables.product.prodname_codeql_runner %}
If your organization isn't taking part in the beta for {{ site.data.variables.product.prodname_actions }}, or if you don't want to use {{ site.data.variables.product.prodname_actions }}, you can run {{ site.data.variables.product.prodname_code_scanning }} using the {{ site.data.variables.product.prodname_codeql_runner }}. If your organization isn't taking part in the beta for {% data variables.product.prodname_actions %}, or if you don't want to use {% data variables.product.prodname_actions %}, you can run {% data variables.product.prodname_code_scanning %} using the {% data variables.product.prodname_codeql_runner %}.
The {{ site.data.variables.product.prodname_codeql_runner }} is a command-line tool that you can add to your third-party CI/CD system. The tool runs {{ site.data.variables.product.prodname_codeql }} analysis on a checkout of a {{ site.data.variables.product.prodname_dotcom }} repository. For more information, see "[Running {{ site.data.variables.product.prodname_code_scanning }} in your CI system](/github/finding-security-vulnerabilities-and-errors-in-your-code/running-code-scanning-in-your-ci-system)." The {% data variables.product.prodname_codeql_runner %} is a command-line tool that you can add to your third-party CI/CD system. The tool runs {% data variables.product.prodname_codeql %} analysis on a checkout of a {% data variables.product.prodname_dotcom %} repository. For more information, see "[Running {% data variables.product.prodname_code_scanning %} in your CI system](/github/finding-security-vulnerabilities-and-errors-in-your-code/running-code-scanning-in-your-ci-system)."
### Disabling {{ site.data.variables.product.prodname_code_scanning }} ### Disabling {% data variables.product.prodname_code_scanning %}
{{ site.data.reusables.enterprise_management_console.enable-disable-code-scanning }} {% data reusables.enterprise_management_console.enable-disable-code-scanning %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.advanced-security-tab }} {% data reusables.enterprise_management_console.advanced-security-tab %}
1. Under "{{ site.data.variables.product.prodname_advanced_security }}", unselect **{{ site.data.variables.product.prodname_code_scanning_capc }}**. 1. Under "{% data variables.product.prodname_advanced_security %}", unselect **{% data variables.product.prodname_code_scanning_capc %}**.
![Checkbox to enable or disable {{ site.data.variables.product.prodname_code_scanning }}](/assets/images/enterprise/management-console/code-scanning-disable.png) ![Checkbox to enable or disable {% data variables.product.prodname_code_scanning %}](/assets/images/enterprise/management-console/code-scanning-disable.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}

14
content/admin/configuration/configuring-dns-nameservers.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring DNS nameservers title: Configuring DNS nameservers
intro: '{{ site.data.variables.product.prodname_ghe_server }} uses the dynamic host configuration protocol (DHCP) for DNS settings when DHCP leases provide nameservers. If nameservers are not provided by a dynamic host configuration protocol (DHCP) lease, or if you need to use specific DNS settings, you can specify the nameservers manually.' intro: '{% data variables.product.prodname_ghe_server %} uses the dynamic host configuration protocol (DHCP) for DNS settings when DHCP leases provide nameservers. If nameservers are not provided by a dynamic host configuration protocol (DHCP) lease, or if you need to use specific DNS settings, you can specify the nameservers manually.'
redirect_from: redirect_from:
- /enterprise/admin/guides/installation/about-dns-nameservers/ - /enterprise/admin/guides/installation/about-dns-nameservers/
- /enterprise/admin/installation/configuring-dns-nameservers - /enterprise/admin/installation/configuring-dns-nameservers
@@ -9,26 +9,26 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
The nameservers you specify must resolve {{ site.data.variables.product.product_location_enterprise }}'s hostname. The nameservers you specify must resolve {% data variables.product.product_location_enterprise %}'s hostname.
{{ site.data.reusables.enterprise_installation.changing-hostname-not-supported }} {% data reusables.enterprise_installation.changing-hostname-not-supported %}
### Configuring nameservers using the virtual machine console ### Configuring nameservers using the virtual machine console
{{ site.data.reusables.enterprise_installation.open-vm-console-start }} {% data reusables.enterprise_installation.open-vm-console-start %}
2. Configure nameservers for your instance. 2. Configure nameservers for your instance.
{{ site.data.reusables.enterprise_installation.vm-console-done }} {% data reusables.enterprise_installation.vm-console-done %}
### Configuring nameservers using the administrative shell ### Configuring nameservers using the administrative shell
{{ site.data.reusables.enterprise_installation.ssh-into-instance }} {% data reusables.enterprise_installation.ssh-into-instance %}
2. To edit your nameservers, enter: 2. To edit your nameservers, enter:
```shell ```shell
$ sudo vim /etc/resolvconf/resolv.conf.d/head $ sudo vim /etc/resolvconf/resolv.conf.d/head
``` ```
3. Append any `nameserver` entries, then save the file. 3. Append any `nameserver` entries, then save the file.
4. After verifying your changes, save the file. 4. After verifying your changes, save the file.
5. To add your new nameserver entries to {{ site.data.variables.product.product_location_enterprise }}, enter: 5. To add your new nameserver entries to {% data variables.product.product_location_enterprise %}, enter:
```shell ```shell
$ sudo service resolvconf restart $ sudo service resolvconf restart
``` ```

30
content/admin/configuration/configuring-github-pages-on-your-appliance.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring GitHub Pages on your appliance title: Configuring GitHub Pages on your appliance
intro: 'You can enable or disable {{ site.data.variables.product.prodname_pages }} on your instance. You can also choose to make {{ site.data.variables.product.prodname_pages }} sites publicly accessible.' intro: 'You can enable or disable {% data variables.product.prodname_pages %} on your instance. You can also choose to make {% data variables.product.prodname_pages %} sites publicly accessible.'
redirect_from: redirect_from:
- /enterprise/admin/guides/installation/disabling-github-enterprise-pages/ - /enterprise/admin/guides/installation/disabling-github-enterprise-pages/
- /enterprise/admin/guides/installation/configuring-github-enterprise-pages/ - /enterprise/admin/guides/installation/configuring-github-enterprise-pages/
@@ -10,33 +10,33 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### Making {{ site.data.variables.product.prodname_pages }} publicly accessible ### Making {% data variables.product.prodname_pages %} publicly accessible
If private mode is enabled on your instance, the public cannot access {{ site.data.variables.product.prodname_pages }} sites hosted on {{ site.data.variables.product.product_location_enterprise }}. If private mode is enabled on your instance, the public cannot access {% data variables.product.prodname_pages %} sites hosted on {% data variables.product.product_location_enterprise %}.
{% warning %} {% warning %}
**Warning:** If you enable public {{ site.data.variables.product.prodname_pages }} sites, every {{ site.data.variables.product.prodname_pages }} site in every repository on your instance will be accessible to the public. **Warning:** If you enable public {% data variables.product.prodname_pages %} sites, every {% data variables.product.prodname_pages %} site in every repository on your instance will be accessible to the public.
{% endwarning %} {% endwarning %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.pages-tab }} {% data reusables.enterprise_management_console.pages-tab %}
4. Select **Public Pages**. 4. Select **Public Pages**.
![Checkbox to enable Public Pages](/assets/images/enterprise/management-console/public-pages-checkbox.png) ![Checkbox to enable Public Pages](/assets/images/enterprise/management-console/public-pages-checkbox.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### Disabling {{ site.data.variables.product.prodname_pages }} on {{ site.data.variables.product.product_location_enterprise }} ### Disabling {% data variables.product.prodname_pages %} on {% data variables.product.product_location_enterprise %}
If subdomain isolation is disabled for {{ site.data.variables.product.product_location_enterprise }}, you should also disable {{ site.data.variables.product.prodname_pages }} to protect yourself from potential security vulnerabilities. For more information, see "[Enabling subdomain isolation](/enterprise/{{ currentVersion }}/admin/guides/installation/enabling-subdomain-isolation)." If subdomain isolation is disabled for {% data variables.product.product_location_enterprise %}, you should also disable {% data variables.product.prodname_pages %} to protect yourself from potential security vulnerabilities. For more information, see "[Enabling subdomain isolation](/enterprise/{{ currentVersion }}/admin/guides/installation/enabling-subdomain-isolation)."
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.pages-tab }} {% data reusables.enterprise_management_console.pages-tab %}
4. Unselect **Enable Pages**. 4. Unselect **Enable Pages**.
![Checkbox to disable {{ site.data.variables.product.prodname_pages }}](/assets/images/enterprise/management-console/pages-select-button.png) ![Checkbox to disable {% data variables.product.prodname_pages %}](/assets/images/enterprise/management-console/pages-select-button.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### Further reading ### Further reading

2
content/admin/configuration/configuring-network-settings.md
View File

@@ -7,7 +7,7 @@ redirect_from:
- /enterprise/admin/guides/installation/configuring-your-github-enterprise-network-settings/ - /enterprise/admin/guides/installation/configuring-your-github-enterprise-network-settings/
- /enterprise/admin/installation/configuring-your-github-enterprise-server-network-settings - /enterprise/admin/installation/configuring-your-github-enterprise-server-network-settings
- /enterprise/admin/configuration/configuring-network-settings - /enterprise/admin/configuration/configuring-network-settings
intro: 'Configure {{ site.data.variables.product.prodname_ghe_server }} with the DNS nameservers and hostname required in your network. You can also configure a proxy server or firewall rules. You must allow access to certain ports for administrative and user purposes.' intro: 'Configure {% data variables.product.prodname_ghe_server %} with the DNS nameservers and hostname required in your network. You can also configure a proxy server or firewall rules. You must allow access to certain ports for administrative and user purposes.'
mapTopic: true mapTopic: true
versions: versions:
enterprise-server: '*' enterprise-server: '*'

28
content/admin/configuration/configuring-rate-limits.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring rate limits title: Configuring rate limits
intro: 'You can set rate limits for {{ site.data.variables.product.prodname_ghe_server }} using the {{ site.data.variables.enterprise.management_console }}.' intro: 'You can set rate limits for {% data variables.product.prodname_ghe_server %} using the {% data variables.enterprise.management_console %}.'
redirect_from: redirect_from:
- /enterprise/admin/installation/configuring-rate-limits - /enterprise/admin/installation/configuring-rate-limits
- /enterprise/admin/configuration/configuring-rate-limits - /enterprise/admin/configuration/configuring-rate-limits
@@ -8,9 +8,9 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### Enabling rate limits for {{ site.data.variables.product.prodname_enterprise_api }} ### Enabling rate limits for {% data variables.product.prodname_enterprise_api %}
Enabling rate limits on {{ site.data.variables.product.prodname_enterprise_api }} can prevent overuse of resources by individual or unauthenticated users. For more information, see "[Resources in the REST API](/rest/overview/resources-in-the-rest-api#rate-limiting)." Enabling rate limits on {% data variables.product.prodname_enterprise_api %} can prevent overuse of resources by individual or unauthenticated users. For more information, see "[Resources in the REST API](/rest/overview/resources-in-the-rest-api#rate-limiting)."
{% if currentVersion ver_gt "enterprise-server@2.21" %} {% if currentVersion ver_gt "enterprise-server@2.21" %}
You can exempt a list of users from API rate limits using the `ghe-config` utility in the administrative shell. For more information, see "[Command-line utilities](/enterprise/admin/configuration/command-line-utilities#ghe-config)." You can exempt a list of users from API rate limits using the `ghe-config` utility in the administrative shell. For more information, see "[Command-line utilities](/enterprise/admin/configuration/command-line-utilities#ghe-config)."
@@ -18,36 +18,36 @@ You can exempt a list of users from API rate limits using the `ghe-config` utili
{% note %} {% note %}
**Note:** The {{ site.data.variables.enterprise.management_console }} lists the time period (per minute or per hour) for each rate limit. **Note:** The {% data variables.enterprise.management_console %} lists the time period (per minute or per hour) for each rate limit.
{% endnote %} {% endnote %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
2. Under "Rate Limiting", select **Enable API Rate Limiting**. 2. Under "Rate Limiting", select **Enable API Rate Limiting**.
![Checkbox for enabling API rate limiting](/assets/images/enterprise/management-console/api-rate-limits-checkbox.png) ![Checkbox for enabling API rate limiting](/assets/images/enterprise/management-console/api-rate-limits-checkbox.png)
3. Type limits for authenticated and unauthenticated requests for each API, or accept the pre-filled default limits. 3. Type limits for authenticated and unauthenticated requests for each API, or accept the pre-filled default limits.
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### Enabling abuse rate limits ### Enabling abuse rate limits
Setting abuse rate limits protects the overall level of service on {{ site.data.variables.product.product_location_enterprise }}. Setting abuse rate limits protects the overall level of service on {% data variables.product.product_location_enterprise %}.
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
2. Under "Rate Limiting", select **Enable Abuse Rate Limiting**. 2. Under "Rate Limiting", select **Enable Abuse Rate Limiting**.
![Checkbox for enabling abuse rate limiting](/assets/images/enterprise/management-console/abuse-rate-limits-checkbox.png) ![Checkbox for enabling abuse rate limiting](/assets/images/enterprise/management-console/abuse-rate-limits-checkbox.png)
3. Type limits for Total Requests, CPU Limit, and CPU Limit for Searching, or accept the pre-filled default limits. 3. Type limits for Total Requests, CPU Limit, and CPU Limit for Searching, or accept the pre-filled default limits.
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### Enabling Git rate limits ### Enabling Git rate limits
You can apply Git rate limits per repository network or per user ID. Git rate limits are expressed in concurrent operations per minute, and are adaptive based on the current CPU load. You can apply Git rate limits per repository network or per user ID. Git rate limits are expressed in concurrent operations per minute, and are adaptive based on the current CPU load.
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
2. Under "Rate Limiting", select **Enable Git Rate Limiting**. 2. Under "Rate Limiting", select **Enable Git Rate Limiting**.
![Checkbox for enabling Git rate limiting](/assets/images/enterprise/management-console/git-rate-limits-checkbox.png) ![Checkbox for enabling Git rate limiting](/assets/images/enterprise/management-console/git-rate-limits-checkbox.png)
3. Type limits for each repository network or user ID. 3. Type limits for each repository network or user ID.
![Fields for repository network and user ID limits](/assets/images/enterprise/management-console/example-git-rate-limits.png) ![Fields for repository network and user ID limits](/assets/images/enterprise/management-console/example-git-rate-limits.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}

6
content/admin/configuration/configuring-the-ip-address-using-the-virtual-machine-console.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring the IP address using the virtual machine console title: Configuring the IP address using the virtual machine console
intro: 'By default, {{ site.data.variables.product.prodname_ghe_server }} retrieves network settings via the dynamic host configuration protocol (DHCP). If your platform supports it, or if DHCP is unavailable, you can also configure the network settings using the virtual machine console.' intro: 'By default, {% data variables.product.prodname_ghe_server %} retrieves network settings via the dynamic host configuration protocol (DHCP). If your platform supports it, or if DHCP is unavailable, you can also configure the network settings using the virtual machine console.'
redirect_from: redirect_from:
- /enterprise/admin/installation/configuring-the-ip-address-using-the-virtual-machine-console - /enterprise/admin/installation/configuring-the-ip-address-using-the-virtual-machine-console
- /enterprise/admin/configuration/configuring-the-ip-address-using-the-virtual-machine-console - /enterprise/admin/configuration/configuring-the-ip-address-using-the-virtual-machine-console
@@ -8,9 +8,9 @@ versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
{{ site.data.reusables.enterprise_installation.open-vm-console-start }} {% data reusables.enterprise_installation.open-vm-console-start %}
3. Choose to configure the `IPv4` or `IPv6` protocol. 3. Choose to configure the `IPv4` or `IPv6` protocol.
![Options to choose the IPv4 or the IPv6 protocol](/assets/images/enterprise/network-configuration/IPv4-or-IPv6-protocol.png) ![Options to choose the IPv4 or the IPv6 protocol](/assets/images/enterprise/network-configuration/IPv4-or-IPv6-protocol.png)
4. Configure options for the protocol you chose. 4. Configure options for the protocol you chose.
![Menu with IP protocol options](/assets/images/enterprise/network-configuration/network-settings-selection.png) ![Menu with IP protocol options](/assets/images/enterprise/network-configuration/network-settings-selection.png)
{{ site.data.reusables.enterprise_installation.vm-console-done }} {% data reusables.enterprise_installation.vm-console-done %}

12
content/admin/configuration/configuring-time-synchronization.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring time synchronization title: Configuring time synchronization
intro: '{{ site.data.variables.product.prodname_ghe_server }} automatically synchronizes its clock by connecting to NTP servers. You can set the NTP servers that are used to synchronize the clock, or you can use the default NTP servers.' intro: '{% data variables.product.prodname_ghe_server %} automatically synchronizes its clock by connecting to NTP servers. You can set the NTP servers that are used to synchronize the clock, or you can use the default NTP servers.'
redirect_from: redirect_from:
- /enterprise/admin/articles/adjusting-the-clock/ - /enterprise/admin/articles/adjusting-the-clock/
- /enterprise/admin/articles/configuring-time-zone-and-ntp-settings/ - /enterprise/admin/articles/configuring-time-zone-and-ntp-settings/
@@ -14,14 +14,14 @@ versions:
### Changing the default NTP servers ### Changing the default NTP servers
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
2. In the left sidebar, click **Time**. 2. In the left sidebar, click **Time**.
![The Time button in the {{ site.data.variables.enterprise.management_console }} sidebar](/assets/images/enterprise/management-console/sidebar-time.png) ![The Time button in the {% data variables.enterprise.management_console %} sidebar](/assets/images/enterprise/management-console/sidebar-time.png)
3. Under "Primary NTP server," type the hostname of the primary NTP server. Under "Secondary NTP server," type the hostname of the secondary NTP server. 3. Under "Primary NTP server," type the hostname of the primary NTP server. Under "Secondary NTP server," type the hostname of the secondary NTP server.
![The fields for primary and secondary NTP servers in the {{ site.data.variables.enterprise.management_console }}](/assets/images/enterprise/management-console/ntp-servers.png) ![The fields for primary and secondary NTP servers in the {% data variables.enterprise.management_console %}](/assets/images/enterprise/management-console/ntp-servers.png)
4. At the bottom of the page, click **Save settings**. 4. At the bottom of the page, click **Save settings**.
![The Save settings button in the {{ site.data.variables.enterprise.management_console }}](/assets/images/enterprise/management-console/save-settings.png) ![The Save settings button in the {% data variables.enterprise.management_console %}](/assets/images/enterprise/management-console/save-settings.png)
5. Wait for the configuration run to complete. 5. Wait for the configuration run to complete.
### Correcting a large time drift ### Correcting a large time drift

38
content/admin/configuration/configuring-tls.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring TLS title: Configuring TLS
intro: 'You can configure Transport Layer Security (TLS) on {{ site.data.variables.product.product_location_enterprise }} so that you can use a certificate that is signed by a trusted certificate authority.' intro: 'You can configure Transport Layer Security (TLS) on {% data variables.product.product_location_enterprise %} so that you can use a certificate that is signed by a trusted certificate authority.'
redirect_from: redirect_from:
- /enterprise/admin/articles/ssl-configuration/ - /enterprise/admin/articles/ssl-configuration/
- /enterprise/admin/guides/installation/about-tls/ - /enterprise/admin/guides/installation/about-tls/
@@ -12,11 +12,11 @@ versions:
### About Transport Layer Security ### About Transport Layer Security
TLS, which replaced SSL, is enabled and configured with a self-signed certificate when {{ site.data.variables.product.prodname_ghe_server }} is started for the first time. As self-signed certificates are not trusted by web browsers and Git clients, these clients will report certificate warnings until you disable TLS or upload a certificate signed by a trusted authority, such as Let's Encrypt. TLS, which replaced SSL, is enabled and configured with a self-signed certificate when {% data variables.product.prodname_ghe_server %} is started for the first time. As self-signed certificates are not trusted by web browsers and Git clients, these clients will report certificate warnings until you disable TLS or upload a certificate signed by a trusted authority, such as Let's Encrypt.
The {{ site.data.variables.product.prodname_ghe_server }} appliance will send HTTP Strict Transport Security headers when SSL is enabled. Disabling TLS will cause users to lose access to the appliance, because their browsers will not allow a protocol downgrade to HTTP. For more information, see "[HTTP Strict Transport Security (HSTS)](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security)" on Wikipedia. The {% data variables.product.prodname_ghe_server %} appliance will send HTTP Strict Transport Security headers when SSL is enabled. Disabling TLS will cause users to lose access to the appliance, because their browsers will not allow a protocol downgrade to HTTP. For more information, see "[HTTP Strict Transport Security (HSTS)](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security)" on Wikipedia.
{{ site.data.reusables.enterprise_installation.terminating-tls }} {% data reusables.enterprise_installation.terminating-tls %}
To allow users to use FIDO U2F for two-factor authentication, you must enable TLS for your instance. For more information, see "[Configuring two-factor authentication](/articles/configuring-two-factor-authentication)." To allow users to use FIDO U2F for two-factor authentication, you must enable TLS for your instance. For more information, see "[Configuring two-factor authentication](/articles/configuring-two-factor-authentication)."
@@ -30,10 +30,10 @@ You can generate a certificate signing request (CSR) for your instance using the
### Uploading a custom TLS certificate ### Uploading a custom TLS certificate
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.privacy }} {% data reusables.enterprise_management_console.privacy %}
{{ site.data.reusables.enterprise_management_console.select-tls-only }} {% data reusables.enterprise_management_console.select-tls-only %}
4. Under "TLS Protocol support", select the protocols you want to allow. 4. Under "TLS Protocol support", select the protocols you want to allow.
![Radio buttons with options to choose TLS protocols](/assets/images/enterprise/management-console/tls-protocol-support.png) ![Radio buttons with options to choose TLS protocols](/assets/images/enterprise/management-console/tls-protocol-support.png)
5. Under "Certificate", click **Choose File** to choose a TLS certificate or certificate chain (in PEM format) to install. This file will usually have a *.pem*, *.crt*, or *.cer* extension. 5. Under "Certificate", click **Choose File** to choose a TLS certificate or certificate chain (in PEM format) to install. This file will usually have a *.pem*, *.crt*, or *.cer* extension.
@@ -46,30 +46,30 @@ You can generate a certificate signing request (CSR) for your instance using the
**Warning**: Your TLS key must not have a passphrase. For more information, see "[Removing the passphrase from your key file](/enterprise/{{ currentVersion }}/admin/guides/installation/troubleshooting-ssl-errors#removing-the-passphrase-from-your-key-file)". **Warning**: Your TLS key must not have a passphrase. For more information, see "[Removing the passphrase from your key file](/enterprise/{{ currentVersion }}/admin/guides/installation/troubleshooting-ssl-errors#removing-the-passphrase-from-your-key-file)".
{% endwarning %} {% endwarning %}
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
### About Let's Encrypt support ### About Let's Encrypt support
Let's Encrypt is a public certificate authority that issues free, automated TLS certificates that are trusted by browsers using the ACME protocol. You can automatically obtain and renew Let's Encrypt certificates on your appliance without any required manual maintenance. Let's Encrypt is a public certificate authority that issues free, automated TLS certificates that are trusted by browsers using the ACME protocol. You can automatically obtain and renew Let's Encrypt certificates on your appliance without any required manual maintenance.
{{ site.data.reusables.enterprise_installation.lets-encrypt-prerequisites }} {% data reusables.enterprise_installation.lets-encrypt-prerequisites %}
When you enable automation of TLS certificate management using Let's Encrypt, {{ site.data.variables.product.product_location_enterprise }} will contact the Let's Encrypt servers to obtain a certificate. To renew a certificate, Let's Encrypt servers must validate control of the configured domain name with inbound HTTP requests. When you enable automation of TLS certificate management using Let's Encrypt, {% data variables.product.product_location_enterprise %} will contact the Let's Encrypt servers to obtain a certificate. To renew a certificate, Let's Encrypt servers must validate control of the configured domain name with inbound HTTP requests.
You can also use the `ghe-ssl-acme` command line utility on {{ site.data.variables.product.product_location_enterprise }} to automatically generate a Let's Encrypt certificate. For more information, see "[Command-line utilities](/enterprise/{{ currentVersion }}/admin/guides/installation/command-line-utilities#ghe-ssl-acme)." You can also use the `ghe-ssl-acme` command line utility on {% data variables.product.product_location_enterprise %} to automatically generate a Let's Encrypt certificate. For more information, see "[Command-line utilities](/enterprise/{{ currentVersion }}/admin/guides/installation/command-line-utilities#ghe-ssl-acme)."
### Configuring TLS using Let's Encrypt ### Configuring TLS using Let's Encrypt
{{ site.data.reusables.enterprise_installation.lets-encrypt-prerequisites }} {% data reusables.enterprise_installation.lets-encrypt-prerequisites %}
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.management-console }} {% data reusables.enterprise_site_admin_settings.management-console %}
{{ site.data.reusables.enterprise_management_console.privacy }} {% data reusables.enterprise_management_console.privacy %}
{{ site.data.reusables.enterprise_management_console.select-tls-only }} {% data reusables.enterprise_management_console.select-tls-only %}
5. Select **Enable automation of TLS certificate management using Let's Encrypt**. 5. Select **Enable automation of TLS certificate management using Let's Encrypt**.
![Checkbox to enable Let's Encrypt](/assets/images/enterprise/management-console/lets-encrypt-checkbox.png) ![Checkbox to enable Let's Encrypt](/assets/images/enterprise/management-console/lets-encrypt-checkbox.png)
{{ site.data.reusables.enterprise_management_console.save-settings }} {% data reusables.enterprise_management_console.save-settings %}
{{ site.data.reusables.enterprise_management_console.privacy }} {% data reusables.enterprise_management_console.privacy %}
7. Click **Request TLS certificate**. 7. Click **Request TLS certificate**.
![Request TLS certificate button](/assets/images/enterprise/management-console/request-tls-button.png) ![Request TLS certificate button](/assets/images/enterprise/management-console/request-tls-button.png)
8. Click **Save configuration**. 8. Click **Save configuration**.

2
content/admin/configuration/configuring-your-enterprise.md
View File

@@ -1,6 +1,6 @@
--- ---
title: Configuring your enterprise title: Configuring your enterprise
intro: 'Once {{ site.data.variables.product.prodname_ghe_server }} is up and running, you can configure the appliance to suit your organization''s needs.' intro: 'Once {% data variables.product.prodname_ghe_server %} is up and running, you can configure the appliance to suit your organization''s needs.'
redirect_from: redirect_from:
- /enterprise/admin/guides/installation/basic-configuration/ - /enterprise/admin/guides/installation/basic-configuration/
- /enterprise/admin/guides/installation/administrative-tools/ - /enterprise/admin/guides/installation/administrative-tools/

62
content/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud.md
View File

@@ -1,67 +1,67 @@
--- ---
title: Connecting GitHub Enterprise Server to GitHub Enterprise Cloud title: Connecting GitHub Enterprise Server to GitHub Enterprise Cloud
intro: 'After you enable {{ site.data.variables.product.prodname_github_connect }}, you can share specific features and workflows between {{ site.data.variables.product.product_location_enterprise }} and {{ site.data.variables.product.prodname_ghe_cloud }}.' intro: 'After you enable {% data variables.product.prodname_github_connect %}, you can share specific features and workflows between {% data variables.product.product_location_enterprise %} and {% data variables.product.prodname_ghe_cloud %}.'
redirect_from: redirect_from:
- /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-to-github-com/ - /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-to-github-com/
- /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-server-to-github-com - /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-server-to-github-com
- /enterprise/admin/developer-workflow/connecting-github-enterprise-server-to-githubcom/ - /enterprise/admin/developer-workflow/connecting-github-enterprise-server-to-githubcom/
- /enterprise/admin/installation/connecting-github-enterprise-server-to-github-enterprise-cloud - /enterprise/admin/installation/connecting-github-enterprise-server-to-github-enterprise-cloud
- /enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud - /enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud
permissions: 'Site administrators for {{ site.data.variables.product.prodname_ghe_server }} who are also owners of a {{ site.data.variables.product.prodname_ghe_cloud }} organization or enterprise account can enable {{ site.data.variables.product.prodname_github_connect }}.' permissions: 'Site administrators for {% data variables.product.prodname_ghe_server %} who are also owners of a {% data variables.product.prodname_ghe_cloud %} organization or enterprise account can enable {% data variables.product.prodname_github_connect %}.'
versions: versions:
enterprise-server: '*' enterprise-server: '*'
--- ---
### About {{ site.data.variables.product.prodname_github_connect }} ### About {% data variables.product.prodname_github_connect %}
To enable {{ site.data.variables.product.prodname_github_connect }}, you must configure the connection in both {{ site.data.variables.product.product_location_enterprise }} and in your {{ site.data.variables.product.prodname_ghe_cloud }} organization or enterprise account. To enable {% data variables.product.prodname_github_connect %}, you must configure the connection in both {% data variables.product.product_location_enterprise %} and in your {% data variables.product.prodname_ghe_cloud %} organization or enterprise account.
To configure a connection, your proxy configuration must allow connectivity to `github.com` and `api.github.com`. For more information, see "[Configuring an outbound web proxy server](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-an-outbound-web-proxy-server)." To configure a connection, your proxy configuration must allow connectivity to `github.com` and `api.github.com`. For more information, see "[Configuring an outbound web proxy server](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-an-outbound-web-proxy-server)."
After enabling {{ site.data.variables.product.prodname_github_connect }}, you will be able to enable features such as unified search and unified contributions. For more information about all of the features available, see "[Managing connections between {{ site.data.variables.product.prodname_ghe_server }} and {{ site.data.variables.product.prodname_ghe_cloud }}](/enterprise/{{ currentVersion }}/admin/installation/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud)." After enabling {% data variables.product.prodname_github_connect %}, you will be able to enable features such as unified search and unified contributions. For more information about all of the features available, see "[Managing connections between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}](/enterprise/{{ currentVersion }}/admin/installation/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud)."
When you connect {{ site.data.variables.product.product_location_enterprise }} to {{ site.data.variables.product.prodname_ghe_cloud }}, a record on {{ site.data.variables.product.prodname_dotcom_the_website }} stores information about the connection: When you connect {% data variables.product.product_location_enterprise %} to {% data variables.product.prodname_ghe_cloud %}, a record on {% data variables.product.prodname_dotcom_the_website %} stores information about the connection:
- The public key portion of your {{ site.data.variables.product.prodname_ghe_server }} license - The public key portion of your {% data variables.product.prodname_ghe_server %} license
- A hash of your {{ site.data.variables.product.prodname_ghe_server }} license - A hash of your {% data variables.product.prodname_ghe_server %} license
- The customer name on your {{ site.data.variables.product.prodname_ghe_server }} license - The customer name on your {% data variables.product.prodname_ghe_server %} license
- The hostname of {{ site.data.variables.product.product_location_enterprise }} - The hostname of {% data variables.product.product_location_enterprise %}
- The version of {{ site.data.variables.product.product_location_enterprise }} - The version of {% data variables.product.product_location_enterprise %}
- The organization or enterprise account on {{ site.data.variables.product.prodname_dotcom_the_website }} that's connected to {{ site.data.variables.product.product_location_enterprise }} - The organization or enterprise account on {% data variables.product.prodname_dotcom_the_website %} that's connected to {% data variables.product.product_location_enterprise %}
- The authentication token that's used by {{ site.data.variables.product.product_location_enterprise }} to make requests to {{ site.data.variables.product.prodname_dotcom_the_website }} - The authentication token that's used by {% data variables.product.product_location_enterprise %} to make requests to {% data variables.product.prodname_dotcom_the_website %}
Enabling {{ site.data.variables.product.prodname_github_connect }} also creates a {{ site.data.variables.product.prodname_github_app }} owned by your {{ site.data.variables.product.prodname_ghe_cloud }} organization or enterprise account. {{ site.data.variables.product.prodname_ghe_server }} uses the {{ site.data.variables.product.prodname_github_app }}'s credentials to make requests to {{ site.data.variables.product.prodname_dotcom_the_website }}. Enabling {% data variables.product.prodname_github_connect %} also creates a {% data variables.product.prodname_github_app %} owned by your {% data variables.product.prodname_ghe_cloud %} organization or enterprise account. {% data variables.product.prodname_ghe_server %} uses the {% data variables.product.prodname_github_app %}'s credentials to make requests to {% data variables.product.prodname_dotcom_the_website %}.
{{ site.data.variables.product.prodname_ghe_server }} stores credentials from the {{ site.data.variables.product.prodname_github_app }}. These credentials will be replicated to any high availability or clustering environments, and stored in any backups, including snapshots created by {{ site.data.variables.product.prodname_enterprise_backup_utilities }}. {% data variables.product.prodname_ghe_server %} stores credentials from the {% data variables.product.prodname_github_app %}. These credentials will be replicated to any high availability or clustering environments, and stored in any backups, including snapshots created by {% data variables.product.prodname_enterprise_backup_utilities %}.
- An authentication token, which is valid for one hour - An authentication token, which is valid for one hour
- A private key, which is used to generate a new authentication token - A private key, which is used to generate a new authentication token
Enabling {{ site.data.variables.product.prodname_github_connect }} will not allow {{ site.data.variables.product.prodname_dotcom_the_website }} users to make changes to {{ site.data.variables.product.prodname_ghe_server }}. Enabling {% data variables.product.prodname_github_connect %} will not allow {% data variables.product.prodname_dotcom_the_website %} users to make changes to {% data variables.product.prodname_ghe_server %}.
{% if currentVersion ver_gt "enterprise-server@2.18" %} {% if currentVersion ver_gt "enterprise-server@2.18" %}
For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)." For more information about managing enterprise accounts using the GraphQL API, see "[Enterprise accounts](/v4/guides/managing-enterprise-accounts)."
{% endif %} {% endif %}
### Enabling {{ site.data.variables.product.prodname_github_connect }} ### Enabling {% data variables.product.prodname_github_connect %}
1. Sign in to {{ site.data.variables.product.product_location_enterprise }} and {{ site.data.variables.product.prodname_dotcom_the_website }}. 1. Sign in to {% data variables.product.product_location_enterprise %} and {% data variables.product.prodname_dotcom_the_website %}.
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.business }} {% data reusables.enterprise_site_admin_settings.business %}
{{ site.data.reusables.enterprise-accounts.settings-tab }} {% data reusables.enterprise-accounts.settings-tab %}
{{ site.data.reusables.enterprise-accounts.github-connect-tab }} {% data reusables.enterprise-accounts.github-connect-tab %}
5. Under "{{ site.data.variables.product.prodname_dotcom_the_website }} is not enabled yet", click **Enable {{ site.data.variables.product.prodname_github_connect }}**. By clicking **Enable {{ site.data.variables.product.prodname_github_connect }}**, you agree to the <a href="/articles/github-connect-addendum-to-the-github-enterprise-license-agreement/" class="dotcom-only">{{ site.data.variables.product.prodname_github_connect }} Addendum to the {{ site.data.variables.product.prodname_enterprise }} License Agreement</a>. 5. Under "{% data variables.product.prodname_dotcom_the_website %} is not enabled yet", click **Enable {% data variables.product.prodname_github_connect %}**. By clicking **Enable {% data variables.product.prodname_github_connect %}**, you agree to the <a href="/articles/github-connect-addendum-to-the-github-enterprise-license-agreement/" class="dotcom-only">{% data variables.product.prodname_github_connect %} Addendum to the {% data variables.product.prodname_enterprise %} License Agreement</a>.
![Enable GitHub Connect button](/assets/images/enterprise/business-accounts/enable-github-connect-button.png) ![Enable GitHub Connect button](/assets/images/enterprise/business-accounts/enable-github-connect-button.png)
6. Next to the enterprise account or organization you'd like to connect, click **Connect**. 6. Next to the enterprise account or organization you'd like to connect, click **Connect**.
![Connect button next to an enterprise account or business](/assets/images/enterprise/business-accounts/choose-enterprise-or-org-connect.png) ![Connect button next to an enterprise account or business](/assets/images/enterprise/business-accounts/choose-enterprise-or-org-connect.png)
### Disconnecting a {{ site.data.variables.product.prodname_ghe_cloud }} organization or enterprise account from {{ site.data.variables.product.product_location_enterprise }} ### Disconnecting a {% data variables.product.prodname_ghe_cloud %} organization or enterprise account from {% data variables.product.product_location_enterprise %}
When you disconnect from {{ site.data.variables.product.prodname_ghe_cloud }}, the {{ site.data.variables.product.prodname_github_connect }} {{ site.data.variables.product.prodname_github_app }} is deleted from your enterprise account or organization and credentials stored on {{ site.data.variables.product.product_location_enterprise }} are deleted. When you disconnect from {% data variables.product.prodname_ghe_cloud %}, the {% data variables.product.prodname_github_connect %} {% data variables.product.prodname_github_app %} is deleted from your enterprise account or organization and credentials stored on {% data variables.product.product_location_enterprise %} are deleted.
{{ site.data.reusables.enterprise_site_admin_settings.access-settings }} {% data reusables.enterprise_site_admin_settings.access-settings %}
{{ site.data.reusables.enterprise_site_admin_settings.business }} {% data reusables.enterprise_site_admin_settings.business %}
{{ site.data.reusables.enterprise-accounts.settings-tab }} {% data reusables.enterprise-accounts.settings-tab %}
{{ site.data.reusables.enterprise-accounts.github-connect-tab }} {% data reusables.enterprise-accounts.github-connect-tab %}
5. Next to the enterprise account or organization you'd like to disconnect, click **Disable {{ site.data.variables.product.prodname_github_connect }}**. 5. Next to the enterprise account or organization you'd like to disconnect, click **Disable {% data variables.product.prodname_github_connect %}**.
![Disable GitHub Connect button next to an enterprise account or organization name](/assets/images/enterprise/business-accounts/disable-github-connect-button.png) ![Disable GitHub Connect button next to an enterprise account or organization name](/assets/images/enterprise/business-accounts/disable-github-connect-button.png)
6. Read the information about disconnecting and click **Disable {{ site.data.variables.product.prodname_github_connect }}**. 6. Read the information about disconnecting and click **Disable {% data variables.product.prodname_github_connect %}**.
![Modal with warning information about disconnecting and confirmation button](/assets/images/enterprise/business-accounts/confirm-disable-github-connect.png) ![Modal with warning information about disconnecting and confirmation button](/assets/images/enterprise/business-accounts/confirm-disable-github-connect.png)

Some files were not shown because too many files have changed in this diff Show More