Actions et CI/CD

fremforge exécute Forgejo Actions, un système de CI/CD compatible avec GitHub Actions. Les fichiers de workflow utilisent la syntaxe YAML de GitHub Actions, et environ 95 % des actions du GitHub Marketplace fonctionnent sans modification.

Emplacement des fichiers de workflow

Placez les fichiers de workflow dans .forgejo/workflows/<name>.yaml à l’intérieur de votre dépôt. Forgejo lit aussi .github/workflows/ par compatibilité avec les dépôts migrés depuis GitHub, mais .forgejo/workflows/ est l’emplacement de référence sur fremforge.

Événements déclencheurs

Variables de contexte

fremforge utilise les noms de contexte github.* par compatibilité avec l’écosystème GitHub Actions. Ils désignent l’instance fremforge/Forgejo, pas GitHub.

Secrets intégrés

Les jetons intégrés ont une courte durée de vie et sont limités à l’exécution de workflow en cours. Ils ne peuvent pas être utilisés en dehors du job qui les a reçus.

Bloc permissions

L’ensemble de permissions par défaut est contents: read. Toutes les autres permissions valent none par défaut, sauf déclaration explicite.

permissions:
  contents: read       # git checkout
  id-token: write      # OIDC token federation
  issues: write        # create / update issues
  pull-requests: write # comment on PRs

Déclarez les permissions au niveau du workflow (elles s’appliquent alors à tous les jobs) ou au niveau de chaque job. Les déclarations au niveau du job remplacent celles du workflow.

Exemple de workflow minimal

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm ci && npm test

Workflows réutilisables

Extrayez la logique commune dans un workflow réutilisable, appelé par d’autres workflows avec workflow_call :

# .forgejo/workflows/reusable.yaml
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string

jobs:
  deploy:
    runs-on: fremforge
    environment: ${{ inputs.environment }}
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}"

Appelez-le depuis un autre workflow :

jobs:
  deploy-staging:
    uses: ./.forgejo/workflows/reusable.yaml@main
    with:
      environment: staging

Cache

Utilisez actions/cache pour conserver des répertoires d’une exécution à l’autre :

- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Les accès au cache accélèrent nettement les jobs pour les gestionnaires de paquets, les outils de build et les sorties compilées. Le cache intégré de actions/setup-node, setup-python, setup-go et setup-java (cache: npm, etc.) utilise le même service.

Comportement du cache sur fremforge :

• Limité au dépôt. Un cache enregistré dans un dépôt n’est jamais visible depuis un autre, que ce soit dans la même organisation ou dans une autre. Au sein d’un dépôt, les branches partagent un même cache.
• Les pull requests sont isolées. Une exécution pull_request peut restaurer les caches du dépôt, mais ce qu’elle enregistre n’est visible que par les exécutions ultérieures de la même pull request : une pull request (y compris issue d’un fork) ne peut donc pas modifier ce que restaurent les autres branches.
• Limites. Jusqu’à 10 Gio par entrée et 10 Gio par dépôt ; lorsqu’un dépôt dépasse cette limite, ses entrées les moins récemment utilisées sont supprimées. Les entrées inutilisées depuis 7 jours, ou plus anciennes que 30 jours, sont supprimées.
• Ne fait jamais échouer un job. Si le cache est indisponible, actions/cache journalise un avertissement et le job continue sans lui.

Le cache est stocké sur l’infrastructure propre de fremforge, dans l’UE.

Environnements et contrôles de déploiement

Les environnements ajoutent aux jobs de déploiement des étapes d’approbation, des approbateurs requis et des secrets propres à l’environnement.

