GitHub Action Reference

Scaffoldly provides a seamless integration with GitHub Actions, allowing you to deploy your applications using GitHub. This guide will walk you through the process of setting up GitHub Actions for your Scaffoldly projects.

Scaffoldly is available on the GitHub Actions Marketplace.

Usage

To use Scaffoldly in your GitHub Actions workflow, you need to create a workflow file in your repository. Follow these steps:

AWS IAM Role (Recommended)

1. Create an Identity Provider in AWS IAM for GitHub Actions.

   • Create an OpenID Connect provider.
   • Use the following URL as the Issuer URL: https://token.actions.githubusercontent.com.
   • Use the following value as the Audience: sts.amazonaws.com.
   • (See GitHub Docs for more information)

2. Create a new IAM role in AWS with the necessary permissions for your deployment

   • Create the role using a Web Identity.
   • Use the token.actions.githubusercontent.com as the Identity Provider.
   • Use the sts.amazonaws.com as the Audience.
   • Fill out the respective fields, such as GitHub organization, GitHub repository, etc.
   • Run npx scaffoldly show permissions to see the necessary permissions for the role.

3. Create new Repository Variable in your GitHub repository named AWS_ROLE_ARN for the desired IAM Role.

4. Add the following YAML configuration to your .github/workflows/scaffoldly.yml file:

.github/workflows/scaffoldly.yml

name: Scaffoldly Deploy

on:
  workflow_dispatch:
  push:

permissions:
  id-token: write
  contents: read

env:
  # AWS_REGION: us-east-1 # Optional, defaults to us-east-1
  AWS_ROLE_ARN: ${{ vars.AWS_ROLE_ARN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy
        uses: scaffoldly/scaffoldly@v1
        with:
          secrets: ${{ toJSON(secrets) }}

AWS Access Keys

1. Create a new IAM user in AWS with the necessary permissions for your deployment.

   • Run npx scaffoldly show permissions to see the necessary permissions for the user.
   • Create Access Keys and Secrets Keys for the user.

2. Create new Repository Secrets in your GitHub repository named AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY for the desired IAM User.

3. Add the following YAML configuration to your .github/workflows/scaffoldly.yml file:

.github/workflows/scaffoldly.yml

name: Scaffoldly Deploy

on:
  workflow_dispatch:
  push:

permissions:
  id-token: write
  contents: read

env:
  # AWS_REGION: us-east-1 # Optional, defaults to us-east-1
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy
        uses: scaffoldly/scaffoldly@v1
        with:
          secrets: ${{ toJSON(secrets) }}

Inputs

operation

Default: deploy

The operation to perform. Supported options:

• deploy: Deploy the application application, this is equivalent to npx scaffoldly deploy.

github-token

Default: ${{ github.token}}

The GitHub token to use for authentication. This token is automatically generated by GitHub Actions. Omit this input if the default repository token and its associated permissions is sufficient.

This token could potentially be used for:

• Authentication to AWS services (if using IAM roles).

See:

• AWS Authentication Methods

working-directory

Default: .

The directory where the application code is located. Useful if your application is in a subdirectory. Omit this input if your application is in the root of the repository.

secrets

Recommended: ${{ toJSON(secrets) }}

Default: {}

A JSON string of secrets that can be uploaded into Cloud Secrets.

See:

• Secrets

Outputs

url

The URL of the deployed application. This output can be used in subsequent steps of your workflow.

identity

The identity created or updated for the deployed application. This output can be used in subsequent steps of your workflow.

Questions, Feedback, and Help

• Join our Discussions on GitHub.
• Join our Community on Discord.