Skip to content

feat: check job permissions and warn if not enough #1410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inimaz wants to merge 5 commits into
base: main
Choose a base branch
from
+139 −0
Open

feat: check job permissions and warn if not enough #1410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0345bc3
feat: check job permissions and warn if not enough
inigoimaz Jul 10, 2026
9e80c8a
chore: adding changelog file 1410.added.md [dependabot-skip]
pyansys-ci-bot Jul 10, 2026
c3086da
fix: content check instead of commits
inigoimaz Jul 10, 2026
d345268
Merge branch 'feat/check-permissions' of github.com:ansys/actions int…
inigoimaz Jul 10, 2026
2f4d5bd
fix: split attestations : write from id-token: write
inigoimaz Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 131 additions & 0 deletions _check-github-permissions/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Copyright (C) 2022 - 2026 Synopsys, Inc. and ANSYS, Inc. All rights reserved.
# SPDX-License-Identifier: MIT
#
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

name: |
Check GitHub permissions action

description: |
Verifies that the ``GITHUB_TOKEN`` has the required permissions to run an
action. Emits a ``::warning::`` for each missing permission without stopping
the job.

Supported permission scopes: ``contents``, ``pull-requests``, ``issues``,
``actions``, ``packages``, ``pages``, ``id-token``, and ``attestations``.

.. note::

Write-level permissions (e.g. ``contents: write``) are verified with a
read probe. If the probe succeeds, read access is confirmed but write
access cannot be guaranteed without a side-effecting call.

.. important::

The ``id-token`` and ``attestations`` scopes are verified by checking for
the ``ACTIONS_ID_TOKEN_REQUEST_URL`` environment variable rather than an
API call.

inputs:

# Required inputs

permissions:
description: |
Comma-separated list of required GitHub token permissions in
``scope: level`` format. For example:
``"contents: read, pull-requests: write"``.
required: true
type: string

# Optional inputs

token:
description: |
GitHub token to use for permission verification.
required: false
default: ${{ github.token }}
type: string

runs:
using: "composite"
steps:

- name: "Check GitHub permissions"
shell: bash
env:
GH_TOKEN: ${{ inputs.token }}
PERMISSIONS: ${{ inputs.permissions }}
REPO: ${{ github.repository }}
run: |
probe() {
local endpoint="$1"
local err
if ! err=$(gh api "${endpoint}" 2>&1 >/dev/null); then
echo "${err}" | grep -qiE "HTTP 403|403|forbidden|not accessible by integration|insufficient permission" && return 1
fi
return 0
}

IFS=',' read -ra PERMS <<< "${PERMISSIONS}"

@klmcadams klmcadams Jul 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To condense the repeating echo statements, could you do something like this? I understand if the case structure is more readable though

# Define the endpoints and suggested permissions as associative arrays
declare -A endpoints=(
  [contents]="repos/${REPO}/contents/"
  [pull-requests]="repos/${REPO}/pulls?per_page=1"
  [issues]="repos/${REPO}/issues?per_page=1"
  [actions]="repos/${REPO}/actions/runs?per_page=1"
  [packages]="repos/${REPO}/packages?package_type=container"
  [pages]="repos/${REPO}/pages"
)

declare -A suggestions=(
  [contents]="contents: read"
  [pull-requests]="pull-requests: read"
  [issues]="issues: read"
  [actions]="actions: read"
  [packages]="packages: read"
  [pages]="pages: read"
)

IFS=',' read -ra PERMS <<< "${PERMISSIONS}"
for perm in "${PERMS[@]}"; do
  perm=$(echo "${perm}" | xargs)
  scope=$(echo "${perm}" | cut -d: -f1 | xargs)

  if [[ -n "${endpoints[$scope]}" ]]; then
    probe "${endpoints[$scope]}" || \
      echo "::warning::Missing permission '${perm}'. Add '${suggestions[$scope]}' (or higher) to your workflow's permissions block."
  elif [[ "$scope" == "id-token" ]]; then
    [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] && \
      echo "::warning::Missing permission '${perm}'. Add 'id-token: write' to your workflow's permissions block."
  elif [[ "$scope" == "attestations" ]]; then
    [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] && \
      echo "::warning::Missing permission '${perm}'. Add 'attestations: write' and 'id-token: write' to your workflow's permissions block."
  else
    echo "::notice::Unknown permission scope '${scope}' — skipping verification."
  fi
