Skip to content

repo sync #24550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 20, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions content/actions/creating-actions/about-custom-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,11 +35,11 @@ Actions can run directly on a machine or in a Docker container. You can define a

You can build Docker container, JavaScript, and composite 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 "[AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions)."

| Type | Operating system |
| ---- | ------------------- |
| Docker container | Linux |
| JavaScript | Linux, macOS, Windows |
| Composite Actions | Linux, macOS, Windows |
| Type | Linux | macOS | Windows |
| ---- | ----- | ----- | -------- |
| Docker container | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} |
| JavaScript | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |
| Composite Actions | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} |

### Docker container actions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,27 +94,27 @@ The following example OIDC token uses a subject (`sub`) that references a job en
To see all the claims supported by {% data variables.product.prodname_dotcom %}'s OIDC provider, review the `claims_supported` entries at
{% ifversion ghes %}`https://HOSTNAME/_services/token/.well-known/openid-configuration`{% else %}https://token.actions.githubusercontent.com/.well-known/openid-configuration{% endif %}.

The token includes the standard audience, issuer, and subject claims:
The token includes the standard audience, issuer, and subject claims.

| Claim | Description |
| ----------- | ---------------------- |
| `aud`| _(Audience)_ By default, this is the URL of the repository owner, such as the organization that owns the repository. This is the only claim that can be customized. You can set a custom audience with a toolkit command: [`core.getIDToken(audience)`](https://www.npmjs.com/package/@actions/core/v/1.6.0) |
| `iss`| _(Issuer)_ The issuer of the OIDC token: {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %} |
| `sub`| _(Subject)_ Defines the subject claim that is to be validated by the cloud provider. This setting is essential for making sure that access tokens are only allocated in a predictable way.|
| Claim | Claim type | Description |
| ----------- | -----| ---------------------- |
| `aud`| Audience | By default, this is the URL of the repository owner, such as the organization that owns the repository. This is the only claim that can be customized. You can set a custom audience with a toolkit command: [`core.getIDToken(audience)`](https://www.npmjs.com/package/@actions/core/v/1.6.0) |
| `iss`| Issuer | The issuer of the OIDC token: {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %} |
| `sub`| Subject | Defines the subject claim that is to be validated by the cloud provider. This setting is essential for making sure that access tokens are only allocated in a predictable way. |

The OIDC token also includes additional standard claims:
The OIDC token also includes additional standard claims.

| Claim | Description |
| ----------- | ---------------------- |
| `alg`| _(Algorithm)_ The algorithm used by the OIDC provider. |
| `exp`| _(Expires at)_ Identifies the expiry time of the JWT. |
| `iat`| _(Issued at)_ The time when the JWT was issued. |
| `jti`| _(JWT token identifier)_ Unique identifier for the OIDC token. |
| `kid`| _(Key identifier)_ Unique key for the OIDC token. |
| `nbf`| _(Not before)_ JWT is not valid for use before this time. |
| `typ`| _(Type)_ Describes the type of token. This is a JSON Web Token (JWT). |
| Claim | Claim type | Description |
| ----------- | -----| ---------------------- |
| `alg`| Algorithm | The algorithm used by the OIDC provider. |
| `exp`| Expires at | Identifies the expiry time of the JWT. |
| `iat`| Issued at | The time when the JWT was issued. |
| `jti`| JWT token identifier | Unique identifier for the OIDC token. |
| `kid`| Key identifier | Unique key for the OIDC token. |
| `nbf`| Not before | JWT is not valid for use before this time. |
| `typ`| Type | Describes the type of token. This is a JSON Web Token (JWT). |

The token also includes custom claims provided by {% data variables.product.prodname_dotcom %}:
The token also includes custom claims provided by {% data variables.product.prodname_dotcom %}.

| Claim | Description |
| ----------- | ---------------------- |
Expand Down Expand Up @@ -172,67 +172,59 @@ The subject claim includes the environment name when the job references an envir

You can configure a subject that filters for a specific [environment](/actions/deployment/targeting-different-environments/using-environments-for-deployment) name. In this example, the workflow run must have originated from a job that has an environment named `Production`, in a repository named `octo-repo` that is owned by the `octo-org` organization:

| | |
| ------ | ----------- |
| Syntax: | `repo:<orgName/repoName>:environment:<environmentName>` |
| Example:| `repo:octo-org/octo-repo:environment:Production` |
- Syntax: `repo:<orgName/repoName>:environment:<environmentName>`
- Example:`repo:octo-org/octo-repo:environment:Production`

#### Filtering for `pull_request` events

The subject claim includes the `pull_request` string when the workflow is triggered by a pull request event, but only if the job doesn't reference an environment.

You can configure a subject that filters for the [`pull_request`](/actions/using-workflows/events-that-trigger-workflows#pull_request) event. In this example, the workflow run must have been triggered by a `pull_request` event in a repository named `octo-repo` that is owned by the `octo-org` organization:

| | |
| ------ | ----------- |
| Syntax: | `repo:<orgName/repoName>:pull_request` |
| Example:| `repo:octo-org/octo-repo:pull_request` |
- Syntax: `repo:<orgName/repoName>:pull_request`
- Example: `repo:octo-org/octo-repo:pull_request`

#### Filtering for a specific branch

The subject claim includes the branch name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event.

You can configure a subject that filters for a specific branch name. In this example, the workflow run must have originated from a branch named `demo-branch`, in a repository named `octo-repo` that is owned by the `octo-org` organization:

| | |
| ------ | ----------- |
| Syntax: | `repo:<orgName/repoName>:ref:refs/heads/branchName` |
| Example:| `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` |
- Syntax: `repo:<orgName/repoName>:ref:refs/heads/branchName`
- Example: repo:octo-org/octo-repo:ref:refs/heads/demo-branch`

#### Filtering for a specific tag

The subject claim includes the tag name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event.

You can create a subject that filters for specific tag. In this example, the workflow run must have originated with a tag named `demo-tag`, in a repository named `octo-repo` that is owned by the `octo-org` organization:

| | |
| ------ | ----------- |
| Syntax: | `repo:<orgName/repoName>:ref:refs/tags/<tagName>` |
| Example:| `repo:octo-org/octo-repo:ref:refs/tags/demo-tag` |
- Syntax: `repo:<orgName/repoName>:ref:refs/tags/<tagName>`
- Example: `repo:octo-org/octo-repo:ref:refs/tags/demo-tag`

### Configuring the subject in your cloud provider

To configure the subject in your cloud provider's trust relationship, you must add the subject string to its trust configuration. The following examples demonstrate how various cloud providers can accept the same `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` subject in different ways:

| | |
| Cloud provider | Example |
| ------ | ----------- |
| Amazon Web Services | `"{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` |
| Azure| `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` |
| Google Cloud Platform| `(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')` |
| HashiCorp Vault| `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch" ` |
| Amazon Web Services | `"{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` |
| Azure| `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` |
| Google Cloud Platform| `(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')` |
| HashiCorp Vault| `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` |

For more information, see the guides listed in "[Enabling OpenID Connect for your cloud provider](#enabling-openid-connect-for-your-cloud-provider)."

## Updating your actions for OIDC

To update your custom actions to authenticate using OIDC, you can use `getIDToken()` from the Actions toolkit to request a JWT from {% data variables.product.prodname_dotcom %}'s OIDC provider. For more information, see "OIDC Token" in the [npm package documentation](https://www.npmjs.com/package/@actions/core/v/1.6.0).

You could also use a `curl` command to request the JWT, using the following environment variables:
You could also use a `curl` command to request the JWT, using the following environment variables.

| | |
| Variable | Description |
| ------ | ----------- |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | The URL for {% data variables.product.prodname_dotcom %}'s OIDC provider. |
| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Bearer token for the request to the OIDC provider. |
| `ACTIONS_ID_TOKEN_REQUEST_URL` | The URL for {% data variables.product.prodname_dotcom %}'s OIDC provider. |
| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Bearer token for the request to the OIDC provider. |


For example:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,15 @@ topics:
{% data reusables.actions.cron-table-entry %}
{% data reusables.actions.permissions-table-entry %}
{% data reusables.actions.concurrency-table-entry %}
| Running the job on different runners, depending on the repository: | [`runs-on`](/actions/using-jobs/choosing-the-runner-for-a-job)|
| Running the job on different runners, depending on the repository | [`runs-on`](/actions/using-jobs/choosing-the-runner-for-a-job)|
{% data reusables.actions.if-conditions-table-entry %}
| Using a matrix to create different test configurations: | [`matrix`](/actions/using-jobs/using-a-matrix-for-your-jobs)|
| Using a matrix to create different test configurations | [`matrix`](/actions/using-jobs/using-a-matrix-for-your-jobs)|
{% data reusables.actions.checkout-action-table-entry %}
{% data reusables.actions.setup-node-table-entry %}
{%- ifversion actions-caching %}
| Caching dependencies: | [`actions/cache`](/actions/advanced-guides/caching-dependencies-to-speed-up-workflows)|
| Caching dependencies | [`actions/cache`](/actions/advanced-guides/caching-dependencies-to-speed-up-workflows)|
{%- endif %}
| Running tests on the runner: | `npm test`|
| Running tests on the runner | `npm test`|

## Example workflow

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,17 +27,17 @@ topics:
{% data reusables.actions.example-table-intro %}

| **Feature** | **Implementation** |
| --- | --- |
| --- | --- |
{% data reusables.actions.push-table-entry %}
{% data reusables.actions.pull-request-table-entry %}
{% data reusables.actions.workflow-dispatch-table-entry %}
{% data reusables.actions.permissions-table-entry %}
{% data reusables.actions.concurrency-table-entry %}
| Running the job on different runners, depending on the repository: | [`runs-on`](/actions/using-jobs/choosing-the-runner-for-a-job)|
| Running the job on different runners, depending on the repository | [`runs-on`](/actions/using-jobs/choosing-the-runner-for-a-job)|
{% data reusables.actions.checkout-action-table-entry %}
{% data reusables.actions.setup-node-table-entry %}
| Using a third-party action: | [`trilom/file-changes-action`](https://github.com/trilom/file-changes-action)|
| Running a script on the runner: | Using `./script/rendered-content-link-checker.mjs` |
| Using a third-party action | [`trilom/file-changes-action`](https://github.com/trilom/file-changes-action)|
| Running a script on the runner | Using `./script/rendered-content-link-checker.mjs` |

## Example workflow

Expand Down
12 changes: 6 additions & 6 deletions content/actions/examples/using-the-github-cli-on-a-runner.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,12 @@ topics:
{% data reusables.actions.secrets-table-entry %}
{% data reusables.actions.checkout-action-table-entry %}
{% data reusables.actions.setup-node-table-entry %}
| Using a third-party action: | [`peter-evans/create-issue-from-file`](https://github.com/peter-evans/create-issue-from-file)|
| Running shell commands on the runner: | [`run`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun) |
| Running a script on the runner: | Using `script/check-english-links.js` |
| Generating an output file: | Piping the output using the `>` operator |
| Checking for existing issues using {% data variables.product.prodname_cli %}: | [`gh issue list`](https://cli.github.com/manual/gh_issue_list) |
| Commenting on an issue using {% data variables.product.prodname_cli %}: | [`gh issue comment`](https://cli.github.com/manual/gh_issue_comment) |
| Using a third-party action | [`peter-evans/create-issue-from-file`](https://github.com/peter-evans/create-issue-from-file)|
| Running shell commands on the runner | [`run`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun) |
| Running a script on the runner | Using `script/check-english-links.js` |
| Generating an output file | Piping the output using the `>` operator |
| Checking for existing issues using {% data variables.product.prodname_cli %} | [`gh issue list`](https://cli.github.com/manual/gh_issue_list) |
| Commenting on an issue using {% data variables.product.prodname_cli %} | [`gh issue comment`](https://cli.github.com/manual/gh_issue_comment) |

## Example workflow

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,18 @@ type: overview

## About autoscaling

You can automatically increase or decrease the number of self-hosted runners in your environment in response to the webhook events you receive with a particular label. For example, you can create automation that adds a new self-hosted runner each time you receive a [`workflow_job`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) webhook event with the [`queued`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) activity, which notifies you that a new job is ready for processing. The webhook payload includes label data, so you can identify the type of runner the job is requesting. Once the job has finished, you can then create automation that removes the runner in response to the `workflow_job` [`completed`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) activity.
You can automatically increase or decrease the number of self-hosted runners in your environment in response to the webhook events you receive with a particular label. For example, you can create automation that adds a new self-hosted runner each time you receive a [`workflow_job`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) webhook event with the [`queued`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) activity, which notifies you that a new job is ready for processing. The webhook payload includes label data, so you can identify the type of runner the job is requesting. Once the job has finished, you can then create automation that removes the runner in response to the `workflow_job` [`completed`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) activity.

## Recommended autoscaling solutions

{% data variables.product.prodname_dotcom %} recommends and partners closely with two open source projects that you can use for autoscaling your runners. One or both solutions may be suitable, based on your needs.
{% data variables.product.prodname_dotcom %} recommends and partners closely with two open source projects that you can use for autoscaling your runners. One or both solutions may be suitable, based on your needs.

The following repositories have detailed instructions for setting up these autoscalers:
The following repositories have detailed instructions for setting up these autoscalers:

- [actions/actions-runner-controller](https://github.com/actions/actions-runner-controller) - A Kubernetes controller for {% data variables.product.prodname_actions %} self-hosted runners.
- [philips-labs/terraform-aws-github-runner](https://github.com/philips-labs/terraform-aws-github-runner) - A Terraform module for scalable {% data variables.product.prodname_actions %} runners on Amazon Web Services.

Each solution has certain specifics that may be important to consider:
Each solution has certain specifics that may be important to consider.

| **Features** | **actions-runner-controller** | **terraform-aws-github-runner** |
| :--- | :--- | :--- |
Expand All @@ -39,7 +39,7 @@ Each solution has certain specifics that may be important to consider:

{% data variables.product.prodname_dotcom %} recommends implementing autoscaling with ephemeral self-hosted runners; autoscaling with persistent self-hosted runners is not recommended. In certain cases, {% data variables.product.prodname_dotcom %} cannot guarantee that jobs are not assigned to persistent runners while they are shut down. With ephemeral runners, this can be guaranteed because {% data variables.product.prodname_dotcom %} only assigns one job to a runner.

This approach allows you to manage your runners as ephemeral systems, since you can use automation to provide a clean environment for each job. This helps limit the exposure of any sensitive resources from previous jobs, and also helps mitigate the risk of a compromised runner receiving new jobs.
This approach allows you to manage your runners as ephemeral systems, since you can use automation to provide a clean environment for each job. This helps limit the exposure of any sensitive resources from previous jobs, and also helps mitigate the risk of a compromised runner receiving new jobs.

To add an ephemeral runner to your environment, include the `--ephemeral` parameter when registering your runner using `config.sh`. For example:

Expand Down Expand Up @@ -90,7 +90,7 @@ You can create your own autoscaling environment by using payloads received from

## Authentication requirements

You can register and delete repository and organization self-hosted runners using [the API](/rest/actions#self-hosted-runners). To authenticate to the API, your autoscaling implementation can use an access token or a {% data variables.product.prodname_dotcom %} app.
You can register and delete repository and organization self-hosted runners using [the API](/rest/actions#self-hosted-runners). To authenticate to the API, your autoscaling implementation can use an access token or a {% data variables.product.prodname_dotcom %} app.

Your access token will require the following scope:

Expand Down
Loading