Deploy an artifact to S3

When you create an environment, Gapstack automatically creates two resources in your AWS account and region:

An S3 bucket for artifacts
An OpenID Connect (OIDC) IAM role so GitHub Actions can authenticate to AWS without long-lived access keys

Copy the bucket name and role from the environment Details page. Store those values as GitHub Actions variables, then add the following steps to your workflow.

Do not store AWS access keys in GitHub. Use the OIDC role from the environment.

Copy values from the environment Details page

Open the environment in Gapstack and click Details. Copy these fields:

OpenID Role → ROLE_TO_ASSUME
Artifacts → BUCKET_SOURCE
Region → AWS_REGION
The environment name → ENVIRONMENT and STAGE

Use the copy icon next to each field.

Environment Details page with OpenID Role and Artifacts highlighted. Each field has a copy button. — Copy OpenID Role and Artifacts from the environment Details page.

Add GitHub Actions variables

Add the values you copied as repository variables so the workflow can read them.

In GitHub, open the repository.
Click Settings.
Click Secrets and variables, then Actions.
Open the Variables tab.
Click New repository variable for each variable below.

Name	Value
`AWS_REGION`	Region on the environment Details page (for example `us-west-1`)
`ENVIRONMENT`	The environment name (for example `prod`)
`STAGE`	The stage name (for example `prod`)
`BUCKET_SOURCE`	Artifacts on the environment Details page
`ROLE_TO_ASSUME`	OpenID Role on the environment Details page

Set environment variables

Add an env block at the top of the workflow. It reads the repository variables you created.

env:
  STAGE: ${{ vars.STAGE }}
  APP_NAME: ${{ github.event.repository.name }}
  AWS_REGION: ${{ vars.AWS_REGION }}
  ENVIRONMENT: ${{ vars.ENVIRONMENT }}
  BUCKET_SOURCE: ${{ vars.BUCKET_SOURCE }}
  ROLE_TO_ASSUME: ${{ vars.ROLE_TO_ASSUME }}

Configure AWS credentials (OIDC)

Assume the environment OIDC role. GitHub issues a short-lived token. AWS trusts that token.

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ env.ROLE_TO_ASSUME }}
    role-session-name: OIDCSession
    aws-region: ${{ env.AWS_REGION }}

The job needs permissions: id-token: write so GitHub can mint the OIDC token.

Upload Artifact to S3

Copy the zip into the environment artifacts bucket. Change ./cmd/main.zip if your build output lives somewhere else.

- name: Upload Artifact
  run: |
    aws s3 cp ./cmd/main.zip s3://${{ env.BUCKET_SOURCE }}/${{ env.APP_NAME }}/${{ env.ENVIRONMENT }}/main.zip

Required GitHub Actions variables

Variable	Copy from
`ROLE_TO_ASSUME`	OpenID Role on the environment Details page
`AWS_REGION`	Region on the environment Details page
`BUCKET_SOURCE`	Artifacts on the environment Details page
`ENVIRONMENT`	The environment name (for example `dev` or `prod`)
`STAGE`	The stage name (for example `prod`)

Example workflow

name: Upload artifact

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

env:
  STAGE: ${{ vars.STAGE }}
  APP_NAME: ${{ github.event.repository.name }}
  AWS_REGION: ${{ vars.AWS_REGION }}
  ENVIRONMENT: ${{ vars.ENVIRONMENT }}
  BUCKET_SOURCE: ${{ vars.BUCKET_SOURCE }}
  ROLE_TO_ASSUME: ${{ vars.ROLE_TO_ASSUME }}

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ env.ROLE_TO_ASSUME }}
          role-session-name: OIDCSession
          aws-region: ${{ env.AWS_REGION }}

      - name: Upload Artifact
        run: |
          aws s3 cp ./cmd/main.zip s3://${{ env.BUCKET_SOURCE }}/${{ env.APP_NAME }}/${{ env.ENVIRONMENT }}/main.zip

APP_NAME comes from the repository name. The other values come from the GitHub Actions variables you added.

Next steps

After the file is in S3, create a Lambda and select that artifact. See Deploy a Lambda.

Getting started

Guides

Troubleshooting

Deploy an artifact to S3

Required GitHub Actions variables

Example workflow

Next steps

​Required GitHub Actions variables

​Example workflow

​Next steps

Required GitHub Actions variables

Example workflow

Next steps