How to Upload from GitHub Actions
If you host your component source on GitHub, you can automate uploads so that new versions are published whenever you push a tag or merge to your main branch.
There are two ways to authenticate GitHub Actions with the ESP Component Registry:
OIDC (recommended): GitHub proves the identity of your workflow to the registry directly. No secrets to store or rotate.
API token: Store a registry API token as a GitHub secret and pass it to the action. Simpler to set up, but you are responsible for keeping the token secure and rotating it.
Option 1: OIDC authentication (recommended)
With OIDC, GitHub Actions requests a short-lived token from the registry on every run. You never store long-lived credentials.
Setup
Sign in to the ESP Component Registry.
Navigate to the Permissions page (click the dropdown with your username).
Select the namespace where your component will be uploaded. If the component does not exist yet, create it first using the
+button in the Components table.Click on the component name in the Components table.
Add a trusted uploader by clicking the
+button in the Trusted Uploaders table.Field
Required
Description
Repository
Yes
GitHub repository in the form
<owner>/<repo>(for example,espressif/my_component).Workflow
Yes
The workflow filename (for example,
upload.yml) or the workflow display name (for example,Upload component). Must match the workflow that performs the upload.Branch
No
Restrict uploads to a specific branch (for example,
main). If omitted, any branch is allowed.Environment
No
Restrict uploads to a specific GitHub environment. If omitted, any environment is allowed.
In your workflow file, grant the job permission to request an OIDC token (
id-token: write).Use the
upload-components-ci-actionto upload.
Example workflow
name: Upload component
on:
push:
branches: [ main ]
jobs:
upload_components:
runs-on: ubuntu-latest
permissions:
id-token: write
steps:
- uses: actions/checkout@v4
- uses: espressif/upload-components-ci-action@v2
with:
components: "my_component: ."
namespace: "my_namespace"
Option 2: API token
If you cannot use OIDC (for example, self-hosted runners without OIDC support), you can authenticate with an API token instead.
Log in to the registry and copy your API token (see How to Authenticate for Publishing).
Add the token as a GitHub Actions secret (for example,
IDF_COMPONENT_API_TOKEN).Pass it to the action:
name: Upload component
on:
push:
branches: [ main ]
jobs:
upload_components:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: espressif/upload-components-ci-action@v2
with:
components: "my_component: ."
namespace: "my_namespace"
api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}