- π‘ Reusable Workflow Best Practices
- π Available Workflows:
- π License
- π¬ Contact
- 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:
-
"latest", a constant which this action always includes in the output.
-
A version tag based either on the version-tag input OR the "version" property in a package.json, if one is present.
-
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:
- Configuration: Your repo must include a Semantic Release config file.
- Authentication: You must provide an auth token granting push access to the project Git repo via a secret named
SEMANTIC_RELEASE_TOKEN
. Semantic Release requires these permissions in order to create git tags.- If your repo does not use branch protection rules, the default
GITHUB_TOKEN
is sufficient. - If your repo does include branch protection rules, the calling workflow must instead provide a personal access token granting push access to the project Git repo.
- If your repo does not use branch protection rules, the default
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 definedbuild
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
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.
Trevor Anderson β [email protected] β @TeeRevTweets