GitHub Actions

Prerequisites

1. An EmbeddedCI API key — generate one on the Get Started page.
2. Add two repository secrets in your GitHub repo (Settings → Secrets and variables → Actions):

   • EMBEDDEDCI_API_KEY — your API key.
   • EMBEDDEDCI_API_URL — only needed for self-hosted instances. The action defaults to https://api.embeddedci.com.
3. An embeddedci.yaml file in your project directory. See the configuration reference.

Submission modes

The action supports two modes depending on whether your build needs source files.

Archive mode (recommended)

When source_path is set, the action archives the specified directory (or file) and uploads it alongside the pipeline definition. This is the recommended mode for most projects — your source code, Makefiles, configs, and embeddedci.yaml are all sent together.

The action automatically locates embeddedci.yaml in the archive root. If your pipeline file is at a different path, set embeddedci_yaml to override.

Entire repo:

name: EmbeddedCI
on: [push]

jobs:
  submit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Submit job to EmbeddedCI
        uses: embeddedci-com/submit-job-action@main
        with:
          api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
          source_path: .

Subdirectory with path filter:

name: EmbeddedCI
on:
  push:
    paths:
      - "firmware/**"
      - ".github/workflows/embeddedci.yml"

jobs:
  submit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Submit job to EmbeddedCI
        uses: embeddedci-com/submit-job-action@main
        with:
          api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
          source_path: firmware/

Using paths on the trigger ensures the workflow only runs when relevant files change.

YAML-only mode

When source_path is not set, the action sends only the pipeline YAML as a JSON payload. Use this when your buildpacks fetch all sources via git+ URLs and don't need local project files.

name: EmbeddedCI
on: [push]

jobs:
  submit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Submit job to EmbeddedCI
        uses: embeddedci-com/submit-job-action@main
        with:
          api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
          embeddedci_yaml: embeddedci.yaml

Most users should prefer archive mode, since buildpacks like apps/build and firmware/stm32-build expect local source files.

Inputs

Outputs

The action sets these outputs from the server response. Use them in subsequent workflow steps.

- name: Submit job to EmbeddedCI
  id: submit
  uses: embeddedci-com/submit-job-action@main
  with:
    api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
    source_path: .

- name: Print job ID
  run: echo "Job ID: ${{ steps.submit.outputs.job_id }}"

Typical repository layout

A common pattern is to have your firmware or project in a subdirectory with the embeddedci.yaml at its root:

my-repo/
├── .github/
│   └── workflows/
│       └── embeddedci.yml       # GitHub Actions workflow
├── firmware/
│   ├── embeddedci.yaml          # Pipeline definition
│   ├── Makefile
│   ├── src/
│   │   └── main.c
│   └── include/
│       └── main.h
└── README.md

With source_path: firmware/, the action archives the firmware/ directory and automatically finds embeddedci.yaml inside it. Your build commands in the packs run relative to this directory.

More examples

Self-hosted EmbeddedCI instance

Override the API URL to point to your own server:

- name: Submit job to EmbeddedCI
  uses: embeddedci-com/submit-job-action@main
  with:
    api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
    api_url: https://ci.mycompany.com
    source_path: .

Custom pipeline file path

If your embeddedci.yaml is not at the root of the archived directory:

- name: Submit job to EmbeddedCI
  uses: embeddedci-com/submit-job-action@main
  with:
    api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
    source_path: firmware/
    embeddedci_yaml: ci/embeddedci.yaml

Pre-built archive

If you already have a tar.gz archive (e.g. from a prior build step):

- name: Submit job to EmbeddedCI
  uses: embeddedci-com/submit-job-action@main
  with:
    api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
    source_path: repo.tar.gz

Multiple projects in one repo

Submit multiple projects as separate jobs using parallel workflow jobs:

name: EmbeddedCI
on: [push]

jobs:
  firmware-a:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: embeddedci-com/submit-job-action@main
        with:
          api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
          source_path: project-a/

  firmware-b:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: embeddedci-com/submit-job-action@main
        with:
          api_key: ${{ secrets.EMBEDDEDCI_API_KEY }}
          source_path: project-b/

Tips

• Use paths on your workflow trigger to avoid unnecessary submissions when unrelated files change.
• Prefer passing a directory to source_path and let the action create the archive. If you create archives manually, exclude .git/, build outputs, and caches.
• Place embeddedci.yaml at the root of your source_path directory for automatic detection. Use embeddedci_yaml only when it lives at a non-standard path.
• The ref and commit inputs are auto-detected from the GitHub context. You only need to set them explicitly in unusual scenarios (e.g. triggered by a different repo).
• Supported archive formats: .tar.gz, .tgz, .tar, .zip.

Next steps

• Configuration reference — write your embeddedci.yaml.
• Buildpacks — choose the right packs for your project.
• Get Started — generate an API key and try a manual submission first.