|
| 1 | +.. _release_getting_started: |
| 2 | + |
| 3 | +Getting started |
| 4 | +---------------- |
| 5 | + |
| 6 | +This section will guide you through the steps to setup the release workflow in your Arduino asset repository. |
| 7 | + |
| 8 | +Prerequisites |
| 9 | +^^^^^^^^^^^^^^ |
| 10 | + |
| 11 | +Before you start, make sure you satisfy the following prerequisites: |
| 12 | + |
| 13 | +- Your Arduino asset (library or core) is hosted in a GitHub repository. |
| 14 | +- GitHub Actions is enabled in your repository. Check the `GitHub docs <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository>`_ to learn how to enable it. |
| 15 | +- You have appropriate permissions to create releases in your repository. |
| 16 | +- If your asset is an Arduino core, ensure it's properly configured for packaging with the :doc:`arduino-packager.py <../scripts/arduino-packager>` tool. |
| 17 | + |
| 18 | +Setting up the reusable workflow |
| 19 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 20 | + |
| 21 | +In your locally cloned repository, follow these steps: |
| 22 | + |
| 23 | +0. Create a new branch, for example ``devops/release-workflow``. |
| 24 | + |
| 25 | + .. note:: |
| 26 | + This is not strictly necessary, but recommended to avoid pushing changes directly to the main branch. |
| 27 | + |
| 28 | +1. Create a new file in the ``.github/workflows`` directory, for example ``release.yml``. |
| 29 | + |
| 30 | +2. Add the following content to the file: |
| 31 | + |
| 32 | + .. code:: yaml |
| 33 | +
|
| 34 | + name: Release |
| 35 | +
|
| 36 | + on: |
| 37 | + push: |
| 38 | + tags: |
| 39 | + - '[0-9]+.[0-9]+.[0-9]+**' |
| 40 | + workflow_dispatch: |
| 41 | + inputs: |
| 42 | + version: |
| 43 | + description: 'Release version' |
| 44 | + required: true |
| 45 | + default: '' |
| 46 | + type: choice |
| 47 | + options: |
| 48 | + - patch |
| 49 | + - minor |
| 50 | + - major |
| 51 | +
|
| 52 | + jobs: |
| 53 | + arduino-devops: |
| 54 | + uses: Infineon/arduino-devops/.github/workflows/release.yml@latest |
| 55 | + with: |
| 56 | + version: ${{ inputs.version }} |
| 57 | + secrets: inherit |
| 58 | +
|
| 59 | + .. important:: |
| 60 | + Notice the ``@latest`` at the end of the ``uses`` line. This will use the latest version of the reusable workflow. |
| 61 | + This is particularly useful to automatically get the latest updates in the reusable workflow. |
| 62 | + Keep in mind that this may introduce breaking changes in case of major version updates. |
| 63 | + You can also specify a specific version, for example ``@0.4.0``, or a branch, for example ``@main``. |
| 64 | + |
| 65 | +3. Commit your changes and push the branch to the remote. |
| 66 | + |
| 67 | +Additional workflow options |
| 68 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 69 | + |
| 70 | +The GitHub Action reusable workflow provides some additional options often used in the release process: |
| 71 | + |
| 72 | +- ``setup-script`` |
| 73 | + Add a setup script that will be executed before building the release asset. |
| 74 | + For example: |
| 75 | + |
| 76 | + .. code:: yaml |
| 77 | +
|
| 78 | + jobs: |
| 79 | + compile-examples: |
| 80 | + uses: Infineon/arduino-devops/.github/workflows/compile-examples.yml@latest |
| 81 | + with: |
| 82 | + setup-script: bash scripts/before-core-build-setup.sh |
| 83 | +
|
| 84 | +- ``release-ssh-key`` |
| 85 | + This is used to provide a secret SSH key from the repository secrets to the workflow. |
| 86 | + |
| 87 | + For example: |
| 88 | + |
| 89 | + .. code:: yaml |
| 90 | +
|
| 91 | + jobs: |
| 92 | + arduino-devops: |
| 93 | + uses: Infineon/arduino-devops/.github/workflows/release.yml@latest |
| 94 | + with: |
| 95 | + version: ${{ inputs.version }} |
| 96 | + secrets: |
| 97 | + release-ssh-key: ${{ secrets.release_wflow_key }} |
| 98 | +
|
| 99 | + This is required for Arduino libraries when using protection rules that prevent direct |
| 100 | + commit to the default branch. |
| 101 | + |
| 102 | + As the workflow creates new commits and pushes them to the remote repository, the new |
| 103 | + commits will be rejected. |
| 104 | + |
| 105 | + To avoid this, you can use the SSH key to push the changes to the remote repository. |
| 106 | + |
| 107 | + Follow the steps to allow GitHub Actions to push changes directly to the default (protected) branch: |
| 108 | + |
| 109 | + 1. Add a new `deploy key <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys>`_ to your repository with write access. |
| 110 | + This is available in the repository settings under "Deploy keys". |
| 111 | + 2. `Add the private key to your repository secrets <https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions>`_ with the name ``release_wflow_key``. |
| 112 | + 3. If you have any protection rules that prevent direct commits to the default branch, |
| 113 | + `enable the bypass option <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset>`_ for deploy keys. |
| 114 | + |
| 115 | + More information about this approach in this `GitHub discussion <https://github.com/orgs/community/discussions/25305#discussioncomment-3247415>`_. |
| 116 | + |
| 117 | +Creating a release |
| 118 | +^^^^^^^^^^^^^^^^^^ |
| 119 | + |
| 120 | +Once the workflow is set up, you can create releases in different ways: |
| 121 | + |
| 122 | +Release via GitHub actions |
| 123 | +~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 124 | + |
| 125 | +1. Navigate to the ``Actions`` tab of your repository in GitHub. |
| 126 | +2. Select the ``Release`` workflow from the list. |
| 127 | + |
| 128 | + .. image:: ../img/release-from-ga-wflow.png |
| 129 | + :alt: Release workflow selection |
| 130 | + :width: 60% |
| 131 | + :align: center |
| 132 | + |
| 133 | + | |
| 134 | +
|
| 135 | +3. Click ``Run workflow`` and select the default branch (usually ``main`` or ``master``) and the version increment: major, minor, or patch. |
| 136 | + |
| 137 | + .. image:: ../img/release-from-ga-select-version.png |
| 138 | + :alt: Release workflow select version |
| 139 | + :width: 50% |
| 140 | + :align: center |
| 141 | + |
| 142 | + | |
| 143 | +
|
| 144 | +4. The workflow will automatically: |
| 145 | + |
| 146 | + - Validate the version format |
| 147 | + - Generate a changelog |
| 148 | + - Create a GitHub release |
| 149 | + - Upload release assets |
| 150 | + |
| 151 | +5. Once the workflow completes, you will see all the release steps passing, and the new release will be available in the ``Releases`` section of your repository. |
| 152 | + |
| 153 | +Release via GitHub release section |
| 154 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 155 | + |
| 156 | +1. Navigate to the ``Releases`` section of your repository. |
| 157 | + |
| 158 | + .. image:: ../img/release-from-release-new-release.png |
| 159 | + :alt: Release from release section |
| 160 | + :width: 80% |
| 161 | + :align: center |
| 162 | + |
| 163 | + | |
| 164 | +
|
| 165 | +2. Click on the ``Draft a new release`` button. |
| 166 | + |
| 167 | + .. image:: ../img/release-from-release-tag.png |
| 168 | + :alt: Set new tag manually |
| 169 | + :width: 60% |
| 170 | + :align: center |
| 171 | + |
| 172 | + | |
| 173 | +
|
| 174 | +3. Fill in the release tag (e.g., ``0.9.0``), and click on ``Create new tag: 0.9.0``. |
| 175 | + |
| 176 | + .. warning:: |
| 177 | + You are going to set the tag manually. It should be a valid semantic version (semver) format, with a valid increment. |
| 178 | + |
| 179 | +4. This will trigger the release workflow, and it will automatically: |
| 180 | + |
| 181 | + - Validate the version format |
| 182 | + - Generate a changelog |
| 183 | + - Create a GitHub release |
| 184 | + - Upload release assets |
| 185 | + |
| 186 | +5. Once the workflow completes, the new release will be updated with the corresponding title, changelog and assets. |
| 187 | + |
| 188 | +Release from local push |
| 189 | +~~~~~~~~~~~~~~~~~~~~~~~ |
| 190 | + |
| 191 | +In your local repository, use the ``arduino-script.py`` to create a new release. Assuming that you are in the root path of your repository, and that the script is located in the ``arduino-devops`` directory: |
| 192 | + |
| 193 | + .. code:: bash |
| 194 | +
|
| 195 | + python arduino-devops/arduino-script.py new <version> |
| 196 | +
|
| 197 | +This will automatically modify the required files, create a new tag, and push the changes to the remote repository. |
| 198 | +The release workflow will be triggered, verifying the version and creating the release. |
| 199 | +Check the ``release`` section of your repository to see the new release. |
| 200 | + |
| 201 | + .. warning:: |
| 202 | + In case of an Arduino library, make sure that you have the necessary permissions to push modifications directly to the default (usually ``main`` or ``master``) branch of the repository. |
| 203 | + The script will not only create a tag, but also update the `library.properties` file with the new version and push the changes to the remote repository. |
| 204 | + The remote will reject the push if you do not have the right permissions. |
0 commit comments