upload-cloud-storage

The upload-cloud-storage GitHub Action uploads files to a Google Cloud Storage (GCS) bucket.

Paths to files that are successfully uploaded are set as output variables and can be used in subsequent steps.

This is not an officially supported Google product, and it is not covered by a Google Cloud support contract. To report bugs or request features in a Google Cloud product, please contact Google Cloud support.

Prerequisites

• This action requires Google Cloud credentials that are authorized to upload blobs to the specified bucket. See the Authorization section below for more information.

• This action runs using Node 16. If you are using self-hosted GitHub Actions runners, you must use runner version 2.285.0 or newer.

Usage

⚠️ WARNING! The Node.js runtime has known issues with unicode characters in filepaths on Windows. There is nothing we can do to fix this issue in our GitHub Action. If you use unicode or special characters in your filenames, please use gsutil or gcloud to upload instead.

For uploading a file

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - id: 'checkout'
      uses: 'actions/checkout@v4'

    - id: 'auth'
      uses: 'google-github-actions/auth@v2'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - id: 'upload-file'
      uses: 'google-github-actions/upload-cloud-storage@v2'
      with:
        path: '/path/to/file'
        destination: 'bucket-name'

    # Example of using the output
    - id: 'uploaded-files'
      uses: 'foo/bar@v1'
      env:
        file: '${{ steps.upload-file.outputs.uploaded }}'

The file will be uploaded to gs://bucket-name/file

For uploading a folder

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - id: 'checkout'
      uses: 'actions/checkout@v4'

    - id: 'auth'
      uses: 'google-github-actions/auth@v2'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - id: 'upload-folder'
      uses: 'google-github-actions/upload-cloud-storage@v2'
      with:
        path: '/path/to/folder'
        destination: 'bucket-name'

    # Example of using the output
    - id: 'uploaded-files'
      uses: 'foo/bar@v1'
      env:
        files: '${{ steps.upload-folder.outputs.uploaded }}'

Destination Filenames

If the folder has the following structure:

.
└── myfolder
    ├── file1
    └── folder2
        └── file2.txt

Default Configuration

With default configuration

- id: 'upload-files'
  uses: 'google-github-actions/upload-cloud-storage@v2'
  with:
    path: 'myfolder'
    destination: 'bucket-name'

The files will be uploaded to gs://bucket-name/myfolder/file1,gs://bucket-name/myfolder/folder2/file2.txt

Optionally, you can also specify a prefix in destination.

- id: 'upload-files'
  uses: 'google-github-actions/upload-cloud-storage@v2'
  with:
    path: 'myfolder'
    destination: 'bucket-name/myprefix'

The files will be uploaded to gs://bucket-name/myprefix/myfolder/file1,gs://bucket-name/myprefix/myfolder/folder2/file2.txt

Upload to bucket root

To upload myfolder to the root of the bucket, you can set parent to false. Setting parent to false will omit path when uploading to bucket.

- id: 'upload-files'
  uses: 'google-github-actions/upload-cloud-storage@v2'
  with:
    path: 'myfolder'
    destination: 'bucket-name'
    parent: false

The files will be uploaded to gs://bucket-name/file1,gs://bucket-name/folder2/file2.txt

If path was set to myfolder/folder2, the file will be uploaded to gs://bucket-name/file2.txt

Optionally, you can also specify a prefix in destination.

- id: 'upload-files'
  uses: 'google-github-actions/upload-cloud-storage@v2'
  with:
    path: 'myfolder'
    destination: 'bucket-name/myprefix'
    parent: false

The files will be uploaded to gs://bucket-name/myprefix/file1,gs://bucket-name/myprefix/folder2/file2.txt

Glob Pattern

You can specify a glob pattern like

- id: 'upload-files'
  uses: 'google-github-actions/upload-cloud-storage@v2'
  with:
    path: 'myfolder'
    destination: 'bucket-name'
    glob: '**/*.txt'

This will particular pattern will match all text files within myfolder.

