diff --git a/.github/.pre-commit-config.yaml b/.github/.pre-commit-config.yaml new file mode 100644 index 0000000..668d5fd --- /dev/null +++ b/.github/.pre-commit-config.yaml @@ -0,0 +1,52 @@ +--- +# install with: 'pre-commit install --config=.github/.pre-commit-config.yaml' + +minimum_pre_commit_version: 3.3.0 +default_install_hook_types: [pre-commit, commit-msg] +default_stages: [commit] + +repos: + - repo: meta + hooks: + - id: check-hooks-apply + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-executables-have-shebangs + - id: check-shebang-scripts-are-executable + - id: check-case-conflict + - id: mixed-line-ending + args: ['-f=lf'] + + - repo: https://github.com/espressif/conventional-precommit-linter + rev: v1.10.0 + hooks: + - id: conventional-precommit-linter + + - repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + args: ['--write-changes'] + additional_dependencies: [tomli] + + - repo: https://github.com/executablebooks/mdformat + rev: 0.7.17 + hooks: + - id: mdformat + args: [--number] + additional_dependencies: + - mdformat-gfm + - mdformat-ruff + - mdformat-simple-breaks + + - repo: https://github.com/Yelp/detect-secrets + rev: v1.5.0 + hooks: + - id: detect-secrets + args: + - --base64-limit=4 + - --hex-limit=3 diff --git a/.github/workflows/reusable-dangerjs.yml b/.github/workflows/reusable-dangerjs.yml new file mode 100644 index 0000000..953578f --- /dev/null +++ b/.github/workflows/reusable-dangerjs.yml @@ -0,0 +1,132 @@ +--- +# Reusable workflow in "espressif/.github" repository (Organization level) +name: DangerJS (PR style linter) + +on: + workflow_call: + inputs: + ref: + description: 'The pull request head reference' + required: true + type: string + rule-description: + description: 'Enable rule for PR Description' + required: false + type: string + default: 'true' + rule-commit-messages: + description: 'Enable rule for PR Lint Commit Messages' + required: false + type: string + default: 'true' + rule-size-lines: + description: 'Enable rule for PR Size (changed lines)' + required: false + type: string + default: 'true' + rule-source-branch: + description: 'Enable rule for PR Source branch name' + required: false + type: string + default: 'true' + rule-target-branch: + description: 'Enable rule for PR Target branch name' + required: false + type: string + default: 'true' + rule-max-commits: + description: 'Enable rule for PR Too Many Commits' + required: false + type: string + default: 'true' + commit-messages-types: + description: 'Allowed commit message "Type"s' + required: false + type: string + default: 'change,ci,docs,feat,fix,refactor,remove,revert,test' + commit-messages-max-body-line-length: + description: 'Max length for commit message "Body" line' + required: false + type: string + default: '100' + commit-messages-max-summary-length: + description: 'Max length for commit message "Summary"' + required: false + type: string + default: '72' + commit-messages-min-summary-length: + description: 'Min length for commit message "Summary"' + required: false + type: string + default: '20' + description-ignore-sections: + description: 'Sections of PR description to ignore when counting length' + required: false + type: string + default: 'related,release,breaking' + max-size-lines: + description: 'Max changed code lines in PR' + required: false + type: string + default: '1000' + max-commits-info: + description: 'Soft limit for maximum commits in PR' + required: false + type: string + default: '2' + max-commits-warn: + description: 'Hard limit for maximum commits in PR' + required: false + type: string + default: '5' + instructions-contributions-file: + description: 'Path to CONTRIBUTING.md or other instructions file' + required: false + type: string + default: '' + instructions-gitlab-mirror: + description: 'Enable GitLab mirror instructions' + required: false + type: string + default: 'false' + instructions-cla-link: + description: 'Link to CLA (Contributor License Agreement)' + required: false + type: string + default: '' + +permissions: + pull-requests: write + contents: write + +jobs: + dangerjs: + runs-on: ubuntu-latest + steps: + - name: Check out Pull Request head + uses: actions/checkout@v4 + with: + ref: ${{ inputs.ref }} + + - name: DangerJS (PR style linter) + uses: espressif/shared-github-dangerjs@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + rule-description: ${{ inputs.rule-description }} + rule-commit-messages: ${{ inputs.rule-commit-messages }} + rule-size-lines: ${{ inputs.rule-size-lines }} + rule-source-branch: ${{ inputs.rule-source-branch }} + rule-target-branch: ${{ inputs.rule-target-branch }} + rule-max-commits: ${{ inputs.rule-max-commits }} + commit-messages-types: ${{ inputs.commit-messages-types }} + commit-messages-max-body-line-length: ${{ inputs.commit-messages-max-body-line-length }} + commit-messages-max-summary-length: ${{ inputs.commit-messages-max-summary-length }} + commit-messages-min-summary-length: ${{ inputs.commit-messages-min-summary-length }} + description-ignore-sections: ${{ inputs.description-ignore-sections }} + max-size-lines: ${{ inputs.max-size-lines }} + max-commits-info: ${{ inputs.max-commits-info }} + max-commits-warn: ${{ inputs.max-commits-warn }} + instructions-contributions-file: ${{ inputs.instructions-contributions-file }} + instructions-gitlab-mirror: ${{ inputs.instructions-gitlab-mirror }} + instructions-cla-link: ${{ inputs.instructions-cla-link }} diff --git a/.github/workflows/reusable-pre-commit.yml b/.github/workflows/reusable-pre-commit.yml new file mode 100644 index 0000000..8f2a56b --- /dev/null +++ b/.github/workflows/reusable-pre-commit.yml @@ -0,0 +1,34 @@ +--- +# Reusable workflow in "espressif/.github" repository (Organization level) +name: Pre-commit (PR code changes) + +on: + workflow_call: + inputs: + python-version: + description: 'The Python version to use in CI' + required: false + type: string + default: '3.9' + skip: + description: "The pre-commit hooks to skip in CI" + required: false + type: string + default: 'pip-compile' + +jobs: + pre-commit: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ inputs.python-version }} + + - name: Run pre-commit + uses: pre-commit/action@v3.0.1 + env: + SKIP: ${{ inputs.skip }} diff --git a/.github/workflows/reusable-sync-jira-issue-comments.yml b/.github/workflows/reusable-sync-jira-issue-comments.yml new file mode 100644 index 0000000..29bbf62 --- /dev/null +++ b/.github/workflows/reusable-sync-jira-issue-comments.yml @@ -0,0 +1,33 @@ +--- +# Reusable workflow in "espressif/.github" repository (Organization level) +name: Sync JIRA - Issue Comments + +on: + workflow_call: + inputs: + jira-project: + description: 'Jira project name' + required: true + type: string + + jira-component: + description: 'Jira component name' + required: false + type: string + default: 'GitHub' + +jobs: + sync_issue_comments_to_jira: + name: Sync Issue Comments to Jira + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Sync issue comments to JIRA + uses: espressif/sync-jira-actions@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + JIRA_PASS: ${{ secrets.JIRA_PASS }} + JIRA_PROJECT: ${{ inputs.jira-project }} + JIRA_COMPONENT: ${{ inputs.jira-component }} + JIRA_URL: ${{ secrets.JIRA_URL }} + JIRA_USER: ${{ secrets.JIRA_USER }} diff --git a/.github/workflows/reusable-sync-jira-issues.yml b/.github/workflows/reusable-sync-jira-issues.yml new file mode 100644 index 0000000..2a33208 --- /dev/null +++ b/.github/workflows/reusable-sync-jira-issues.yml @@ -0,0 +1,33 @@ +--- +# Reusable workflow in "espressif/.github" repository (Organization level) +name: Sync JIRA - Issues + +on: + workflow_call: + inputs: + jira-project: + description: 'Jira project name' + required: true + type: string + + jira-component: + description: 'Jira component name' + required: false + type: string + default: 'GitHub' + +jobs: + sync-jira-issues: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Sync JIRA - Issues + uses: espressif/sync-jira-actions@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + JIRA_PASS: ${{ secrets.JIRA_PASS }} + JIRA_PROJECT: ${{ inputs.jira-project }} + JIRA_COMPONENT: ${{ inputs.jira-component }} + JIRA_URL: ${{ secrets.JIRA_URL }} + JIRA_USER: ${{ secrets.JIRA_USER }} diff --git a/.github/workflows/reusable-sync-jira-prs.yml b/.github/workflows/reusable-sync-jira-prs.yml new file mode 100644 index 0000000..51d980f --- /dev/null +++ b/.github/workflows/reusable-sync-jira-prs.yml @@ -0,0 +1,41 @@ +--- +# Reusable workflow in "espressif/.github" repository (Organization level) +name: Sync JIRA - Pull Requests + +on: + workflow_call: + inputs: + cron-job: + description: 'Run as scheduled job' + required: false + type: boolean + default: true + + jira-project: + description: 'Jira project name' + required: true + type: string + + jira-component: + description: 'Jira component name' + required: false + type: string + default: 'GitHub' + +jobs: + sync-jira-pull-requests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: JIRA Sync - Pull Requests + uses: espressif/sync-jira-actions@v1 + with: + cron_job: ${{ inputs.cron-job }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + JIRA_PASS: ${{ secrets.JIRA_PASS }} + JIRA_PROJECT: ${{ inputs.jira-project }} + JIRA_COMPONENT: ${{ inputs.jira-component }} + JIRA_URL: ${{ secrets.JIRA_URL }} + JIRA_USER: ${{ secrets.JIRA_USER }} diff --git a/.github/workflows/templates/call-pre-commit.yml b/.github/workflows/templates/call-pre-commit.yml new file mode 100644 index 0000000..e209c00 --- /dev/null +++ b/.github/workflows/templates/call-pre-commit.yml @@ -0,0 +1,16 @@ +# Copy this file form here to your TARGET PROJECT (e.g. https://github.com/esptool/.github/workflows/call-pre-commit.yml) + +# If you have another versions of pre-commit hooks Github Action workflow already in your repo, +# (e.g. https://github.com/esptool/.github/workflows/pre-commit.yml) you should remove them +# with adding this file to your repo to avoid conflicts and double execution of the same tasks. + +# Keep it slim after adding to your repo and remove all absolutely unnecessary comments. +--- +name: Pre-commit (PR code changes) + +on: + pull_request: + +jobs: + call-pre-commit: + uses: espressif/.github/.github/workflows/reusable-pre-commit.yml@main diff --git a/.github/workflows/workflows-instructions.md b/.github/workflows/workflows-instructions.md new file mode 100644 index 0000000..2b99e7e --- /dev/null +++ b/.github/workflows/workflows-instructions.md @@ -0,0 +1,181 @@ +These are [GitHub reusable workflows](https://docs.github.com/en/actions/sharing-automations/reusing-workflows) that can be called from any repository within the Espressif GitHub organization. + +> \[!IMPORTANT\] +> Their presence here does not mean they are automatically propagated or inherited across all Espressif organization GitHub repositories +> (as with issue and pull request templates). +> These workflows need to be explicitly called. See the ["Calling from the target repository"](#calling-from-the-target-repository) section for details. + +--- + +- [Reasoning](#reasoning) +- [Calling from the target repository](#calling-from-the-target-repository) +- [Usage in target project (calls)](#usage-in-target-project-calls) + - [Pre-commit (PR code changes)](#pre-commit-pr-code-changes) + - [DangerJS (PR style linter)](#dangerjs-pr-style-linter) + - [JIRA Sync Actions (package)](#jira-sync-actions-package) + - [Sync JIRA - Pull Requests (1/3)](#sync-jira---pull-requests-13) + - [Sync JIRA - Issues (2/3)](#sync-jira---issues-23) + - [Sync JIRA - Issue Comments (3/3)](#sync-jira---issue-comments-33) +- [Troubleshooting](#troubleshooting) + +## Reasoning + +Managing these workflows from a central place like this repository (`espressif/.github`) offers several advantages: + +- **Ease of Integration**: Simplifies the process for repository administrators—only a call statement is needed to integrate the workflow. +- **Centralized Updates**: Quickly update the version of a GitHub workflow for all repositories that use it with a single change here. +- **Consistent Permissions**: Ensure that action permissions are set correctly across all repositories. + +## Calling from the target repository + +In the target repository, e.g., `espressif/example-repo`, the following steps are required: + +1. Create a file at the usual location for GitHub Actions workflow YAML files, such as `.github/workflows/call-pre-commit.yml`. +2. Add the call to the reusable workflow from another Espressif repository. +3. Optionally, you can add parameters that will be passed to the GitHub Action. + +This allows precise customization of the local action configuration without needing to modify the full action YAML file. + +> \[!NOTE\] +> If the configuration ever changes in the `espressif/.github` repository (this repo), there is no need to update every repository — the +> changes are propagated automatically. + +For example, if an external action version is updated (e.g., `uses: actions/setup-python@v4` to `uses: actions/setup-python@v5`), the update would automatically apply to all repositories using this workflow. + +## Usage in target project (calls) + +### Pre-commit (PR code changes) + +```yaml +# FILE: .github/workflows/call-pre-commit.yml +--- +name: Pre-commit (PR code changes) + +on: + pull_request: + +jobs: + call-pre-commit: + uses: espressif/.github/.github/workflows/reusable-pre-commit.yml@main +``` + +**Optional arguments**: + +| input | description | type | default | +| -------------- | -------------------------------- | ------------- | ------------- | +| python-version | Python version the workflow uses | str | '3.9' | +| skip | pre-commit hooks skipped in CI | comma sep str | 'pip-compile' | + +### DangerJS (PR style linter) + +```yaml +# FILE: .github/workflows/call-dangerjs.yml +--- +name: DangerJS (PR style linter) + +on: + pull_request_target: + types: [opened, edited, reopened, synchronize] + +permissions: + pull-requests: write + contents: write + +jobs: + call-dangerjs: + uses: espressif/.github/.github/workflows/reusable-dangerjs.yml@master +``` + +**Optional arguments**: + +| with: | description | type | default | +| ---------------------- | --------------------------------------- | ---- | ------- | +| `rule-commit-messages` | Enable rule for PR Lint Commit Messages | str | 'true' | +| `rule-description` | Enable rule for PR Description | str | 'true' | +| `rule-max-commits` | Enable rule for PR Too Many Commits | str | 'true' | + +> \[!TIP\] +> The table with optional arguments is not exhaustive, it is here for reference. +> More information and config details in in project [espressif/shared-github-dangerjs](https://github.com/espressif/shared-github-dangerjs) + +### JIRA Sync Actions (package) + +#### Sync JIRA - Pull Requests (1/3) + +```yaml +# FILE: .github/workflows/call-sync-jira-prs.yml +--- +name: Sync JIRA - Pull Requests + +on: + workflow_dispatch: # Allows manual triggering of the workflow + schedule: + - cron: '0 * * * *' # Adjust the cron schedule as needed + +concurrency: + group: jira-issues # Ensures only one workflow in the 'jira-issues' group runs at a time (avoid sync issues) + +jobs: + call-sync-jira-pull-requests: + uses: espressif/.github/.github/workflows/reusable-sync-jira-prs.yml@main + with: + jira-project: '' # e.g., 'ESPTOOL' or 'IDFGH' +``` + +#### Sync JIRA - Issues (2/3) + +```yaml +# FILE: .github/workflows/call-sync-jira-prs.yml +--- +name: Sync JIRA - Issues + +on: issues + +concurrency: + group: jira-issues # Ensures only one workflow in the 'jira-issues' group runs at a time (avoid sync issues) + +jobs: + call-sync-jira-pull-requests: + uses: espressif/.github/.github/workflows/reusable-sync-jira-prs.yml@main + with: + jira-project: '' # e.g., 'ESPTOOL' or 'IDFGH' +``` + +#### Sync JIRA - Issue Comments (3/3) + +```yaml +# FILE: .github/workflows/call-sync-jira-prs.yml +--- +name: Sync JIRA - Issue Comments + +on: issue_comment + +concurrency: + group: jira-issues # Ensures only one workflow in the 'jira-issues' group runs at a time (avoid sync issues) + +jobs: + call-sync-jira-pull-requests: + uses: espressif/.github/.github/workflows/reusable-sync-jira-prs.yml@main + with: + jira-project: '' # e.g., 'ESPTOOL' or 'IDFGH' +``` + +**Optional arguments**: + +| input | description | type | default | +| -------------- | --------------------------------------------- | ---- | -------- | +| jira-component | Jira component (if used in Jira project) name | str | 'GitHub' | + +📖 More info in project: https://github.com/espressif/sync-jira-actions + +> \[!TIP\] +> More information and config details in in project [espressif/sync-jira-actions](https://github.com/espressif/sync-jira-actions) + +--- + +## Troubleshooting + +If the reusable workflow is not running in the target repository, check the following: + +- **Actions and Workflow Permissions**: Ensure that the target repository allows `Allow all actions and reusable workflows` (in repo `Settings -> Actions -> Actions permissions`). +- **Correct Path to Reusable Workflow**: Double-check the path in the `uses:` directive. The correct format is `espressif/.github/.github/workflows/.yml@main` (note the two `.github` segments in the path; the first refers to the .github repository, and the second refers to the .github directory within that repository).