done

for perm in "${PERMS[@]}"; do
perm=$(echo "${perm}" | xargs)
scope=$(echo "${perm}" | cut -d: -f1 | xargs)

case "${scope}" in
contents)
probe "repos/${REPO}/contents/" || \
echo "::warning::Missing permission '${perm}'. Add 'contents: read' (or higher) to your workflow's permissions block."

@moe-ad moe-ad Jul 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wondering how easy it would be to print an exact warning message i.e. instead of "contents: read (or higher)", "contents: write" is printed (which we could detect from inputs.permissions).

@inimaz inimaz Jul 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed! The issue is that we cannot distinguish for now read and write permissions. Since normally read is a prerequisite for write I only test read things in the probe() function, like this I do not write anything. For future versions we can try to find write actions that are harmless per each permission?

@moe-ad moe-ad Jul 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should change the wording of the warning message then. For instance, we can add a link pointing to the documentation of the action (which already contains information about the minimum permissions required).

;;
pull-requests)
probe "repos/${REPO}/pulls?per_page=1" || \
echo "::warning::Missing permission '${perm}'. Add 'pull-requests: read' (or higher) to your workflow's permissions block."
;;
issues)
probe "repos/${REPO}/issues?per_page=1" || \
echo "::warning::Missing permission '${perm}'. Add 'issues: read' (or higher) to your workflow's permissions block."
;;
actions)
probe "repos/${REPO}/actions/runs?per_page=1" || \
echo "::warning::Missing permission '${perm}'. Add 'actions: read' (or higher) to your workflow's permissions block."
;;
packages)
probe "repos/${REPO}/packages?package_type=container" || \
echo "::warning::Missing permission '${perm}'. Add 'packages: read' (or higher) to your workflow's permissions block."
;;
pages)
probe "repos/${REPO}/pages" || \
echo "::warning::Missing permission '${perm}'. Add 'pages: read' (or higher) to your workflow's permissions block."
;;
id-token)
if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
echo "::warning::Missing permission '${perm}'. Add 'id-token: write' to your workflow's permissions block."
fi
;;
attestations)
if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
echo "::warning::Missing permission '${perm}'. Add 'attestations: write' and 'id-token: write' to your workflow's permissions block."
fi
;;
*)
echo "::notice::Unknown permission scope '${scope}' — skipping verification."
;;

@moe-ad moe-ad Jul 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If any of the checks fail, we can fail the action early by emitting exit code 1, since the action won't work correctly anyways if the permissions aren't set properly.

@inimaz inimaz Jul 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure!
Up to us to decide. Maybe there are some actions that work with a subset of the permissions?
For example I was using the doc-deploy-dev without the pull-requests:write permission and it was working fine on its own, until I added the doc-deploy-pr that creates comments on prs --> then doc-deploy-dev needs the permission to comment that on a pr to close previously-opened comments .

TLDR: some jobs still work without the permissions because they do just a subset of all the actions, should we fail them and tell them to add the proper permission?

@moe-ad moe-ad Jul 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on your explanation in the other comment, until we are able to test write permissions, we cannot fail all workflows.

It can however be done for workflows that require only read permissions, so maybe we do that first and re-iterate in the future like you suggested.

On the doc-deploy-dev case, your observation is correct. We will have to treat it as a special case. For example, we can split this step into multiple steps: the first checks if there is something to be removed and sets a flag, the next then checks for write permissions, and the last does the actually removal. That way, we are able to check for write permissions only when needed. You see what I mean?
But of course, that still depends on being able to test write permissions in the first place.

esac
done
7 changes: 7 additions & 0 deletions doc-deploy-dev/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,12 @@ runs:
using: "composite"
steps:

- name: "Check GitHub permissions"
uses: ansys/actions/_check-github-permissions@main
with:
permissions: "contents: write, pull-requests: write"
token: ${{ inputs.token }}

- uses: ansys/actions/_logging@main
with:
level: "INFO"
Expand All @@ -162,6 +168,7 @@ runs:
repository: ${{ steps.get-repository-name.outputs.REPOSITORY }}
token: ${{ inputs.token }} # zizmor: ignore[artipacked] , credentials need to be persisted in this case


- name: "Ensure that the desired branch exists"
shell: bash
env:
Expand Down
1 change: 1 addition & 0 deletions doc/source/changelog/1410.added.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Check job permissions and warn if not enough
Loading