In this case, myfolder/folder2/file2.txt is the only matched file and will be uploaded to gs://bucket-name/myfolder/folder2/file2.txt.

If parent is set to false, it wil be uploaded to gs://bucket-name/folder2/file2.txt.

Inputs

• project_id: (Optional) Google Cloud project ID to use for billing and API requests. If not provided, the project will be inferred from the environment, best-effort. To explicitly set the value:

  project_id: 'my-project'

• universe: (Optional, default: googleapis.com) The Google Cloud universe to use for constructing API endpoints. Trusted Partner Cloud and Google Distributed Hosted Cloud should set this to their universe address.

  You can also override individual API endpoints by setting the environment variable GHA_ENDPOINT_OVERRIDE_<endpoint> where <endpoint> is the API endpoint to override. For example:

  env:
    GHA_ENDPOINT_OVERRIDE_oauth2: 'https://oauth2.myapi.endpoint/v1'

  For more information about universes, see the Google Cloud documentation.

• path: (Required) The path to a file or folder inside the action's filesystem that should be uploaded to the bucket.

  You can specify either the absolute path or the relative path from the action:

  path: '/path/to/file'

  path: '../path/to/file'

• destination: (Required) The destination for the file/folder in the form bucket-name or with an optional prefix in the form bucket-name/prefix. For example, to upload a file named file to the GCS bucket bucket-name:

  destination: 'bucket-name'

  To upload to a subfolder:

  destination: 'bucket-name/prefix'

• gzip: (Optional, default: true) Upload file(s) with gzip content encoding. To disable gzip content-encoding, set the value to false:

  gzip: false

• resumable: (Optional, default: true) Enable resumable uploads. To disable resumable uploads, set the value to false:

  resumable: false

• predefinedAcl: (Optional) Apply a predefined set of access controls to the files being uploaded. For example, to grant project team members access to the uploaded files according to their roles:

  predefinedAcl: 'projectPrivate'

  Acceptable values are: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead. See the document for details.

• headers: (Optional) Set object metadata. For example, to set the Content-Type header to application/json and custom metadata with key custom-field and value custom-value:

  headers: |-
    content-type: 'application/json'
    x-goog-meta-custom-field: 'custom-value'

  Settable fields are: cache-control, content-disposition, content-encoding, content-language, content-type, custom-time. See the document for details. All custom metadata fields must be prefixed with x-goog-meta-.

• parent: (Optional, default: true) Whether the parent directory should be included in GCS destination path. To disable this:

  parent: false

• glob: (Optional) Glob pattern to match for files to upload.

  glob: '*.txt'

• concurrency: (Optional, default: 100) Number of files to simultaneously upload.

  concurrency: '10'

• gcloudignore_path: (Optional, default: .gcloudignore) Path to a gcloudignore file within the repository.

  gcloudignore_path: '.gcloudignore.dev'

• process_gcloudignore: (Optional, default: true) Process a .gcloudignore file present in the top-level of the repository. If true, the file is parsed and any filepaths that match are not uploaded to the storage bucket. To disable, set the value to false:

  process_gcloudignore: false

Outputs

• uploaded: Comma-separated list of files that were uploaded.

Authorization

There are a few ways to authenticate this action. The caller must have permissions to access the secrets being requested.

Via google-github-actions/auth

Use google-github-actions/auth to authenticate the action. You can use Workload Identity Federation or traditional Service Account Key JSON authentication.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - id: 'auth'
      uses: 'google-github-actions/auth@v2'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - uses: 'google-github-actions/upload-cloud-storage@v2'

Via Application Default Credentials

If you are hosting your own runners, and those runners are on Google Cloud, you can leverage the Application Default Credentials of the instance. This will authenticate requests as the service account attached to the instance. This only works using a custom runner hosted on GCP.

jobs:
  job_id:
    steps:
    - id: 'upload-file'
      uses: 'google-github-actions/upload-cloud-storage@v2'

The action will automatically detect and use the Application Default Credentials.