|
| 1 | +.. _integrations_github: |
| 2 | + |
| 3 | +|github_logo| GitHub |
| 4 | +==================== |
| 5 | + |
| 6 | +.. include:: ../common/experimental_warning.inc |
| 7 | + |
| 8 | +The Conan `GitHub Actions <https://github.com/features/actions>`_ integration allows you to setup |
| 9 | +Conan client in your GitHub Actions workflows in a simple and effective way. |
| 10 | + |
| 11 | +The project can be found on its `GitHub marketplace page <https://github.com/marketplace/actions/setup-conan-client>`_, or |
| 12 | +its `GitHub source page <https://github.com/conan-io/setup-conan>`_ directly. |
| 13 | + |
| 14 | +To use the integration, add a step in your workflow YAML file. The integration will |
| 15 | +install the Conan client and set up the environment for you. |
| 16 | + |
| 17 | +You can customize the following parameters: |
| 18 | + |
| 19 | +- **Conan version**: Specify the Conan version to install (e.g., `2.15.1`). Default: latest stable. |
| 20 | +- **Configuration URLs**: A list of configuration URLs to download and install in Conan home. By default, no configuration is installed. |
| 21 | +- **Conan Audit Token**: The :ref:`audit<devops_audit>` token used for the audit command to scan vulnerabilities in packages. By default, no token is used. |
| 22 | +- **Conan home path**: Set a custom location for the Conan home folder. By default, no custom path is used. |
| 23 | +- **Cache Conan packages**: Cache all packages in your Conan cache automatically and re-use them in a next build. By default, no cache is used. |
| 24 | +- **Python version**: You can specify the Python version to be installed with Conan, the same will be available in the environment. By default, Python 3.10 is installed. |
| 25 | + |
| 26 | +The integration is available for all platforms supported by GitHub Actions, including Linux, Windows, and macOS. |
| 27 | + |
| 28 | +Examples |
| 29 | +-------- |
| 30 | + |
| 31 | +This section provides some examples of how to use the integration in your GitHub Actions workflows. |
| 32 | + |
| 33 | +Scanning Packages for Vulnerabilities in a Nightly Build |
| 34 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 35 | + |
| 36 | +.. warning:: |
| 37 | + |
| 38 | + Do not share your Conan audit token or expose it in your code. Always use GitHub secrets for sensitive data. |
| 39 | + |
| 40 | +First, you need to set up the Conan audit token in your `GitHub secrets`_. |
| 41 | +Then, use the following example to scan for vulnerabilities in a package and its dependencies: |
| 42 | + |
| 43 | +.. code-block:: yaml |
| 44 | + :caption: .github/workflows/ci.yml |
| 45 | +
|
| 46 | + name: Nightly security scan |
| 47 | + on: |
| 48 | + schedule: |
| 49 | + - cron: "0 0 * * *" |
| 50 | +
|
| 51 | + jobs: |
| 52 | + scan-vulnerabilities: |
| 53 | + runs-on: ubuntu-latest |
| 54 | + steps: |
| 55 | + - name: Checkout code |
| 56 | + uses: actions/checkout@v4 |
| 57 | +
|
| 58 | + - name: Install and setup Conan |
| 59 | + uses: conan-io/setup-conan@v1 |
| 60 | + with: |
| 61 | + audit_token: ${{ secrets.MY_CONAN_AUDIT_TOKEN }} |
| 62 | +
|
| 63 | + - name: Scan for vulnerabilities with Conan Audit |
| 64 | + run: | |
| 65 | + conan audit scan . |
| 66 | +
|
| 67 | +This example scans all dependencies in a ``conanfile.py`` in the current directory. |
| 68 | +Note that it uses a `GitHub schedule`_ to run the scan every day at midnight, this is in the case of |
| 69 | +using the free service token, to avoid hitting the daily limits, but still having security checks every day. |
| 70 | + |
| 71 | +Installing Conan configuration and building packages |
| 72 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 73 | + |
| 74 | +This example installs a custom Conan configuration from a URL, |
| 75 | +restores cached packages from previous builds, builds the package defined in the ``conanfile.py``, and uploads it to the Conan server. |
| 76 | + |
| 77 | +.. code-block:: yaml |
| 78 | + :caption: .github/workflows/ci.yml |
| 79 | +
|
| 80 | + name: Build and upload Conan package |
| 81 | + on: |
| 82 | + push: |
| 83 | + branches: |
| 84 | + - 'main' |
| 85 | +
|
| 86 | + jobs: |
| 87 | + build: |
| 88 | + runs-on: ubuntu-latest |
| 89 | + steps: |
| 90 | + - name: Checkout code |
| 91 | + uses: actions/checkout@v4 |
| 92 | +
|
| 93 | + - name: Install and setup Conan |
| 94 | + uses: conan-io/setup-conan@v1 |
| 95 | + with: |
| 96 | + config_urls: https://mycompany.com/conan/configs.git |
| 97 | + cache_packages: true |
| 98 | +
|
| 99 | + - name: Build and upload package |
| 100 | + run: | |
| 101 | + conan create . -pr:a myprofile --build=missing |
| 102 | + conan remote login artifactory developer -p ${{ secrets.MY_CONAN_PASSWORD }} |
| 103 | + conan upload "*" --confirm --remote artifactory |
| 104 | +
|
| 105 | +In this example, the action's option ``cache_packages`` is set to true, so all packages in the Conan cache are cached for the next build. |
| 106 | +Remote information is expected from the configuration installed from the URL pointed by the option ``config_urls``. |
| 107 | +Remote authentication uses GitHub secrets for security. The remote authentication is done using the GitHub secrets, which is a secure way to store sensitive information. |
| 108 | + |
| 109 | + |
| 110 | +.. |github_logo| image:: ../images/integrations/conan-github-logo.png |
| 111 | +.. _`GitHub schedule`: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule |
| 112 | +.. _`GitHub secrets`: https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions |
0 commit comments