Every once in a while there is an outage on e.g. GitHub Actions, and I see a lot of influx of users on this blogpost. So before you start reading this, check the GitHub status page to see if there is an outage. If there is, you can wait until it is resolved. If there is not, you can continue reading this post to see if you can find the cause of your issue. Outages can always happen in any SaaS (Software as a Service) environment and keeping a large scale environment in a healthy state is not an easy task. So if you are experiencing an outage, be empathic with the engineers who are solving the issue 🤗.
Some default caveats that new GitHub Actions users run into is that their workflows are not being triggered or that the UI to do so is missing. In the beginning everyone starts with the
on: push trigger but there will come a time that you only want to execute some workflows on the default (main) branch. So you limit the
on: push trigger to that branch:
on: push: branches: - main
When you follow best practices you want to implement a Pull Request based process to prevent a single person from making changes to a repository. That means that you are making your changes to workflows in a feature branch and not in your main branch.
What happens next? See in the steps below. You can start at the top (scheduled run not starting) and then work your way down to the more specific examples. This also represents the order in which a lot of times these questions will occur.
I have ran into this myself and looked for 15 minutes before I saw what was wrong: check the location of your workflow file! When you are creating the first workflow in a repo, you might learn you have configured the wrong directory because the UI does not show the workflow file if it is in the wrong folder. That can be a hint 😉.
It needs to be stored in the following folder:
/.github/workflows/. And that folder is
workflows (plural) and not
When you add your first schedule for a daily run, you might be surprised that it does not start at the schedule you have set. You might scratch you head and wait for a couple of days, and nothing will happen.
on: schedule: - cron: '30 5,17 * * *'
The cause of this is that scheduled runs only trigger from the default branch (main). Several triggers behave this way, like a Pull Request (+Status) trigger, the issue / label / comment triggers, etc.
So if you have a schedule in your workflow and you are not on the default branch, the workflow will not start. This is a security measure to prevent someone from creating a workflow that runs on a schedule and then creating a pull request to a repository that has a scheduled workflow. The scheduled workflow would then run on the pull request and the attacker could do something malicious. This is a good thing, but it can be confusing when you are just starting out. The solution is to make sure that you are on the default branch when you create your scheduled workflow, so that means that you need to merge in your changes for it to start based on your schedule.
There are other reasons why a schedule might not trigger:
This is the common next step when the schedule does not start: you just add a workflow dispatch trigger to the workflow to trigger it manually. But since this is a new workflow that has not existed yet, the UI for it to trigger is not visible! This is the same as creating a new workflow file with this trigger in one go.
For a manual trigger, the UI is only available from the default branch. You can choose which branch to trigger the run from then, and have the inputs available from the default branch. But the file and the trigger has to be on the default branch for the UI to be visible.
You have two options to proceed and trigger the workflow:
You can trigger a workflow dispatch (as well as a repository dispatch for that matter) using the UI and even trigger it from a branch.
You need to make an (authenticated) call to the url for your workflow:
The workflows actually have an ID under the covers, but you can also use the filename, which is easier to read. So when the workflow is named
get-action-data.yml and it lives in the repo
rajbos/actions-marketplace it becomes this url:
https://api.github.com/repos/rajbos/actions-marketplace/actions/workflows/get-action-data.yml/dispatches. Include a JSON payload with the branch you are referencing in a “ref” property (see Postman screenshot below).
My tool of choice for this is Postman, because I can store my requests in it and it lives in its own window. This makes it super easy to navigate to and hit CTRL+ENTER to trigger the call, which is helpful when you are creating the workflows.
You can also use the GitHub CLI to trigger the workflow, by running the following command from the repository folder:
gh workflow run get-action-data.yml --ref rajbos-patch-1
Do not forget to include the
ref here if you want to run from a branch. Otherwise it will run from the default branch. Also be aware that this will execute in the context of the repo content that is ‘on GitHub, so not your local content!
The last option you have is to just trigger the workflow whenever someone pushed data into the repository. You can decide if that should happen on certain branches but the best tip here is to include a path filter (see the docs here).
on: push: branches: - main - my-test-branch paths: - 'src/**' - '.github/workflows/my-workflow-file.yml'
I often run the workflow on at least my test branch, but then only when the relevant files for that workflow have been edited. That usually is the workflow file itself and maybe certain source files in the repo that are used: whenever there is a change in those files: execute the workflow. This is especially helpful during the development of the workflow: if you push a change in it, it is a good change that you want to trigger the workflow 😄.
If you target a runner that you do not have access to (check the runner group permissions) or a label for which no runner exists, your job will hang around until the timeout of 24 hours has passed. Then it will get a timeout error and the job will be cancelled. Double check the label you are using (this typo in the screenshot always gets me!) and fix it, or check the permissions on the runner group.
Note that this all will not help when you have specific use cases you want to test, like when someone creates a comment, a pull request. There are other ways to deal with that, but that is for another post.