Skip to content

Nerdware-LLC/reusable-action-workflows

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

93 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Nerdware_Logo

Reusable GitHub Actions Workflows

Author: Trevor Anderson, Founder of Nerdware

Reusable Workflow Best Practices

  • When calling any reusable workflow, pegging the version to a specific ref/SHA is recommended. This ensures that your workflow will not break if a new version of the workflow is released which contains breaking changes. In the example below, the version is pegged to the v1.5.0 tag, but you can also use the main branch to always use the latest version.
    jobs:
      my_job_using_foo_workflow:
        uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
  • Provide only the necessary minimum permissions to any given workflow. For more information, see "Automatic token authentication."

This workflow builds a Docker image using BuildKit and uploads it to an ECR repo.

Requirements:

  • You must have an existing ECR image repo.
  • The calling workflow must specify an OpenID Connect IAM role ARN with which the relevant API calls can be authenticated. Support for other forms of authentication may be added in the future.

Usage:

jobs:
  my_job_using_ecr_image_push:
    uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
    secrets:
      OIDC_GITHUB_ROLE_ARN: ${{ secrets.OIDC_GITHUB_ROLE_ARN }}
      AWS_ECR_PRIVATE_REPO: ${{ secrets.AWS_ECR_PRIVATE_REPO }}
      AWS_ECR_REGION: ${{ secrets.AWS_ECR_REGION }}
    permissions:
      id-token: write
      contents: read

This workflow outputs a JSON-formatted array of three Docker tags which can be used in docker build and/or docker tag commands.

In order, the tags provided in the output are as follows:

  1. "latest", a constant which this action always includes in the output.

  2. A version tag based either on the version-tag input OR the "version" property in a package.json, if one is present.

  3. A ref tag based on the variable component of the GITHUB_REF env var, the value of which depends on the type of event which triggered the Action run:

    EVENT REF IMAGE TAG
    branch push refs/heads/<branch_name> <branch_name>
    pull request refs/pull/<pr_number>/merge <pr_number>
    release refs/tags/<release_tag> <release_tag>

Usage:

jobs:
  my_job_using_get_docker_tags:
    uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
    with:
      tag-prefix: my-image-name # required input
      version-tag: v1.0.0 # optional input - defaults to the "version" specified in package.json

This workflow sets up NodeJS, runs your test-script (default: test:ci), updates the GitHub commit status, and optionally updates CodeCov. The input env-vars is a string formatted as a space-separated list of environment variables to be set in the workflow; this is a workaround to the limitation that the env context in caller workflows is not propagated to called workflows. The input test-script is the name of the npm script to run.

Artifacts: If your test-script creates coverage reports at <repo-root>/coverage, the coverage dir will be uploaded as an artifact named coverage-reports. This artifact can be downloaded in a subsequent step using the download-artifact action. To disable this behavior, set the input should-upload-coverage-artifacts to false.

Usage:

jobs:
  my_job_using_node_test:
    uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
    with:
      test-script: "test:ci"
      # Note the >- below; this block-chomping indicator will rm all newline chars, and separate each line by a space.
      env-vars: >-
        [email protected]
        FOO=bar
        BAZ=qux
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} # <-- Optional

This workflow builds a Docker image as a ZIP archive and then uploads it to an S3 bucket.

Requirements:

  • You must have an existing S3 bucket with default SSE encryption. Support for buckets encrypted with a user-managed KMS key may be added in the future.
  • The calling workflow must specify an OpenID Connect IAM role ARN with which the relevant API calls can be authenticated. Support for other forms of authentication may be added in the future.

Usage:

jobs:
  my_job_using_s3_image_upload:
    uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
    with:
      image-name: foo-image-name
    secrets:
      OIDC_GITHUB_ROLE_ARN: ${{ secrets.OIDC_GITHUB_ROLE_ARN }}
      S3_BUCKET_DEST: ${{ secrets.S3_BUCKET_DEST }}
      S3_BUCKET_REGION: ${{ secrets.S3_BUCKET_REGION }}

This workflow uses Semantic Release to publish a GitHub release.

Requirements:

Usage:

jobs:
  my_job_using_release:
    uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
    secrets:
      SEMANTIC_RELEASE_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
      # or "${{ secrets.GITHUB_TOKEN }}" (see above info regarding auth requirements)

This workflow creates a NodeJS build via npm run build, and then uploads the resultant package to an S3 bucket using the aws s3 sync command.

Requirements:

  • Your project's repo root must include a package.json file with a defined build script.
  • You must have an existing S3 bucket with default SSE encryption. Support for buckets encrypted with a user-managed KMS key may be added in the future.
  • The calling workflow must specify an OpenID Connect IAM role ARN with which the relevant API calls can be authenticated. Support for other forms of authentication may be added in the future.

Usage:

jobs:
  my_job_using_upload_to_s3:
    uses: Nerdware-LLC/reusable-action-workflows/.github/workflows/[email protected] # or @main
    with:
      s3-sync-command-params: "--acl bucket-owner-full-control --sse AES256"
      # The above s3-sync command params would be sufficient for a bucket with default SSE encryption
      # and standard ACL protections. For more info on s3-sync command options, see the documentation
      # at https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/sync.html#options
    secrets:
      OIDC_GITHUB_ROLE_ARN: ${{ secrets.OIDC_GITHUB_ROLE_ARN }}
      S3_BUCKET_REGION: ${{ secrets.S3_BUCKET_REGION }}
      S3_UPLOAD_PATH: ${{ secrets.S3_UPLOAD_PATH }} # my_foo_bucket/production

πŸ“ License

Nerdware-LLC/reusable-action-workflows is licensed under the Apache License 2.0, a permissive license whose main conditions require preservation of copyright and license notices. Contributors provide an express grant of patent rights. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

See LICENSE for more information.

πŸ’¬ Contact

Trevor Anderson β€” [email protected] β€” @TeeRevTweets

Check out Nerdware on YouTube   Trevor Anderson's LinkedIn   Trevor Anderson's Twitter   Email Trevor Anderson

Dare Mighty Things.