From ab838b1ba74d1debbdf95dd923201c4c63635144 Mon Sep 17 00:00:00 2001 From: Swanny Date: Wed, 26 Nov 2025 09:04:48 -0500 Subject: [PATCH] docs: update all docs --- docs/auto-release.md | 2 +- docs/ecr-build-and-push.md | 81 ++++++++++++++++ docs/forge-script.md | 10 +- docs/ghcr.md | 34 +++++++ docs/ghcr.yml | 34 +++++++ docs/index.md | 5 + docs/release-docker-ghcr.md | 22 ++++- docs/release-rust-bin.md | 2 +- docs/rust-library-base.md | 98 ++++++++++++++++++++ docs/solidity-coverage.md | 33 +++++++ docs/solidity-deployment.md | 59 +++++++----- examples/example-auto-release-rust.yml | 4 +- examples/example-auto-release-solidity.yml | 13 ++- examples/example-forge-script.yml | 32 +++++++ examples/example-ghcr.yml | 18 ++++ examples/example-github-release-binaries.yml | 18 ++++ examples/example-release-rust-bin.yml | 19 ++++ examples/example-rust-library-base.yml | 15 +++ examples/example-solidity-coverage.yml | 12 +++ examples/example-solidity-deployment.yml | 46 +++++++++ 20 files changed, 518 insertions(+), 39 deletions(-) create mode 100644 docs/ecr-build-and-push.md create mode 100644 docs/ghcr.md create mode 100644 docs/ghcr.yml create mode 100644 docs/rust-library-base.md create mode 100644 docs/solidity-coverage.md create mode 100644 examples/example-forge-script.yml create mode 100644 examples/example-ghcr.yml create mode 100644 examples/example-github-release-binaries.yml create mode 100644 examples/example-release-rust-bin.yml create mode 100644 examples/example-rust-library-base.yml create mode 100644 examples/example-solidity-coverage.yml create mode 100644 examples/example-solidity-deployment.yml diff --git a/docs/auto-release.md b/docs/auto-release.md index 98194c2..f73ff05 100644 --- a/docs/auto-release.md +++ b/docs/auto-release.md @@ -1,4 +1,4 @@ -# github-release-binaries.yml +# auto-release.yml ## Base Usage diff --git a/docs/ecr-build-and-push.md b/docs/ecr-build-and-push.md new file mode 100644 index 0000000..b4a8a8b --- /dev/null +++ b/docs/ecr-build-and-push.md @@ -0,0 +1,81 @@ +# ecr-build-and-push.yml + +## Base Usage + +```yml +docker-ecr-push: + uses: init4tech/actions/.github/workflows/ecr-build-and-push.yml@main + with: + rust-binary-name: 'my-binary' + environment: 'dev' + secrets: + aws-ecr-repository: ${{ secrets.AWS_ECR_REPOSITORY }} + aws-ecr-deployer-role-arn: ${{ secrets.AWS_ECR_DEPLOYER_ROLE_ARN }} +``` + +## Required Parameters + +### `rust-binary-name` + +**Description:** Name of the Rust binary to build + +**Type**: `string` + +### `environment` + +**Description:** Environment to deploy to (used for GitHub environment secrets) + +**Type**: `string` + +## Optional Parameters + +### `requires-private-deps` + +**Description:** Requires private dependencies to be fetched, sets up ssh-agent + +**Type**: `boolean` + +**Default Value:** `false` + +### `dockerfile-path` + +**Description:** Path to the Dockerfile to use + +**Type**: `string` + +**Default Value:** `Dockerfile` + +## Required Secrets + +### `aws-ecr-repository` + +**Description:** ECR repository to push to + +**Type**: `string` + +### `aws-ecr-deployer-role-arn` + +**Description:** Role ARN to assume for ECR access + +**Type**: `string` + +## Optional Secrets + +### `SSH_PRIVATE_KEY` + +**Description:** SSH private key for fetching private dependencies (required if `requires-private-deps` is `true`) + +**Type**: `string` + +### `SSH_PRIVATE_KEY_2` + +**Description:** Additional SSH private key for fetching private dependencies + +**Type**: `string` + +### `SSH_PRIVATE_KEY_3` + +**Description:** Additional SSH private key for fetching private dependencies + +**Type**: `string` + diff --git a/docs/forge-script.md b/docs/forge-script.md index a09e846..f654c00 100644 --- a/docs/forge-script.md +++ b/docs/forge-script.md @@ -1,13 +1,13 @@ -# github-release-binaries.yml +# forge-script.yml ## Base Usage ```yml forge-script: - uses: init4tech/actions/.github/workflows/auto-release.yml@main + uses: init4tech/actions/.github/workflows/forge-script.yml@main with: github-environment: 'dev' - forge-script-contract: '0x0000000000000000000000000000000000000000' + forge-script-contract: 'MyScript' forge-script-signature: 'myFunction(address,uint256)' forge-script-params: '0x0000000000000000000000000000000000000000 123' ``` @@ -16,13 +16,13 @@ forge-script: ### `github-environment` -**Description:** The github environment to use for the release +**Description:** The GitHub environment to use (contains required secrets) **Type**: `string` ### `forge-script-contract` -**Description:** The forge script contract to use for the release +**Description:** Name of the script contract to run **Type**: `string` diff --git a/docs/ghcr.md b/docs/ghcr.md new file mode 100644 index 0000000..304f42c --- /dev/null +++ b/docs/ghcr.md @@ -0,0 +1,34 @@ +# ghcr.yml + +## Base Usage + +```yml +build-and-push: + uses: init4tech/actions/.github/workflows/ghcr.yml@main +``` + +## Description + +This workflow builds and pushes a Docker image to GitHub Container Registry (GHCR). It builds multi-platform images for both `linux/amd64` and `linux/arm64` architectures and generates artifact attestations for supply chain security. + +The workflow automatically: +- Builds the Docker image from the repository's `Dockerfile` +- Tags the image based on the git reference (branch, PR, tag, etc.) +- Pushes to `ghcr.io/` +- Generates artifact attestations for provenance + +## Required Permissions + +The calling workflow must have the following permissions: + +- `contents: read` - To checkout the repository +- `packages: write` - To push to GHCR +- `attestations: write` - To create attestations +- `id-token: write` - For OIDC authentication + +## Notes + +- The image name is automatically set to `ghcr.io/` +- The workflow uses the repository's default Dockerfile in the root directory +- Multi-platform builds are performed for both AMD64 and ARM64 architectures + diff --git a/docs/ghcr.yml b/docs/ghcr.yml new file mode 100644 index 0000000..304f42c --- /dev/null +++ b/docs/ghcr.yml @@ -0,0 +1,34 @@ +# ghcr.yml + +## Base Usage + +```yml +build-and-push: + uses: init4tech/actions/.github/workflows/ghcr.yml@main +``` + +## Description + +This workflow builds and pushes a Docker image to GitHub Container Registry (GHCR). It builds multi-platform images for both `linux/amd64` and `linux/arm64` architectures and generates artifact attestations for supply chain security. + +The workflow automatically: +- Builds the Docker image from the repository's `Dockerfile` +- Tags the image based on the git reference (branch, PR, tag, etc.) +- Pushes to `ghcr.io/` +- Generates artifact attestations for provenance + +## Required Permissions + +The calling workflow must have the following permissions: + +- `contents: read` - To checkout the repository +- `packages: write` - To push to GHCR +- `attestations: write` - To create attestations +- `id-token: write` - For OIDC authentication + +## Notes + +- The image name is automatically set to `ghcr.io/` +- The workflow uses the repository's default Dockerfile in the root directory +- Multi-platform builds are performed for both AMD64 and ARM64 architectures + diff --git a/docs/index.md b/docs/index.md index c072ed1..7a786f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,13 +5,18 @@ Welcome to the documentation for the shared Github Actions workflows provided by ## Workflow Docs - [auto-release](./auto-release) +- [auto-release-rust](./auto-release-rust) +- [ecr-build-and-push](./ecr-build-and-push) - [forge-script](./forge-script) +- [ghcr](./ghcr) - [github-release-binaries](./github-release-binaries) - [hugo-build-deploy](./hugo-build-deploy) - [release-crates](./release-crates) - [release-docker-ghcr](./release-docker-ghcr) - [release-rust-bin](./release-rust-bin) - [rust-base](./rust-base) +- [rust-library-base](./rust-library-base) - [solidity-base](./solidity-base) +- [solidity-coverage](./solidity-coverage) - [solidity-deployment](./solidity-deployment) - [solidity-static-analysis](./solidity-static-analysis) diff --git a/docs/release-docker-ghcr.md b/docs/release-docker-ghcr.md index 591f1a2..8913331 100644 --- a/docs/release-docker-ghcr.md +++ b/docs/release-docker-ghcr.md @@ -1,10 +1,26 @@ -# github-release-binaries.yml +# release-docker-ghcr.yml ## Base Usage ```yml release-docker-ghcr: - uses: init4tech/actions/.github/workflows/release-rust-bin.yml@main + uses: init4tech/actions/.github/workflows/release-docker-ghcr.yml@main ``` -## Optional Parameters +## Description + +This workflow builds and pushes a Docker image to GitHub Container Registry (GHCR) for multiple platforms. It builds images for both `linux/amd64` and `linux/arm64` architectures, creates a multi-platform manifest, and generates artifact attestations. + +The workflow automatically: +- Builds Docker images for multiple platforms (AMD64 and ARM64) +- Tags images based on git references (branch, PR, semver tags, SHA) +- Pushes to `ghcr.io/` +- Creates a multi-platform manifest list +- Generates artifact attestations for provenance + +## Required Permissions + +The calling workflow must have the following permissions: + +- `contents: write` - To create releases and tags +- `packages: write` - To push to GHCR diff --git a/docs/release-rust-bin.md b/docs/release-rust-bin.md index 6f9c4b5..86bd5d9 100644 --- a/docs/release-rust-bin.md +++ b/docs/release-rust-bin.md @@ -1,4 +1,4 @@ -# github-release-binaries.yml +# release-rust-bin.yml ## Base Usage diff --git a/docs/rust-library-base.md b/docs/rust-library-base.md new file mode 100644 index 0000000..42b1afd --- /dev/null +++ b/docs/rust-library-base.md @@ -0,0 +1,98 @@ +# rust-library-base.yml + +## Base Usage + +```yml +rust-library-base: + uses: init4tech/actions/.github/workflows/rust-library-base.yml@main +``` + +## Description + +This workflow extends `rust-base.yml` with additional feature checks. It runs all the checks from `rust-base.yml` (tests, doctests, rustfmt, clippy, docs) plus additional clippy checks for all feature combinations. + +## Optional Parameters + +### `rust-channel` + +**Description:** Sets the rust-toolchain channel if no toolchain file present + +**Type**: `string` + +**Default Value:** `stable` + +**Allowed values:** `stable`, `beta`, `nightly` + +### `install-foundry` + +**Description:** Will install `foundry` as a pre-test step to all use of the binary during the test phase + +**Type**: `boolean` + +**Default Value:** `false` + +**Allowed values:** `false`,`true` + +### `require-lockfile` + +**Description:** Will require a `Cargo.lock` file to be present in the repository + +**Type**: `boolean` + +**Default Value:** `false` + +**Allowed values:** `false`,`true` + +### `os` + +**Description:** Sets the OS for the runner + +**Type**: `string` + +**Default Value:** `ubuntu-latest` + +### `requires-private-deps` + +**Description:** Will require the use of private dependencies in the repository, meaning an ssh key needs to be added to ssh-agent + +**Type**: `boolean` + +**Default Value:** `false` + +**Allowed values:** `false`,`true` + +### `rust-profile` + +**Description:** The profile to give to cargo for running + +**Type**: `string` + +**Default Value:** `dev` + +## Optional Secrets + +### `SSH_PRIVATE_KEY` + +**Description:** The SSH private key to be used for private dependencies, required if `requires-private-deps` is set to `true` + +**Type**: `string` + +### `SSH_PRIVATE_KEY_2` + +**Description:** Additional SSH private key for fetching private dependencies + +**Type**: `string` + +### `SSH_PRIVATE_KEY_3` + +**Description:** Additional SSH private key for fetching private dependencies + +**Type**: `string` + +## Jobs + +This workflow runs two jobs: + +1. **rust-base-checks**: Runs all checks from `rust-base.yml` (tests, doctests, rustfmt, clippy, docs) +2. **feature-checks**: Runs clippy with `--all-features` and `--no-default-features` to ensure code compiles with different feature combinations + diff --git a/docs/solidity-coverage.md b/docs/solidity-coverage.md new file mode 100644 index 0000000..8e9bfa1 --- /dev/null +++ b/docs/solidity-coverage.md @@ -0,0 +1,33 @@ +# solidity-coverage.yml + +## Base Usage + +```yml +coverage: + uses: init4tech/actions/.github/workflows/solidity-coverage.yml@main +``` + +## Description + +This workflow checks code coverage for Solidity contracts using Foundry's coverage tools. It generates a coverage report and compares it against a committed `.coverage-report` file to ensure coverage doesn't regress. + +The workflow: +- Generates a code coverage report using `forge coverage` +- Filters out test files, script files, and library files from the report +- Compares the generated report against the committed `.coverage-report` file +- Fails if there are differences, ensuring coverage is maintained + +## Required Files + +The repository must have a `.coverage-report` file committed that contains the expected coverage report. This file is used as a baseline for comparison. + +## Environment Variables + +The workflow uses `FOUNDRY_PROFILE: ci` for the coverage generation. + +## Notes + +- The workflow filters out coverage for test files (`test/`), script files (`script/`), and the `BytesLib` library +- Coverage is checked using the `--ir-minimum` flag for more accurate reporting +- The workflow will fail if the generated coverage differs from the committed `.coverage-report` file + diff --git a/docs/solidity-deployment.md b/docs/solidity-deployment.md index c765b08..ea53331 100644 --- a/docs/solidity-deployment.md +++ b/docs/solidity-deployment.md @@ -1,20 +1,21 @@ -# github-release-binaries.yml +# solidity-deployment.yml ## Base Usage ```yml -release-binaries: - uses: init4tech/actions/.github/workflows/auto-release.yml@main +deploy: + uses: init4tech/actions/.github/workflows/solidity-deployment.yml@main with: network: 'holesky' chain-id: '17000' - environment: 'production' - forge-deployment-contract: 'ForgeDeployment' - forge-deployment-signature: 'deploy' - forge-deployment-script-file: 'deploy.js' + deployer-address: ${{ secrets.DEPLOYER_ADDRESS }} etherscan-url: 'https://holesky.etherscan.io' + environment: 'production' + forge-deployment-contract: 'DeployContract' + forge-deployment-signature: 'deploy()' + forge-deployment-script-file: 'DeployContract.s.sol' secrets: - aws-role: ${{ secrets.AWS_ROLE }} + aws-deployer-role: ${{ secrets.AWS_DEPLOYER_ROLE }} kms-key-id: ${{ secrets.KMS_KEY_ID }} rpc-url: ${{ secrets.RPC_URL }} etherscan-api-key: ${{ secrets.ETHERSCAN_API_KEY }} @@ -24,35 +25,37 @@ release-binaries: ### `network` -**Description:** The evm network to deploy to +**Description:** The EVM network to deploy to -**Type**: `choice` +**Type**: `string` -**Choices**: -- `holesky` +**Default Value:** `holesky` ### `chain-id` -**Description:** Chain ID for the network +**Description:** Chain ID of the network + +**Type**: `string` + +**Default Value:** `17000` -**Type**: `choice` +### `deployer-address` -**Choices**: -- `17000` +**Description:** Address of the deployer account + +**Type**: `string` ### `etherscan-url` **Description:** The base URL for etherscan for the network -**Type**: `choice` - -**Choices**: -- `https://holesky.etherscan.io` +**Type**: `string` +**Default Value:** `https://holesky.etherscan.io` ### `environment` -**Description:** Github Environment to deploy from; contains required secrets +**Description:** GitHub Environment to deploy from; contains required secrets **Type**: `string` @@ -68,15 +71,25 @@ release-binaries: **Type**: `string` +**Default Value:** `deploy()` + ### `forge-deployment-script-file` -**Description:** Name of the file containing the deploy script +**Description:** Name of the deployment script file + +**Type**: `string` + +## Optional Parameters + +### `forge-deployment-params` + +**Description:** Parameters for the deployment script **Type**: `string` ## Required Secrets -### `aws-role` +### `aws-deployer-role` **Description:** AWS Role to assume diff --git a/examples/example-auto-release-rust.yml b/examples/example-auto-release-rust.yml index 3289dda..2cf98bc 100644 --- a/examples/example-auto-release-rust.yml +++ b/examples/example-auto-release-rust.yml @@ -12,7 +12,7 @@ permissions: # these permissions are required for the actions to run contents: write jobs: - auto-release: # this job will create a new tag and release - uses: init4tech/actions/.github/workflows/auto-release.yml@main + auto-release: # this job will create a new tag and release based on Cargo.toml version + uses: init4tech/actions/.github/workflows/auto-release-rust.yml@main with: binary-name: 'my-binary' # the name of the binary that will be used for versioning the release diff --git a/examples/example-auto-release-solidity.yml b/examples/example-auto-release-solidity.yml index 0973943..3d550fc 100644 --- a/examples/example-auto-release-solidity.yml +++ b/examples/example-auto-release-solidity.yml @@ -41,14 +41,19 @@ jobs: generate-tag: true custom-tag: ${{ github.event.inputs.custom-tag }} deploy-contract: # this job will deploy the contract - uses: init4tech/actions/.github/workflows/deploy-contract.yml@main + uses: init4tech/actions/.github/workflows/solidity-deployment.yml@main needs: auto-release with: network: ${{ github.event.inputs.network }} + chain-id: '17000' + deployer-address: ${{ secrets.DEPLOYER_ADDRESS }} + etherscan-url: 'https://holesky.etherscan.io' environment: ${{ github.event.inputs.environment }} - forge-deployment-script: "DeployContract" + forge-deployment-contract: 'DeployContract' + forge-deployment-signature: 'deploy()' + forge-deployment-script-file: 'DeployContract.s.sol' secrets: aws-deployer-role: ${{ secrets.AWS_DEPLOYER_ROLE }} - holesky-kms-key-id: ${{ secrets.HOLESKY_DEPLOYER_KEY_ID }} - holesky-rpc-url: ${{ secrets.HOLESKY_RPC_URL }} + kms-key-id: ${{ secrets.HOLESKY_DEPLOYER_KEY_ID }} + rpc-url: ${{ secrets.HOLESKY_RPC_URL }} etherscan-api-key: ${{ secrets.ETHERSCAN_API_KEY }} diff --git a/examples/example-forge-script.yml b/examples/example-forge-script.yml new file mode 100644 index 0000000..05f8b66 --- /dev/null +++ b/examples/example-forge-script.yml @@ -0,0 +1,32 @@ +name: Run Forge Script + +on: + workflow_dispatch: + inputs: + environment: + description: 'Environment to run script in' + required: true + default: 'dev' + type: choice + options: + - dev + - staging + - production + +permissions: + id-token: write + +# Example of using the forge-script workflow to run a script contract +jobs: + run-script: + uses: init4tech/actions/.github/workflows/forge-script.yml@main + with: + github-environment: ${{ github.event.inputs.environment }} + forge-script-contract: 'MyScript' + forge-script-signature: 'run(address,uint256)' + forge-script-params: '0x0000000000000000000000000000000000000000 1000000' + secrets: + aws-role: ${{ secrets.AWS_ROLE }} + kms-key-id: ${{ secrets.KMS_KEY_ID }} + rpc-url: ${{ secrets.RPC_URL }} + diff --git a/examples/example-ghcr.yml b/examples/example-ghcr.yml new file mode 100644 index 0000000..4f3a377 --- /dev/null +++ b/examples/example-ghcr.yml @@ -0,0 +1,18 @@ +name: Build and Push to GHCR + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + packages: write + attestations: write + id-token: write + +# Example of building and pushing a Docker image to GitHub Container Registry +jobs: + build-and-push: + uses: init4tech/actions/.github/workflows/ghcr.yml@main + diff --git a/examples/example-github-release-binaries.yml b/examples/example-github-release-binaries.yml new file mode 100644 index 0000000..b168a26 --- /dev/null +++ b/examples/example-github-release-binaries.yml @@ -0,0 +1,18 @@ +name: Upload Binaries to Release + +on: + push: + tags: + - 'v*' + # This will trigger when a tag matching v* is pushed (v1.0.0, v2.0.0, etc.) + +permissions: + contents: write + +# This job will build the rust binary and upload it to the GitHub release +jobs: + upload-binaries: + uses: init4tech/actions/.github/workflows/github-release-binaries.yml@main + with: + binary-name: 'my-binary' + diff --git a/examples/example-release-rust-bin.yml b/examples/example-release-rust-bin.yml new file mode 100644 index 0000000..ad6e63d --- /dev/null +++ b/examples/example-release-rust-bin.yml @@ -0,0 +1,19 @@ +name: Release Rust Binary + +on: + push: + tags: + - 'v*' + # This will trigger when a tag matching v* is pushed (v1.0.0, v2.0.0, etc.) + +permissions: + contents: write + +# This job will build the rust binary for multiple platforms and upload them to the GitHub release +jobs: + release-binary: + uses: init4tech/actions/.github/workflows/release-rust-bin.yml@main + with: + binary-name: 'my-binary' + tag: ${{ github.ref_name }} + diff --git a/examples/example-rust-library-base.yml b/examples/example-rust-library-base.yml new file mode 100644 index 0000000..0649f97 --- /dev/null +++ b/examples/example-rust-library-base.yml @@ -0,0 +1,15 @@ +name: CI # Continuous Integration + +on: + push: + branches: [main] + pull_request: + +# Example of using the rust-library-base workflow for library projects +# This workflow includes feature checks in addition to the base rust checks +jobs: + rust-library-base: + uses: init4tech/actions/.github/workflows/rust-library-base.yml@main + with: + require-lockfile: true + diff --git a/examples/example-solidity-coverage.yml b/examples/example-solidity-coverage.yml new file mode 100644 index 0000000..7d94176 --- /dev/null +++ b/examples/example-solidity-coverage.yml @@ -0,0 +1,12 @@ +name: Code Coverage + +on: + pull_request: + push: + branches: [main] + +# Example of using the solidity-coverage workflow to check code coverage +jobs: + coverage: + uses: init4tech/actions/.github/workflows/solidity-coverage.yml@main + diff --git a/examples/example-solidity-deployment.yml b/examples/example-solidity-deployment.yml new file mode 100644 index 0000000..f4e479e --- /dev/null +++ b/examples/example-solidity-deployment.yml @@ -0,0 +1,46 @@ +name: Deploy Smart Contract + +on: + workflow_dispatch: + inputs: + network: + description: 'Network to deploy to' + required: true + default: 'holesky' + type: choice + options: + - holesky + - mainnet + environment: + description: 'Environment to deploy from' + required: true + default: 'dev' + type: choice + options: + - dev + - staging + - production + +permissions: + contents: write + id-token: write + +# Example of deploying a smart contract using the solidity-deployment workflow +jobs: + deploy: + uses: init4tech/actions/.github/workflows/solidity-deployment.yml@main + with: + network: ${{ github.event.inputs.network }} + chain-id: '17000' + deployer-address: ${{ secrets.DEPLOYER_ADDRESS }} + etherscan-url: 'https://holesky.etherscan.io' + environment: ${{ github.event.inputs.environment }} + forge-deployment-contract: 'DeployContract' + forge-deployment-signature: 'deploy()' + forge-deployment-script-file: 'DeployContract.s.sol' + secrets: + aws-deployer-role: ${{ secrets.AWS_DEPLOYER_ROLE }} + kms-key-id: ${{ secrets.KMS_KEY_ID }} + rpc-url: ${{ secrets.RPC_URL }} + etherscan-api-key: ${{ secrets.ETHERSCAN_API_KEY }} +