Enabling GitHub Actions with Amazon S3 storage

About external storage for GitHub Actions

GitHub Actions uses external blob storage to store data generated by workflow runs. Stored data includes workflow logs, caches, and user-uploaded build artifacts. For more information, see "Getting started with GitHub Actions for GitHub Enterprise Server."

There are two options for configuring GitHub Enterprise Server to connect to your external storage provider:

OpenID Connect (OIDC)
Traditional credentials-based authentication using secrets

We recommend using OIDC where possible, as you won't need create or manage sensitive and long-lived credential secrets for your storage provider, and risk them being exposed. After defining a trust with OIDC, your cloud storage provider automatically issues short-lived access tokens to your GitHub Enterprise Server instance, which automatically expire.

Prerequisites

Note: The only GitHub-supported S3 storage providers are Amazon S3 and MinIO Gateway for NAS.

There are other S3 API-compatible storage products that GitHub partners have self-validated as working with GitHub Actions on GitHub Enterprise Server. For more information, see the GHES Storage Partners repository.

For storage products validated through the GitHub Technology Partnership program, the storage provider is responsible for support and documentation for using the storage product with GitHub Actions.

Before enabling GitHub Actions, make sure you have completed the following steps:

Create your Amazon S3 bucket for storing data generated by workflow runs.
Review the hardware requirements for GitHub Actions. For more information, see "Getting started with GitHub Actions for GitHub Enterprise Server."
TLS must be configured for your GitHub Enterprise Server instance's domain. For more information, see "Configuring TLS."

Note: We strongly recommend that you configure TLS on GitHub Enterprise Server with a certificate signed by a trusted authority. Although a self-signed certificate can work, extra configuration is required for your self-hosted runners, and it is not recommended for production environments.
If you have an HTTP Proxy Server configured on your GitHub Enterprise Server instance:
You must add .localhost and 127.0.0.1 to the HTTP Proxy Exclusion list.
If your external storage location is not routable, then you must also add your external storage URL to the exclusion list.

For more information on changing your proxy settings, see "Configuring an outbound web proxy server."

If you are using OIDC for the connection to your storage provider, you must expose the following OIDC token service URLs on your GitHub Enterprise Server instance to the public internet:
```
https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks
```
This ensures that the storage provider can contact your GitHub Enterprise Server instance for authentication.

Enabling GitHub Actions with Amazon S3 using OIDC (recommended)

To configure GitHub Enterprise Server to use OIDC with an Amazon S3 bucket, you must first create an Amazon OIDC provider, then create an Identity and Access Management (IAM) role, and finally configure GitHub Enterprise Server to use the provider and role to access your S3 bucket.

1. Create an Amazon OIDC provider

Get the thumbprint for your GitHub Enterprise Server instance.

Use the following OpenSSL command to get the SHA1 thumbprint for your GitHub Enterprise Server instance, replacing HOSTNAME with the public hostname for your GitHub Enterprise Server instance

Shell

openssl s_client -connect HOSTNAME:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin

openssl s_client -connect HOSTNAME:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin

For example:

openssl s_client -connect my-ghes-host.example.com:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin

The command returns a thumbprint in the following format:

SHA1 Fingerprint=AB:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56

Remove the colons (:) from the thumbprint value, and save the value to use later.

For example, the thumbprint for the value returned in the previous step is:
```
AB1234567890ABCDEF1234567890ABCDEF123456
```

Using the AWS CLI, use the following command to create an OIDC provider for your GitHub Enterprise Server instance. Replace HOSTNAME with the public hostname for your GitHub Enterprise Server instance, and THUMBPRINT with the thumbprint value from the previous step.

Shell

aws iam create-open-id-connect-provider \
  --url https://HOSTNAME/_services/token \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "THUMBPRINT"

aws iam create-open-id-connect-provider \
  --url https://HOSTNAME/_services/token \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "THUMBPRINT"

For example:

Shell

aws iam create-open-id-connect-provider \
  --url https://my-ghes-host.example.com/_services/token \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "AB1234567890ABCDEF1234567890ABCDEF123456"

aws iam create-open-id-connect-provider \
  --url https://my-ghes-host.example.com/_services/token \
  --client-id-list "sts.amazonaws.com" \
  --thumbprint-list "AB1234567890ABCDEF1234567890ABCDEF123456"

For more information on installing the AWS CLI, see the Amazon documentation.

Warning: If the certificate for your GitHub Enterprise Server instance changes in the future, you must update the thumbprint value in the Amazon OIDC provider for the OIDC trust to continue to work.

2. Create an IAM role

Open the AWS Console, and navigate to the Identity and Access Management (IAM) service.
In the left menu, under "Access management", click Roles, then click Create Role.
On the "Select trusted entity" page, enter the following options:
- For "Trusted entity type", click Web identity.
- For "Identity provider", use the Choose provider drop-down menu and select the OIDC provider you created in the previous steps. It should be named HOSTNAME/_services/token, where HOSTNAME is the public hostname for your GitHub Enterprise Server instance.
- For "Audience", select sts.amazonaws.com.
Click Next.
On the "Add permissions" page, use the filter to find and select the AmazonS3FullAccess policy.
Click Next.
On the "Name, review, and create" page, enter a name for the role, and click Create role.
On the IAM "Roles" page, select the role you just created.
Under "Summary", note the ARN value for the role, as this is needed later.
Click the Trust relationships tab, then click Edit trust policy.

Edit the trust policy to add a new sub claim. The value for Condition must match the following example, replacing HOSTNAME with the public hostname for your GitHub Enterprise Server instance:

...
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "HOSTNAME"
  }
}
...

For example:

...
"Condition": {
  "StringEquals": {
    "my-ghes-host.example.com/_services/token:aud": "sts.amazonaws.com",
    "my-ghes-host.example.com/_services/token:sub": "my-ghes-host.example.com"
  }
}
...

Click Update policy.

3. Configure GitHub Enterprise Server to connect to Amazon S3 using OIDC

From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .
If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.
In the " Site admin" sidebar, click Management Console.
In the "Settings"" sidebar, click Actions.
Under "GitHub Actions", select Enable GitHub Actions.
Under "Artifact & Log Storage", next to "Amazon S3", click Setup.
Under "Authentication", select OpenID Connect (OIDC), and enter the values for your storage:
- AWS S3 Bucket: The name of your S3 bucket.
- AWS Role: The ARN for the role you created in the previous procedures. For example, arn:aws:iam::123456789:role/my-role-name.
- AWS Region: The AWS region for your bucket. For example, us-east-1.
Click the Test storage settings button to validate your storage settings.

If there are any errors validating the storage settings, check the settings with your storage provider and try again.
Under the "Settings" sidebar, click Save settings.

Note: Saving settings in the Management Console restarts system services, which could result in user-visible downtime.
Wait for the configuration run to complete.