Créez les environnements sous Administration de l’organisation → Environnements (https://frem.sh/<org>/_admin/environments). Configurez des approbateurs requis pour exiger une approbation manuelle avant l’exécution du job.

Faites référence à un environnement dans un job :

jobs:
  deploy-prod:
    runs-on: fremforge
    environment: production
    steps:
      - run: ./deploy.sh

Si des approbateurs requis sont configurés pour production, le job se met en pause dans l’attente d’une approbation avant de s’exécuter. Les secrets définis sur l’environnement production ne sont injectés que dans ce job.

Notes de compatibilité

• Environ 95 % des actions du GitHub Marketplace fonctionnent sans modification.
• secrets.GITHUB_TOKEN est un alias de secrets.FORGEJO_TOKEN. Les actions qui l’utilisent fonctionnent telles quelles.
• Les actions qui appellent directement l’API GitHub (api.github.com codé en dur) échoueront. L’URL de l’API fremforge est https://frem.sh/api/v1.
• Les actions qui lisent des données publiques sur api.github.com (les listes de versions des actions setup-*, les téléchargements de releases) partagent la limite de GitHub de 60 requêtes par heure avec tous les jobs qui utilisent la même adresse IP sortante. Indiquez une version major.minor et fournissez un jeton GitHub.com : voir Limite de débit de l’API GitHub.
• actions/upload-artifact et actions/download-artifact fonctionnent.
• GitHub Packages (ghcr.io, pkg.github.com) n’est pas disponible. Utilisez plutôt le registre de paquets fremforge.
• Les actions qui exigent des fonctionnalités propres à GitHub (GitHub Copilot, GitHub Codespaces, GitHub Packages) n’ont pas d’équivalent fremforge.
• Les commandes de workflow ::set-output, ::set-env et ::add-path ne font rien. Écrivez plutôt dans $GITHUB_OUTPUT, $GITHUB_ENV et $GITHUB_PATH ; voir Sorties, variables d’environnement et PATH.
• Une expression qui ne peut pas être évaluée fait échouer son étape ou son job, de même qu’une strategy.matrix invalide, par exemple un exclude qui nomme une valeur absente de la matrice.
• Les résumés de job ne sont pas pris en charge. Une étape qui écrit dans $GITHUB_STEP_SUMMARY réussit quand même, mais le résumé est ignoré et le journal de l’étape affiche l’avertissement This Forgejo instance does not support job summaries.

Consultez Compatibilité Marketplace pour la matrice de compatibilité complète des 100 actions les plus utilisées.

Sorties, variables d’environnement et PATH

Depuis le 21 octobre 2026, les runners hébergés utilisent forgejo-runner 13, qui a supprimé trois commandes de workflow : ::set-output, ::set-env et ::add-path. Une étape qui affiche l’une d’elles reçoit un avertissement dans son journal et continue normalement, mais la sortie, la variable d’environnement ou l’entrée de PATH n’est pas définie. Le job peut tout de même passer au vert, et une étape ou un job ultérieur lit alors une valeur vide.

C’est surtout important pour les workflows portés depuis GitHub, où ::set-output est obsolète mais encore accepté. Définir ACTIONS_ALLOW_UNSECURE_COMMANDS=true ne rétablit pas ces commandes.

Écrivez plutôt dans les fichiers que désigne le runner. Chacun est disponible sous les noms GITHUB_* et FORGEJO_*, qui pointent vers le même fichier : un workflow qui tourne aussi sur GitHub continue donc de fonctionner avec les noms GITHUB_*.

Avant, ce qui ne définit plus rien :

      - id: version
        run: echo "::set-output name=tag::$(git describe --tags)"
      - run: echo "Releasing ${{ steps.version.outputs.tag }}"   # empty

Après :

      - id: version
        run: echo "tag=$(git describe --tags)" >> "$GITHUB_OUTPUT"
      - run: echo "Releasing ${{ steps.version.outputs.tag }}"

Pour trouver ces commandes dans un dépôt : git grep -nE '::(set-output|set-env|add-path)'. Une action du Marketplace qui les affiche encore perd ses sorties de la même façon ; passez à une version qui écrit dans les fichiers.

Portée des secrets pour les pull requests de forks : politique pull_request_target

En bref : les workflows déclenchés par pull_request_target s’exécutent avec les secrets et les permissions du dépôt cible, même lorsque la pull request provient d’un fork. Ne récupérez et n’exécutez jamais le head de la pull request dans un tel workflow (par exemple actions/checkout avec ref: ${{ github.event.pull_request.head.sha }}) : cela exécute du code non fiable à côté de vos secrets. Utilisez pull_request pour construire et tester les contributions ; les pull requests issues de forks s’y exécutent sans secrets ni jeton d’identité.

pull_request_target exécute les workflows dans le contexte du dépôt cible lorsqu’une pull request provient d’un fork : le workflow a donc accès aux secrets du dépôt cible, alors même que le fichier de workflow a pu être modifié par l’auteur du fork. C’est exactement la forme d’attaque à l’origine de la classe d’incidents GitHub Actions Marketplace de 2023.

Politique de fremforge : les workflows qui utilisent pull_request_target NE DOIVENT PAS exécuter de code fourni par le fork en présence de secrets. Deux schémas sont acceptables :

1. pull_request au lieu de pull_request_target lorsque le workflow doit exécuter le code du fork. Le workflow de la pull request s’exécute alors dans le contexte du fork, sans accès aux secrets du dépôt cible. C’est le schéma par défaut et le plus sûr.
2. pull_request_target UNIQUEMENT pour des workflows en lecture seule d’étiquetage, de tri ou de commentaire, qui extraient explicitement github.sha (la base de fusion, pas la tête du fork) et n’exécutent aucune étape d’installation, de build ou de test fournie par le fork.

Les workflows qui combinent pull_request_target avec un actions/checkout@v4 sur github.event.pull_request.head.sha sont un vecteur d’exfiltration de secrets de niveau SEV-1 et seront signalés lors de la revue avant fusion. Un hook pre-receive Forgejo qui rejette statiquement cette combinaison dangereuse figure dans la feuille de route de durcissement ; en attendant, la revue de code est le contrôle actif.

Aucun environnement pour une exécution issue d’un fork (plus strict que GitHub). Une exécution pull_request_target déclenchée par une pull request provenant d’un fork ne reçoit aucun environnement : ni secrets d’environnement, ni variables d’environnement, ni claim environment dans son jeton OIDC, même lorsque le job déclare environment: et que c’est le fichier de workflow de la base qui s’exécute. GitHub accorde l’environnement à une telle exécution, sous réserve de ses règles de protection ; fremforge ne le fait pas, depuis le 2026-10-27. Les pull requests provenant d’une branche du même dépôt conservent leur environnement, lu depuis le fichier de workflow de la branche de base et soumis comme d’habitude à la règle de branches et aux approbateurs de l’environnement. La règle de branches est vérifiée par rapport à la branche de base visée par la pull request, comme sur GitHub, et non par rapport à la ref propre de la pull request (refs/pull/<n>/head) : un environnement limité à main admet un job pull_request_target du même dépôt sur une pull request vers main. Les secrets de dépôt et d’organisation ne changent pas : une exécution pull_request_target issue d’un fork les reçoit toujours, comme sur GitHub et Forgejo.

C’est pourquoi extraire la tête reste dangereux. Un job pull_request_target qui extrait et exécute le code de la tête de la pull request (une installation, un build, un test, un script provenant de la pull request) livre à ce code tous les secrets que le job peut encore atteindre : les secrets du dépôt et de l’organisation, ainsi que le jeton du job. Retenir l’environnement n’y change rien. Limitez ces jobs au schéma en lecture seule ci-dessus, ou déplacez le travail vers pull_request.

Aucun id-token OIDC pour une exécution issue d’un fork. Une exécution pull_request_target déclenchée par une pull request provenant d’un fork ne reçoit pas d’id-token : getIDToken (ou id-token: write) répond 403, quelle que soit l’audience. Une telle exécution ne peut donc ni se fédérer vers un cloud ni signer sans clé avec Sigstore. Un job qui doit déployer ou signer a sa place sur push ou workflow_dispatch, après qu’un mainteneur a fusionné la modification. Les exécutions provenant du dépôt lui-même, y compris les pull requests issues d’une branche du même dépôt, ne sont pas concernées.

Pour le contexte complet : le modèle de sécurité de Forgejo Actions est le même que celui de GitHub. La sémantique de pull_request_target en est héritée, à ceci près que fremforge ne délivre ni id-token ni environnement à l’exécution d’un fork.

Politique de provenance des images

Les instructions uses: prennent deux formes ; toutes deux sont acceptées sur fremforge, mais leur comportement en matière de sortie réseau diffère :

• uses: <owner>/<repo>@<sha> : résolu sur le miroir d’actions européen à l’adresse frem.sh/<owner>/<repo>. Chaque éditeur amont a sa propre organisation miroir (actions, docker, aws-actions, azure, google-github-actions, peter-evans, softprops, sonarsource, step-security, dorny, pnpm) : uses: actions/checkout@<sha> se résout donc en frem.sh/actions/checkout. Les miroirs se synchronisent avec l’amont toutes les 8 h. C’est la forme recommandée.
• uses: docker://<registry>/<image>:<tag> : Forgejo Actions la résout en récupérant l’image directement depuis l’URL de registre indiquée par l’auteur du workflow. Il n’y a pas de réécriture automatique vers un miroir fremforge, ni, à ce jour, de liste d’autorisation intégrée pour la partie registre. Épinglez sur un condensat (docker://<registry>/<image>@sha256:…) plutôt que sur un tag modifiable. Depuis le 2026-10-24, l’analyse quotidienne d’Épinglage des workflows liste chaque référence docker:// qui n’est pas épinglée par condensat. Un hook pre-receive Forgejo ou une liste d’autorisation côté runner pour docker:// figure dans la feuille de route de durcissement ; en attendant, traitez une référence docker:// non épinglée comme un problème à relever en revue de code.

L’API des exécutions de workflow

Quatre routes existent et fonctionnent. Seules les deux premières sont documentées ailleurs, ce qui explique pourquoi les deux autres sont souvent signalées comme manquantes :

# stop a run that is queued or in progress
curl -X POST -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/runs/<run_id>/cancel
# -> 204, and the run's status becomes `cancelled`

Pourquoi l’annulation semble ne pas exister

Tous les indices vous en détournent : « je ne l’ai pas trouvée » est donc le résultat attendu, pas un manque de recherche :

• DELETE renvoie 405. La route accepte uniquement POST. DELETE .../cancel et les deux verbes sur .../runs/<id> (sans /cancel) renvoient tous 405.
• /actions/tasks/<id>/cancel renvoie 404. Les tâches ne sont pas des exécutions.
• La spécification OpenAPI de Forgejo n’est pas servie ici. /swagger.v1.json et toutes ses variantes renvoient 404 sur frem.sh : il n’y a donc nulle part où chercher la route.
• La spécification de l’API fremforge ne la décrit pas, et ne le peut pas. Elle documente les points de terminaison de cette plateforme, pas ceux de Forgejo ; cancel n’y apparaît que sous /orgs/{org}/billing/cancel, qui concerne les abonnements. Y chercher un moyen d’annuler une exécution mène au mauvais cancel.
• L’API fremforge répond 501. C’est la réponse par défaut pour les chemins /api/v1/* qui ne correspondent à aucun point de terminaison, et son message renvoie à la spécification OpenAPI de fremforge, c’est-à-dire à la spécification qui ne contient pas cette route.
• Les jetons ffp_* ne peuvent pas le faire du tout. Le proxy limité à l’organisation ne relaie que la route des journaux (voir plus bas) ; l’annulation et la relance exigent un PAT Forgejo ou un cookie de session.

Si vous annulez des exécutions à la main plus d’une fois

Ne l’automatisez pas par script : définissez plutôt un groupe de concurrence, pour que Forgejo annule lui-même l’exécution devenue obsolète :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Chaque push vers une branche remplace alors l’exécution précédente de cette branche. Sans risque pour les vérifications requises : les statuts sont propres à chaque commit, donc annuler l’exécution d’un commit plus ancien ne peut pas laisser en suspens les vérifications de la tête actuelle.

Une exécution annulée fait échouer ses vérifications. Le statut de commit de chaque job annulé se termine en failure avec la description Has been cancelled, que le job ait été en cours d’exécution ou encore en attente. Annuler une exécution sur le commit que vous essayez de fusionner fait donc passer ses vérifications requises au rouge, et une fusion automatique armée ne le fusionnera pas. Faites un push, ou POST .../rerun.

Activer et désactiver des workflows

Les boutons Disable workflow / Enable workflow de l’onglet Actions d’un dépôt ont des équivalents dans l’API. Les chemins, noms d’opérations et JSON sont ceux de Gitea : un client écrit pour l’API de Gitea fonctionne donc sans modification.

<workflow_id> est le nom de fichier du workflow, par ex. ci.yaml, tel qu’il apparaît dans .forgejo/workflows/ (ou .gitea/workflows/, .github/workflows/) sur la branche par défaut.

# switch a workflow off, then back on
curl -X PUT -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/workflows/ci.yaml/disable
# -> 204
curl -X PUT -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/workflows/ci.yaml/enable
# -> 204

# which workflows are switched off?
curl -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/workflows

{
  "workflows": [
    {
      "id": "ci.yaml",
      "name": "CI",
      "path": ".forgejo/workflows/ci.yaml",
      "state": "disabled_manually",
      "created_at": "2026-10-09T08:00:00Z",
      "updated_at": "2026-10-09T08:00:00Z",
      "url": "https://frem.sh/api/v1/repos/<owner>/<repo>/actions/workflows/ci.yaml",
      "html_url": "https://frem.sh/<owner>/<repo>/src/branch/main/.forgejo/workflows/ci.yaml",
      "badge_url": "https://frem.sh/<owner>/<repo>/badges/workflows/ci.yaml/badge.svg?branch=main"
    }
  ],
  "total_count": 1
}

• state vaut active ou disabled_manually. C’est le même réglage que celui que modifient les boutons : l’interface et l’API sont donc toujours d’accord.
• name est le name: du workflow, ou le nom de fichier s’il n’en a pas. created_at et updated_at correspondent tous deux à l’heure du dernier commit de la branche par défaut, comme sur Gitea, et non à l’historique propre du fichier.
• Désactiver et activer exige d’être administrateur du dépôt, comme pour les boutons. Un utilisateur disposant d’un accès en écriture reçoit 403. C’est plus strict que Gitea, qui l’autorise aux utilisateurs ayant l’accès en écriture.
• 404 pour un fichier qui n’est pas un workflow sur la branche par défaut. Une faute de frappe, un fichier sur une autre branche, ou un fichier qui n’est pas un .yml/.yaml du répertoire des workflows est refusé plutôt qu’enregistré.
• Un dépôt archivé répond 423 à l’activation et à la désactivation. Il reste lisible.
• Les deux appels sont idempotents. Désactiver un workflow déjà désactivé renvoie 204 et ne change rien.
• Ce que « désactivé » empêche : les exécutions déclenchées par des événements (push, pull request, etc.), les exécutions planifiées et les relances de ses exécutions existantes (POST .../rerun répond 422). Un déclenchement manuel (POST .../actions/workflows/<workflow_id>/dispatches) s’exécute toujours, exactement comme Run workflow dans l’interface.
• Les jetons ffp_* ne peuvent pas appeler ces routes. Il faut un PAT Forgejo (scope write:repository pour activer/désactiver) ou une session, comme pour l’annulation et la relance.

Récupérer les journaux de workflow par programme

L’interface web de Forgejo affiche les journaux des exécutions d’actions de manière interactive. Pour un accès par programme (notificateurs d’échec, scripts de débogage, exports de conformité, agents d’IA qui trient les échecs), il existe deux points de terminaison, selon le type de jeton dont vous disposez :

Avec un PAT Forgejo ou un cookie de session

curl -H "Authorization: token <forgejo-pat>" \
  https://frem.sh/api/v1/repos/<owner>/<repo>/actions/runs/<run_id>/logs

Renvoie du text/plain : tous les jobs de l’exécution concaténés, séparés par des en-têtes === job: <name> (status=<status>, attempt=<n>) ===. Le <run_id> est l’identifiant global que Forgejo renvoie depuis GET /api/v1/repos/<owner>/<repo>/actions/runs (le même identifiant que celui que l’interface web affiche dans /<owner>/<repo>/actions/runs/<n>). Le contrôle d’accès est la vérification standard de lecture du dépôt de Forgejo ; les comptes bots membres de la bonne organisation fonctionnent comme les utilisateurs humains.

Avec un PAT de l’API fremforge (ffp_*)

Si votre jeton commence par ffp_ (y compris les PAT créés dans l’interface d’administration, les jetons obtenus via POST /_app/api/v1/auth/token-exchange (échange OIDC) et les jetons délivrés par POST /_app/api/v1/oauth/token (client_credentials)), Forgejo ne le reconnaît pas. Utilisez plutôt le proxy de l’API fremforge :

curl -H "Authorization: Bearer <ffp_…>" \
  https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/actions/runs/<run_id>/logs

Même forme de réponse (text/plain, jobs concaténés, en-têtes entre eux). Scope requis : runners:read. Le proxy vérifie le rattachement du jeton à son organisation (le <org> de l’URL doit correspondre à l’organisation du jeton) avant de transmettre la requête à Forgejo avec un identifiant système ; cet identifiant système ne quitte jamais la plateforme, de sorte qu’un PAT client divulgué ne peut lire que les journaux de sa propre organisation.

Les deux points de terminaison renvoient le même corps : un appelant qui change de type d’authentification n’a qu’à modifier l’URL et l’en-tête Authorization.

Note sur la solution de contournement. Le proxy /api/v1/orgs/<org>/repos/<repo>/... est une passerelle temporaire en attendant que Forgejo prenne en charge en amont les jetons du domaine de l’API (ffp_*) sur son point de terminaison natif /api/v1/repos/<owner>/<repo>/.... Quand ce sera le cas, le proxy sera retiré et les jetons ffp_* utiliseront le même chemin que les PAT Forgejo. La forme de la réponse reste identique ; seule la forme de l’URL change.

Quand les journaux ne sont pas disponibles

• 404 : exécution introuvable, ou n’appartenant pas au dépôt de l’URL.
• 410 : les journaux ont été purgés par la tâche de nettoyage (exécutions d’actions plus anciennes que la durée de conservation).
• 502 : l’origine Forgejo est injoignable. Réessayez ; si le problème persiste, consultez status.frem.sh.

Voir aussi

• Runners CI : libellés de runners disponibles, runners fournis par vous, limites de concurrence
• Secrets : portées des secrets, rotation, OIDC comme alternative
• Compatibilité Marketplace : matrice de compatibilité des actions
• Fédération de jetons OIDC : déploiement cloud sans clé depuis les jobs
• Registre de paquets : publier des paquets depuis la CI