-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathgithub_actions.saas.txt
1050 lines (900 loc) · 60.2 KB
/
github_actions.saas.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
┏━━━━━━━━━━━━━━━━━━━━┓
┃ GITHUB_ACTIONS ┃
┗━━━━━━━━━━━━━━━━━━━━┛
ALTERNATIVES ==> # - GitHub actions (preferred):
# - run shell command or Docker container
# - plugins
# - triggered on push, PR, cron, API, any GitHub event
# - Windows, Mac, Linux
# - integrated with GitHub UI
# - 20 parallel jobs
# - great hardware
# - any background process/service (Docker container)
# - nice conditional logic
# - timeout 6 mins
# - fast fail
# - secret environment variables with GitHub repo UI settings
# - simple templating
# - Travis:
# - run shell command
# - no plugins
# - triggered on push, PR, cron, API
# - Windows, Mac, Linux
# - 5 parallel jobs
# - good hardware
# - specific built-in background process/service
# - nice conditional logic
# - timeout 50 mins
# - fast fail
# - secret environment variables with CLI
# - can re-use configuration file
# - auto-cancel several builds in a row
# - can run on multiple CPU architectures
GITHUB MAIN|WEBHOOKS|APPS
|API|CLI ==> #See other GitHub docs
┌─────────────┐
│ GENERAL │
└─────────────┘
LIMITS ==> # - 20 workflows in parallel at once per repository
# - 20 jobs in parallel at once for all repositories
# - 5 for MacOS
# - 40 for Pro, 60 for Team
# - 1000 API requests per hour per repository
# - for private, max 2000|3000|10000|50000 mins/month for free|pro|team|enterprise
# - can pay for extra mins
FORKED REPOSITORY ==> #Do not trigger any workflows:
# - unless enabled in web UI
# - not for private repositories
STATUS BADGE ==> #https://github.com/USER/REPO/workflows/WORKFLOW_NAME/badge.svg
STATS ==> #Can see stats (duration, failure rate, etc.) for all REPOs of an ORG by going in that ORG's Insights tab in UI
┌──────────┐
│ HOST │
└──────────┘
JOB.runs-on #Host OS among:
# - ubuntu-VERSION (latest|24.04|22.04[-arm])
# - *-arm does not work in private repos
# - macOS-VERSION (latest|15|14|13[-[x]large])
# - windows-VERSION (latest|2022|2019)
#Each JOB runs in own virtual machine instance.
#With custom runners, linux|windows|macos and x86|x64|ARM|ARM64|GPU instead
#"Large runners":
# - machines with more CPU|RAM|IO
# - team|enterprise only
# - billed per minute
# - not macOS
# - can autoscale
ENVVAR RUNNER_OS
CONTEXT.runner.os #'Linux|macOS|Windows'
SOFTWARE ==> #See https://help.github.com/en/articles/software-in-virtual-environments-for-github-actions
#and https://github.com/actions/virtual-environments for list of global dependencies but this includes:
# - Node.js 10.16.3
# - nvm on Mac, n on Linux|Windows
# - Bash, powershell
# - Git
# - gulp, grunt
# - yarn, bower
# - typescript
# - wget, curl
# - python, ruby, php, rust, go
ENVVAR HOME #Can be used
PRIVILEGES ==> #Passwordless sudo on Linux|Mac, no admin prompt for Windows
ENVVAR USER #'runner'
HARDWARE ==> #Hosted on Azure Standard_DS2_v2 for Windows|Linux:
# - 2 CPUs
# - 7GB RAM
# - 14GB SSD temporary storage
# - max I/O: 8000 IOPS and 8MB/s
# - max network: 200MB/s
#Hosted on MacStadium for Mac
JOB.container #Docker CONTAINER to run every STEP that uses STEP.run (not STEP.uses)
JOB.services.SERVICE_ID #Docker SERVICE, i.e. container started in background before all STEPs and closed after all.
CONTAINER|SERVICE.image #'IMAGE[:TAG]'
CONTAINER|SERVICE.ports #NUM_ARR to expose
CONTAINER|SERVICE.volumes #ARR of Docker volumes '[HOST_DIR:]CONTAINER_DIR'
CONTAINER|SERVICE.options #'--OPT ...' passed to docker create
CONTEXT.job.container|services.
SERVICE.id #CONTAINER|SERVICE's ID
CONTEXT.job.container|services.
network #CONTAINER|SERVICE's NETWORK ID
CONTEXT.job.container|services.
ports #OBJ
┌────────────┐
│ EVENTS │
└────────────┘
WORKFLOW.on #EVENT[_NAME][_ARR] triggering this workflow.
#Not recursive, i.e. workflow cannot trigger another workflow.
EVENT #{ EVENT_NAME: OPTS,... }
#OPTS:
# - types STR_ARR:
# - filter to only those sub-types
# - def to all sub-types unless indicated otherwise
# (push|pull_request only)
# (can use globbing including globstar and '!...')
# - branches[-ignore] 'LBRANCH'_ARR
# - tags[-ignore] 'TAG'_ARR
# - paths[-ignore] 'PATH'_ARR
# - only for those files
# - relative to root directory
# - no starting slash
EVENTS ==> #Same as Webhooks (see GitHub webhooks doc) except no:
# - webhook itself: ping, meta
# - GitHub app: github_app_authorization, installation*, marketplace_purchase
# - ORG|TEAMs: organization, org_block, membership, team[_add], sponsorship
# - alerts: *_alert, security_advisory
# - deploy_key, pull_request_review_thread, repository, repository_import, star, workflow_job
#`registry_package` is called `package`
#Also includes `workflow_call` (see below) and the following ones
pull_request_target #Like EVENT 'pull_request', but run inside the fork instead
# - i.e. access to SECRETVARs
schedule #Regular intervals
#OPTS_ARR:
# - cron '0-59 0-23 1-31 1-12 0-6'
# - hour minute dayOfMonth month dayOfWeek
# - each FIELD can be:
# - *: every
# - FIELD,...: and
# - FIELD-FIELD: from-to
# - NUM/NUM2: from NUM, then every NUM2
CONTEXT.github.event_name
ENVVAR GITHUB_EVENT_NAME
GITHUB.context.eventName #'EVENT_NAME' that triggered the WORKFLOW
CONTEXT.github.actor
ENVVAR GITHUB_ACTOR
GITHUB.context.actor #STR. Username or app that triggered the WORKFLOW
CONTEXT.github.event
GITHUB.context.payload #OBJ of the GitHub event payload
ENVVAR GITHUB_EVENT_PATH
CONTEXT.github.event_path #'PATH' to a JSON file containing CONTEXT.github.event
┌───────────────────┐
│ ORCHESTRATION │
└───────────────────┘
WORKFLOW #.github/workflows/WORKFLOW.y[a]ml
#There can be several per repository
WORKFLOW.name #'WORKFLOW_NAME'. Shown in Web UI.
#Def: filepath
CONTEXT.github.workflow
ENVVAR GITHUB_WORKFLOW
GITHUB.context.workflow #WORKFLOW.name
ENVVAR GITHUB_RUN_NUMBER
CONTEXT.github.run_number
GITHUB.context.runNumber #WORKFLOW ID inside the repository. Incremented from 1
WORKFLOW.run-name #Workflow run 'NAME'. Shown in Web UI.
ENVVAR GITHUB_RUN_ID
CONTEXT.github.run_id
GITHUB.context.runId #Workflow run unique ID.
WORKFLOW.jobs.JOB_ID #JOB. Run in parallel (unless JOB.needs)
#JOB_ID must be [:alnum:]-_
JOB.name #'JOB_NAME'. Displayed in web UI
JOB.needs #'JOB_ID'[_ARR]. Wait for those jobs first.
ENVVAR GITHUB_JOB
CONTEXT.github.action
GITHUB.context.job #'JOB_ID'
WORKFLOW[.jobs.JOB_ID.]
concurrency #STR. Same as concurrency.group STR
WORKFLOW[.jobs.JOB_ID.] #Ensure two workflows|jobs with different STR are run serially
concurrency.group #Def: 'ci-${{github.ref}}'
WORKFLOW[.jobs.JOB_ID.]
concurrency.cancel-in-progress #BOOL (def: false).
JOB.steps #STEP_ARR. Run serially.
STEP.id #'STEP_ID'
STEP.name #'STEP_NAME' (def: STEP.run|uses). Displayed in web UI
CONTEXT.job.status
CONTEXT.needs.JOB_ID.result #JOB's status among 'success', 'failure' and 'cancelled'
CONTEXT.steps.STEP_ID. #STEP's status among 'success', 'failure', 'cancelled' and 'skipped'
outcome|conclusion #If exit code non-0 but continue-on-error true, outcome is 'failure' but conclusion is 'success'
STEP.continue-on-error #BOOL. If false (def), exits whole JOB once any STEP.run|uses has exit code non-0
JOB|STEP.if #BOOL. If false, skips this JOB|STEP
#Usually used with ${{EXPR}} but ${{ }} can be omitted
#EXPR can use the additional following functions:
success|failure()->BOOL #Whether previous STEP failed
cancelled()->BOOL #Whether previous STEP was cancelled
always()->BOOL #Always returns true
SKIP GIT MESSAGE ==> #Skip CI when using git message with any of: '[skip ci]', '[no ci]', '[skip actions]' (or reverse order)
JOB|STEP.timeout-minutes #NUM (max|def: 6)
CANCEL|RE-RUN ==> #Done through web UI
┌─────────┐
│ CLI │
└─────────┘
GITHUB CLI ==> #See its doc
gh workflow list #
gh workflow|run list
--all|-a #Also show disabled WORKFLOWs
gh workflow enable|disable
WORKFLOW_ID|NAME #
gh workflow view #Show WORKFLOW:
WORKFLOW_ID|NAME|FILE # - ID, name, PATH
# - number of runs
# - recent runs status
--yaml|-y #Print WORKFLOW file
gh workflow run #Create a `workflow_dispatch` event
#Inputs are asked in prompt
--json #Get inputs from stdin
--field|-F VARR=VAL
--raw-field|-f VARR=STR #Specify inputs. Same syntax as gh api
gh workflow view|run --ref|-r #'TAG|BRANCH'
gh run delete RUN_ID #
gh run list #List RUNs
#Show: id, status, title, WORKFLOW, branch, event, duration date
--workflow|-w #'WORKFLOW_NAME'
--created #Creation 'DATE'
--event|-e #'EVENT'
--commit|-c #'COMMIT_ID'
--status|-s #STR. Status, among: queued|completed|in_progress|requested|waiting|action_required
#|cancelled|failure|neutral|skipped|stale|startup_failure|success|timed_out
gh run view RUN_ID #View RUN
#Show: id, name, WORKFLOW
#Show each JOB: id, name, status, duration
--job|-j #JOB_ID
--attempt|-a #UINT. Attempt number
--exit-status #Non-0 exit code if RUN failed
--verbose|-v #Print steps
--log #View logs
--log-failed #View logs of failed steps
gh run watch RUN_ID #Watch ongoing RUN
--interval|-i #INT. Refresh interval
--exit-status #Non-0 exit code if RUN failed
gh run cancel RUN_ID #Cancel ongoing RUN
gh run rerun RUN_ID #Repeat a RUN
--job|-j #JOB_ID
--failed #Only failed JOBs
--debug|-d #
┌────────────┐
│ MATRIX │
└────────────┘
JOB.strategy.matrix #Build matrix: repeat JOB once for each cartesian product
#OBJ:
# - VAR: ARR
# - include OBJ_ARR
# - either add additional VAR: VAL to a specific dimension
# (if VAR match)
# - or add a new dimension (otherwise)
# - exclude OBJ_ARR:
# - remove a dimension
# - all VAR: VAL of that dimension must be specified
CONTEXT.matrix.VAR #Access each dimension's values
CONTEXT.strategy.job-index #NUM of current dimension
CONTEXT.strategy.job-total #NUM of dimensions
JOB.strategy.fail-fast #BOOL (def: true). Cancels whole matrix if any JOB fails.
CONTEXT.strategy.fail-fast #
JOB.strategy.max-parallel #NUM (def: max available)
CONTEXT.strategy.max-parallel #
┌─────────────┐
│ COMMAND │
└─────────────┘
STEP.run #'SHELL_COMMAND'
#Can use several commands with newline separators.
STEP.shell #Shell to use with STEP.run:
WORKFLOW|JOB.defaults.run.shell # - 'bash': bash --noprofile --norc -eo pipefail ...
# - def on Unix
# - uses msys on Windows
# - 'sh': sh -e ...
# - not supported on Windows
# - 'cmd': %ComSpec% /D /E:ON /V:OFF /S /C "CALL "...""
# - def on Windows
# - only supported on Windows
# - 'pwsh': pwsh -command "& '...'"
# - core PowerShell
# - 'powershell': powershell -command "& '...'"
# - only supported on Windows
# - desktop PowerShell
# - 'python': python ...
# - 'COMMAND ...': custom
# - {0} is replaced with command
ACTION #Command to execute within a STEP, delivered as a plugin.
#Alternative to STEP.run
STEP.uses #ACTION_REF (see below)
STEP.with.INPUT_ID #STR (see ACTION.inputs.INPUT_ID)
STEP.with.entrypoint|args #Override ACTION.entrypoint|args (see below)
ENVVAR GITHUB_ACTION
CONTEXT.github.action
GITHUB.context.action #ACTION_ID
┌──────────┐
│ LOGS │
└──────────┘
LOGS ==> #Can be seen through web UI
ACTIONS_RUNNER_DEBUG=true #SECRETVAR. Add debug information about environment and orchestration
ACTIONS_STEP_DEBUG=true #SECRETVAR. Add debug information about each job itself (see ACTION_COMMAND debug below)
DOWNLOAD ARTIFACTS ==> #Done through web UI
MENU NOTIFICATION ==> #Not integrated with CCMenu yet.
#Can use https://cryptic-stream-13380.herokuapp.com/USER/REPO/WORKFLOW.yml for the moment
┌────────────┐
│ ENVVAR │
└────────────┘
WORKFLOW|JOB|STEP|CONTAINER.env #OBJ of ENVVARs
CONFVAR #Set in web UI, or in JOBS.vars.VAR
#Limits:
# - 100 per repository|environment, 1000 per organization
# - 64KB value
CONTEXT.vars.CONFVAR #Use it
SECRETVAR #Set in web UI, or in JOBS.secrets.VAR
#Cannot be used in forked repositories (except GITHUB_TOKEN)
#Limits:
# - 100 per repository|environment, 1000 per organization
# - 64KB value
CONTEXT.secrets.SECRETVAR #Use it
JOB.environment #'NAME'
#Sets of SECRETVARs, set in web UI
#When a JOB uses them, can require specific rules:
# - reviewers approval
# - fixed wait time
# - specific branches
ENVVAR GITHUB_WORKSPACE #'DIR' used as PWD for ACTIONs (e.g. '/home/runner/work/REPO/REPO')
CONTEXT.github.workspace #This will be most likely where repository root directory will be checked out by ACTIONs
#Cannot be used if inside an ACTION that uses USER Dockerfile instruction
ENVVAR RUNNER_WORKSPACE
CONTEXT.runner.workspace #Parent directory of GITHUB_WORKSPACE
STEP.working-directory
WORKFLOW|JOB.defaults.run.
working-directory #'PATH' for PWD
ENVVAR GITHUB_ACTIONS #Always 'true'
ENVVAR CI #Always 'true'
┌─────────┐
│ GIT │
└─────────┘
CONTEXT.github.repository
ENVVAR GITHUB_REPOSITORY #'USER/REPO'
GITHUB.context.repo #OBJ: owner 'USER', repo 'REPO'
#Uses either ENVVAR GITHUB_REPOSITORY or GitHub event payload.repository.owner|name
GITHUB.context.issue #Same but also adds OBJ.number NUM, which is GitHub event payload[.issue|pullRequest].number
CONTEXT.github.repository_owner #'USER'
CONTEXT.github.sha
ENVVAR GITHUB_SHA
GITHUB.context.sha #'HASH'
CONTEXT.github.ref
ENVVAR GITHUB_REF
GITHUB.context.ref #'refs/heads/BRANCH|TAG'
CONTEXT.github.head_ref
ENVVAR GITHUB_HEAD_REF #Same but for head if forked repository
CONTEXT.github.base_ref
ENVVAR GITHUB_BASE_REF #Same but for base repository if forked repository
ENVVAR GITHUB_SERVER_URL
GITHUB.context.serverUrl #Def: 'https://github.com'
ENVVAR GITHUB_API_URL
GITHUB.context.apiUrl #Def: 'https://api.github.com'
ENVVAR GITHUB_GRAPHQL_URL
GITHUB.context.graphqlUrl #Def: 'https://api.github.com/graphql'
actions/checkout #Action that does a git pull + git checkout
#Version 4.2.2
INPUTS.token #'TOKEN' (def: ENVVAR GITHUB_TOKEN)
INPUTS.ssh-key #STR. Alternative to INPUTS.token
INPUTS.ssh-known-hosts #STR.
INPUTS.ssh-strict #BOOL (def: true). Use StrictHostKeyChecking=yes and CheckHostIP=no SSH options
INPUTS.persist-credentials #BOOL (def: true). Use local git config for INPUTS.token|ssh-key if available
INPUTS.repository #'USER/REPO' (def: ENVVAR GITHUB_REPOSITORY)
INPUTS.ref #'COMMIT|BRANCH|TAG' (def: ENVVAR GITHUB_REF or 'refs/heads/master')
INPUTS.path #'PATH' where to checkout (def: '.')
INPUTS.clean #BOOL (def: true). Does git clean -ffdx + git reset --hard before git checkout
INPUTS.fetch-depth #NUM (def: 1, 0 for all). How many commits to fetch
INPUTS.fetch-tags #BOOL (def: false). Fetch tags even if fetch-depth 0
INPUTS.lfs #BOOL (def: false). Download Git-LFS files
INPUTS.submodules #BOOL (def: false) or 'recursive'. Checkout git submodules shallowly|deeply
INPUTS.set-safe-directory #BOOL (def: false): use git config safe.directory instead of overridding global gitconfig
INPUTS.sparse-checkout #'GLOB'_ARR. git sparse checkout, i.e. only checkout those files
INPUTS.sparse-checkout-cone-mode #BOOL (def: true)
INPUTS.filter #STR. git fetch --filter
OUTPUTS.ref #'BRANCH|TAG|COMMIT_SHA'
OUTPUTS.commit #'COMMIT_SHA'
GH CLI ==> #GitHub CLI available
actions/github-script #Fire an inline JavaScript async function, with access to the following variables:
# - github: GITHUB (see @actions/github)
# - context: GITHUB.context
# - core: CORE
# - io|exec|glob: @actions/io|exec|glob
# - require()
# - fetch: node-fetch
#Version 6.4.1
INPUTS.script #'JAVASCRIPT'. Function body
#Can use top-level await
INPUTS.github-token #'TOKEN'. Def: '${{github.token}}'
INPUTS.debug #BOOL (def: false). Sets OCORE KOPTS.log = console
INPUTS.user-agent #STR (def: 'actions/github-script'). Sets OCORE KOPTS.userAgent
INPUTS.retries #NUM of times to retry API requests, using OCORE KOPTS.request.retries
INPUTS.retry-exempt-status-codes #'NUM,...'. Do not retry those status codes, using OCORE KOPTS.retry.doNotRetry
INPUTS.result-encoding #'json' (def) or 'string'.
OUTPUTS.result #STR. Function return value.
#If INPUTS-result-encoding 'json', JSON.stringify(). If 'string', String()
octokit/request-action #Calls GitHub REST API endpoint
#Uses @octokit/action
#Version 2.4.0
INPUTS.* #REQ_OPTS (from @octokit/endpoint)
OUTPUTS.status|headers|data #RES.* (from @octokit/request)
octokit/graphql-action #Calls GitHub GraphQL API endpoint
#Uses @octokit/action
#Version 2.3.2
INPUTS.* #REQ_OPTS (from @octokit/graphql)
OUTPUTS.data #GRES (from @octokit/graphql)
ad-m/github-push-actions #Does a git push to current repo
#Does git push https://USER:GITHUB_TOKEN@github.com/REPOSITORY.git HEAD:BRANCH --follow-tags
#Version 0.8.0
INPUTS.github_token #'TOKEN' (def: CONTEXT.github.token)
INPUTS.repository #'USER/REPO' (def: current one)
INPUTS.branch #'BRANCH' (def: 'main')
INPUTS.force #BOOL (def: false). Does --force
INPUTS.force_with_lease #BOOL (def: false). Does --force-with-lease
INPUTS.atomic #BOOL (def: true). Does --atomic
INPUTS.tags #BOOL (def: false). Does --tags
INPUTS.directory #'PATH' (def: '.'). Current directory
INPUTS.ssh #BOOL (def: false). Use SSH
INPUTS.github_url #'URL' (def: CONTEXT.github.server_url)
┌─────────────────┐
│ PERMISSIONS │
└─────────────────┘
GITHUB_TOKEN #SECRETVAR with a GitHub token
CONTEXT.github.token #Scoped to current repository
#Can create another token if not enough permissions
#Is a IAT under the hood (see GitHub apps)
#WORKFLOW|JOB-specific
# - expires at end of it
WORKFLOW|JOB.permissions #Either:
# - { ACTION_PERMISSION: 'read|write|none', ... }
# - 'read-all|write-all'
#Permissions granted to GITHUB_TOKEN
#TYPE can be actions|checks|contents|...
#Default:
# - can be set by ORG
# - either:
# - permissive (def):
# - read on metadata, none on id-token
# - read|write on all other endpoints
# - restrictive:
# - read on metadata|contents|packages
# - none on all other endpoints
#Always read-only in forked REPOs
ACTION_PERMISSION #Different names than API_PERMISSION, APP_PERMISSION or TOKEN_PERMISSION
actions #
checks #
contents #
deployments #
id-token #
issues #
metadata #
packages #
pages #
pull-requests #
repository-projects #
security-events #
statuses #
@actions/github #Version 6.0.0
#Node only
getOctokit #@octokit/core OCORE, but:
('TOKEN'[, KOPTS][, ...PLUGIN]) # - authenticated with TOKEN
->GITHUB # - handles ENVVAR GITHUB_API_URL
# - uses @actions/http-client, i.e. handle ENVVAR HTTP[S]|NO_PROXY
#Meant to be used inside Workflow files or GitHub actions
context #GITHUB.context
@octokit/action #Version 7.0.1
#Node only
Octokit #Octokit to use inside GitHub actions
#Forwards to @octokit/core, but:
# - uses @octokit/auth-action, i.e. automatically authenticated
# - handles ENVVAR GITHUB_API_URL and HTTP[S]_PROXY
#Meant to be used inside GitHub actions
@octokit/auth-action #Version 5.1.1
#Node/Deno/browsers
createActionAuth()->IAPP #Like @octokit/auth-token (see GitHub app) but using ENVVAR GITHUB_TOKEN
#Fails unless ENVVAR GITHUB_ACTION
┌───────────────┐
│ TEMPLATES │
└───────────────┘
${{EXPR}} #Template variable to use anywhere.
#Can use:
# - 'STR'|"STR"|BOOL|NUM|null
# - operators: () [] ! && || < <= > >= == !=
# - does type coercion (STR -> BOOL|NUM, BOOL -> 0|1|'BOOL', NUM -> 'NUM', null -> 0|'')
# - VARR from CONTEXT.**
# - can use ARR.*...
# - can use either OBJ.VAR or OBJ['VAR']
# - VAR must be [:alnum:]-_
# - one of the FUNC() below
CONTEXT #Values that can be used as VARR inside ${{EXPR}}
contains(STR, STR2)->BOOL #Like STR.includes(), case-insensitive
contains(ARR, VAL)->BOOL #Like ARR.includes(), case-insensitive
startsWith(STR, STR2)->BOOL #Like STR.startsWith(), case-insensitive
endsWith(STR, STR2)->BOOL #Like STR.endsWith(), case-insensitive
format(STR, VAL...)->STR #Replace {NUM} placeholders in STR. {{}} for escaping {}
join(STR[_ARR], STR2)->STR #Like [...STR_ARR, STR2].join(' ')
toJson(VAL)->STR #Like VAL.toJson()
fromJson(STR)->VAL #Like JSON.parse()
hashFiles('GLOB')->'HASH' #
┌───────────────┐
│ ARTIFACTS │
└───────────────┘
ARTIFACT ==> #*.zip archive that can be downloaded either:
# - in-between jobs of a build
# - in the UI of the build that uploaded it
#File permissions not kept, but can use tar to fix that
#Cannot be downloaded in future builds though.
#Done by the underlying RUNNER (using RUNS.plugin 'upload|download')
#Max 500 per workflow run
actions/artifact #Underlying library, which can be used in Node.js actions
#Not documented yet
actions/upload-artifact #Action that uploads files as an artifact
#Version 4.6.2
INPUTS.path #'FILE|DIR'[_ARR]
#Can use GLOB, ~
INPUTS.include-hidden-files #BOOL. If false (def), ignore dotfiles
INPUTS.name #STR (def: 'artifact'). Artifact name
INPUTS.retention-days #NUM of days to keep
#Min 1, max 90
#Def: 0, i.e. 90 but can be configured in settings
#Restarted on each new commit for PRs
INPUTS.compression-level #NUM (def: 6). Zlib compression level
INPUTS.if-no-files-found #If INPUTS.path empty: 'ignore', 'warn' (def), 'error'
INPUTS.overwrite #BOOL. If INPUTS.path already exists:
# - false (def): error
# - true: delete it first
#In either case:
# - always errors if was uploaded by a previous JOB, as opposed to previous RUN
# - i.e. in a matrix, INPUTS.name must include combination id
OUTPUTS.artifact-id #'ARTIFACT_ID'
OUTPUTS.artifact-url #'https://github.com/USER/REPO/actions/runs/RUN_ID/artifacts/ARTIFACT_ID'
OUTPUTS.artifact-digest #'ARTIFACT_HASH'
#On mismatch during actions/download-artifact, fails
ENVVAR ACTIONS_ARTIFACT_ #NUM of parallel uploads
UPLOAD_CONCURRENCY #Def|max: max(16 * NUM of CPUs, 300)
ENVVAR ACTIONS_ARTIFACT_
UPLOAD_TIMEOUT_MS #NUM (in ms, def: 5m). Upload timeout
actions/upload-artifact/merge #Action that merge multiple artifacts into a single one
INPUT.pattern #'GLOB'
INPUTS.name #STR (def: 'merged-artifacts'). Artifact name
INPUTS.delete-merged #BOOL (def: false). Delete artifacts after they have been merged
INPUTS.separate-directories #BOOL (def: false). Create subdirectories instead of using root
INPUTS.
retention-days|compression-level
OUTPUTS.artifact-id|artifact-url #Same as above
actions/download-artifact #Action that download an artifact files
#Version 4.2.1
INPUTS.path #'PATH' (def: '.')
#Can use ~
INPUTS.name #STR (def: all). Artifact name
INPUTS.pattern #Same as 'REGEXP'
INPUTS.merge-multiple #BOOL. If:
# - false (def): one subdirectory per artifact
# - true: merge all artifacts into same top directory
INPUTS.repository #'USER/REPO' (def: current)
INPUTS.run-id #'RUN_ID' (def: current)
INPUTS.github-token #'GITHUB_TOKEN'. Required with INPUTS.repository|run-id
OUTPUTS.download-path #'FILE|DIR'
gh run download [RUN_ID] #Download artifacts
#Def RUN_ID: interactive
--dir|-D #'DIR' (def: '.')
--name|-n #'NAME'
--pattern|-p #'GLOB'
gh attestation verify #Verify artifact integrity
#Not documented yet
gh attestation download #Download artifact integrity to verify it offline
#Not documented yet
┌───────────┐
│ CACHE │
└───────────┘
CACHING ==> #Uses internal GitHub actions REST API to cache files as a key-value store
#Scoped to each repository
# - scoped to branch too, but `main` and parent branch (including in PRs) caches are available too
# - not scoped to each matrix dimension, so need to namespace KEY with it
#Cache eviction:
# - rotated on max 10GB per repository, based on atime
# - also removed after 7 days if not accessed
#Can be accessed by anyone who can create PRs, i.e. should not contain confidential information
#Can be manipulated from the UI too
actions/cache #Combines actions/cache/save and actions/cache/restore (run on `post`)
#Version 4.0.2
INPUTS.path|key|restore-keys
|upload-chunk-size
|enableCrossOsArchive
|fail-on-cache-miss|lookup-only
INPUTS.save-always #BOOL. If false (def), only run actions/cache/restore if JOB succeeded
OUTPUTS.cache-hit #Same as below
actions/cache/save #Save local FILE|DIR to remote cache
#Usually at end of workflow run
INPUTS.key #'KEY'. Archive ID
#Max 512 chars. Cannot contain comma
#Example: '${{matrix.os}}-NAMESPACE-${{hashFiles('GLOB')}}'
INPUTS.path #'PATH' of the FILE|DIR to save. Can start with ~
#Can be several paths, newline-delimited
#Can contain GLOB
#Example: ~/.cache/pip
INPUTS.upload-chunk-size #NUM (in bytes)
#Multipart upload chunk size
INPUTS.enableCrossOsArchive #BOOL (def: false). Allow restoring on a different OS
actions/cache/restore #Restore local FILE|DIR from remote cache
#Usually at start of workflow run
INPUTS.key #Exact 'KEY'
INPUTS.restore-keys #Start with 'KEY'
#Can be several 'KEY', newline-delimited
#Lower priority than INPUTS.key
#If several matches, pick only the last created one
#Example: '${{matrix.os}}-NAMESPACE-'
INPUTS.path #'FILE|DIR|GLOB'
INPUTS.fail-on-cache-miss #BOOL (def: false). Fail if no cache found
INPUTS.lookup-only #BOOL (def: false). Do not download cache, only check it
ENVVAR
SEGMENT_DOWNLOAD_TIMEOUT_MINS #NUM (def: 10, in mins). Timeout when downloading each 1GB chunk
OUTPUTS.cache-hit #'true|false'. Whether cache found through INPUTS.key (not INPUTS.restore-keys)
OUTPUTS.cache-primary-key #Same as INPUTS.key
OUTPUTS.cache-matched-key #Same as INPUTS.key or INPUTS.restore-keys, whichever matched
gh cache list #List cached files
--key|-k #Starts with 'KEY'
--ref|-r #Git ref, e.g. 'refs/heads/BRANCH' or 'refs/pull/NUM/merge'
gh cache delete CACHE_ID|KEY #Delete cached file
--all|-a #
--succeed-on-no-caches #Unless set, exit code 1 if no cache
┌───────────────────┐
│ CACHE HELPERS │
└───────────────────┘
@actions/tool-cache #Contains:
# - helpers to do HTTP download and tar|zip|7z extraction using a standardized temporary directory
# - helpers to cache files locally using a standardized cache directory
#Version 1.1.2
USERSDIR #Is:
# - Linux: /home
# - Mac: /Users
# - Windows: ENVVAR USERPROFILE (or C:\)
CACHEBASEDIR #Either:
CONTEXT.runner.tool_cache # - ENVVAR RUNNER_TOOL_CACHE (e.g. /opt/hostedtoolcache)
# - USERS_DIR/actions/cache
CACHEDIR #CACHEBASEDIR/NAME/VERSION/ARCH
# - NAME is any project name
# - VERSION is normalized with SEMVER.clean() (see its doc)
# - ARCH def is OS.arch()
#Created by cacheFile|cacheDir() if does not exist
cacheFile('PATH', 'PATH2', #Copy 'PATH' to CACHEDIR/PATH2
'NAME', 'VERSION'[, 'ARCH']) #Create CACHEDIR if does not exist
->PROMISE_'CACHEDIR' #Once done, write an empty file at CACHEDIR.complete
# - this is checked by find[AllVersions]() to exclude still ongoing copies
cacheDir('DIR',
'NAME', 'VERSION'[, 'ARCH'])
->PROMISE_'CACHEDIR' #Same with a 'DIR' recursively
findAllVersions('NAME'[, 'ARCH'])
->'VERSION'_ARR #Find all 'VERSION' from CACHEBASEDIR/NAME/*. Uses sync I/O
find('NAME', 'VERSION_RANGE'
[', ARCH'])->'CACHEDIR' #Find the 'CACHEDIR' of a specific NAME+VERSION_RANGE+ARCH. Uses sync I/O
TMPBASEDIR #Either:
CONTEXT.runner.temp # - ENVVAR RUNNER_TEMP (e.g. /home/runner/work/_temp)
# - USERS_DIR/actions/temp
TMPCOREDIR #TMPBASEDIR/UUIDv4
#Created by downloadTool|extract*() if does not exist
downloadTool('URL') #Download URL and stream it to TMPCOREDIR
->PROMISE_TMPCOREDIR #Throw HTTPError if status not 200. Throw other ERROR if other issues.
extractTar
( 'PATH'[, 'TMPCOREDIR'][, STR]) #Extract tar archive to temporary directory, using 'tar' binary
->PROMISE_TMPCOREDIR #STR def is tar flags (def: 'xz')
extractZip('PATH'[, 'PATH2'])
->PROMISE_PATH2 #Same with zip using 'unzip' binary (on Unix) or Powershell Power.IO.Compression.FileSystem (on Windows)
extract7z('PATH'[, 'PATH2']
[, '7Z_BIN_PATH']) #Same with 7z using '7z' binary, which is shipped as *.exe with the code but can be '7Z_BIN_PATH' too
->PROMISE_PATH2 #Windows only
┌───────────────────────┐
│ REUSABLE WORKFLOW │
└───────────────────────┘
JOB.uses #'USER/REPO/.github/workflows/FILENAME.yml@TAG'
#Use a reusable workflow
JOB.with.INPUT_ID #STR. Like STEP.with.INPUT_ID but for reusable workflows.
JOB.secrets.VAR #Sets SECRETVAR
JOB.secrets.inherit #Inherit child secrets, but not grandchild
workflow_call #EVENT_NAME. Declare that WORKFLOW can be used as a reusable workflow
#OPTS:
# - inputs.INPUT_ID INPUT
# - secrets OBJ
┌─────────────────┐
│ ACTION MAIN │
└─────────────────┘
ACTION_REF #'[USER/REPO][/PATH]@REF'
#Path to DIR with action.yml
#Def USER/REPO: current one
#Def PATH: /
#REF can be:
# - BRANCH
# - VERSION (GitHub release): vX (X.*.*) or vX.Y (X.Y.*)
# - COMMIT
#Only public repository
#If not meant to be published, recommend to put in .github/actions/ACTION_ID
#Can also be 'docker://[HOST/]IMAGE[:TAG]' (public Docker image)
action.yml #ACTION.* file
ACTION.name #'ACTION_NAME'. Displayed in web UI
ACTION.description #STR
ACTION.author #STR
ACTION.runs #RUNS. Main command execution
RUNS.using #Either:
# - 'node20' (NODE_RUNS): run in child process
# - 'docker' (DOCKER_RUNS)
# - only on Linux hosts
# - slower than 'node*'
# - 'composite' (SHELL_RUNS): shell commands
NODE_RUNS.main #'PATH' to file to execute
NODE_RUNS.pre|post #'PATH' to file to execute at the start|end of the JOB
#Whether it was successful or not, but can use NODE_RUNS.pre|post-if 'success|failure()' to restrict
NODE_RUNS.pre|post-if #Like JOB|STEP.if but for NODE_RUNS.pre|post
DOCKER_RUNS.image #'PATH', 'docker://[HOST/]IMAGE[:TAG]' or 'USER/REPO' to Dockerfile
SHELL_RUNS.steps #STEP_ARR
#Cannot use STEP.uses|with|continue-on-error
RUNS.plugin #'PLUGIN'. Action that is done at the RUNNER-level
#Available: 'download|upload' (see below)
@actions/toolkit #Monorepo with @actions/core|io|exec|github|tool-cache
@actions/core #CORE
#Version 1.2.0
@actions/io #Filesystem utilities. Prefer alternative packages since they are not as good:
# - cp|copyFile|cpDirRecursive(...): like CP-FILE|CPY (see their docs)
# - mv(...): like MV-FILE (see its docs)
# - rmRF(...): like RIMRAF|DEL (see their docs)
# - mkdirP(...): like MAKE-DIR (see its docs)
# - which(...): like NODE-WHICH (see its docs)
#Version 1.0.1
@actions/exec #Like EXECA but not as good
#Version 1.0.2
@actions/glob #Globbing library
┌─────────────────┐
│ MARKETPLACE │
└─────────────────┘
MARKETPLACE ==> #Where users search for Actions
#Cannot purchase, only shows instructions on how to install
#See more docs in GitHub apps doc
PUBLISHING ==> #Automatic on new GitHub release
#Must use the UI option to release on marketplace
VERIFICATION ==> #"Verified account" badge|filter
#Must email partnerships@github.com
#Required if either:
# - private REPO
# - multiple ACTIONs
# - has WORKFLOW files itself
# - actions.yml not in root
CATEGORIES ==> #Primary/secondary categories, choosen in UI while publishing
ACTION.branding #BRANDING. Badge shown MARKETPLACE
#Can preview at https://create-github-action.now.sh
BRANDING.color #'white|gray-dark|yellow|blue|green|orange|red|purple'
BRANDING.icon #STR (feathers library icon name)
┌───────────────────┐
│ ACTION STATUS │
└───────────────────┘
STATUS ==> #'success' if exit code 0, 'failure' otherwise
CORE.setFailed(STR) #Sets process.exitCode = 1 + CORE.error(STR)
#Should wrap top-level function with it, using error.message as STR
┌────────────────┐
│ ACTION IPC │
└────────────────┘
ACTION_COMMAND #IPC mechanism between ACTION and RUNNER
({ATTR: STR,...}[, STR2]) #Printed to stdout as ::ACTION_COMMAND [ATTR=STR],...::[STR2]
#Must percent-encode:
# - STR|STR2: \r \n %
# - STR: ] ;
#ACTION_COMMAND|ATTR are case-insensitive
#Must use OS-specific newline.
ACTION_COMMAND stop-commands #Pauses IPC mechanism.
('ACTION_COMMAND2') #Should be done before printing user-supplied string.
#Resume with ACTION_COMMAND2
┌───────────────────────┐
│ ACTION I/O DOCKER │
└───────────────────────┘
DOCKER_RUNS.entrypoint #'SHELL_COMMAND'. Sets|overrides ACTION's Dockerfile ENTRYPOINT, i.e. main command to run.
DOCKER_RUNS.args #STR. Sets|overrides Dockerfile CMD, i.e. arguments to ENTRYPOINT.
┌───────────────────────┐
│ ACTION I/O INPUTS │
└───────────────────────┘
ACTION.inputs.INPUT_ID #INPUT. ENVVAR used as arguments
#INPUT_ID is case-sensitive when matching STEP.with
#It is passed as ENVVAR INPUT_{INPUT_ID.toUpperCase()}=STR
#INPUT_ID must be [:alnum:]-_
INPUT.required #BOOL (def: false)
INPUT.default #STR
INPUT.description #STR
CONTEXT.inputs.INPUT_ID #Available with EVENT_NAME workflow_call|workflow_dispatch
#With workflow_dispatch: shown as UI input fields
INPUT.type #Only for EVENT_NAME workflow_dispatch
#STR among 'choice|boolean|number|string|environment'
INPUT.choices #STR_ARR. Only if INPUT.type 'choice'
CORE.getInput('INPUT_ID'[, OPTS]) #Retrieve ENVVAR INPUT_{INPUT_ID.toUpperCase()}
->STR #Trims value
#If OPTS.required true (def: false), throw if STR empty string (before trimming)
┌────────────────────────┐
│ ACTION I/O OUTPUTS │
└────────────────────────┘
ACTION.outputs.OUTPUT_ID #OUTPUT.
#OUTPUT_ID must be [:alnum:]-_ (lowercase-only)
OUTPUT.description #STR
CORE.setOutput('OUTPUT_ID', STR) #Set OUTPUT
ENVVAR GITHUB_OUTPUT #Newline-separated file containing OUTPUT=VAL
CONTEXT.steps.STEP_ID.outputs.VAR #Get OUTPUT of previous STEPs' ACTIONs
CONTEXT.needs.JOB_ID.outputs.VAR #Can only be used in the following STEPs
┌────────────────────────┐
│ ACTION I/O ENVVARS │
└────────────────────────┘
RUNS.env #OBJ of ENVVARs
ENVVAR GITHUB_ENV #Newline-separated file containing ENVVAR=VAL to set in parent process and following STEPs (not current one)
#Cannot set ENVVAR NODE_OPTIONS
CORE.exportVariable('VAR', 'VAL') #Add to GITHUB_ENV + set process.env.VAR
ENVVAR GITHUB_PATH #Newline-separted file where each line is a DIR to prepend to PATH ENVVAR
#in parent process and following STEPs (not current one)
CORE.addPath('DIR') #Add to GITHUB_PATH + set process.env.PATH (not process.env.Path)
ENVVAR GITHUB_STEP_SUMMARY #'PATH' to a Markdown file shown in summary
CORE.summary.* #Helper functions to set GITHUB_STEP_SUMMARY
CORE.saveState('VAR', 'VAL') #Set ENVVAR STATE_VAR=VAL. Only within current action
#Meant for communication between NODE_RUNS.main and NODE_RUNS.post
CORE.getState('VAR')->'VAL' #Retrieve ENVVAR STATE_VAR ('' if not set)
┌─────────────────┐
│ ACTION LOGS │
└─────────────────┘
LOG_LEVEL #debug|warning|notice|error
ACTION_COMMAND LOG_LEVEL(OBJ, STR)#Print message
#OBJ (all optional): file 'FILENAME', line NUM, col NUM
CORE.LOG_LEVEL(STR) #If debug, only printed if SECRETVAR ACTIONS_STEP_DEBUG is 'true'
ACTION_COMMAND group('GROUP')
CORE.startGroup('GROUP') #Start foldable group
ACTION_COMMAND endgroup()
CORE.endGroup() #Stop last foldable group
CORE.group
('GROUP', FUNC()[->PROMISE])
->PROMISE #Call ACTION_COMMAND group|endgroup before|after FUNC()
ACTION_COMMAND add-mask(STR) #Replace any STR in logs by *
CORE.setSecret(STR) #Meant for confidential values
#If STR is multiline, should be called on each line.
ACTION_COMMAND add-matcher #Creates GitHub annotations in Action logs, by looking for specific RegExps
({}, 'PATH.json') #For example use the highlight warning|errors (such as linting|validation)
#PATH.json is OBJ: problemMatcher OBJ_ARR:
# - owner 'NAME': project name
# - pattern OBJ_ARR:
# - how to detect and parse log lines to GitHub annotations
# - when several OBJ, read|parse logs with each of them in order:
# - create a single GitHub annotation for all of them
# - if OBJ.loop true, create several annotations, by repeating REGEXP until it fails
# - OBJ:
# - regexp 'REGEXP': each NUM below represents a parens group inside REGEXP
# - message NUM
# - code NUM: code sample
# - severity NUM: 'warning'|'error'
# - file|line|column NUM: error location
# - loop BOOL (def: false)
ACTION_COMMAND remove-matcher
({owner STR}) #
┌────────────┐
│ RUNNER │
└────────────┘
RUNNER #Underlying server that executes WORKFLOW files.
#By default hosted on GitHub, but can be customized.
#Code at https://github.com/actions/runner