Skip to content

Commit

Permalink
Merge pull request #70 from actions/v2-docs-improvements
Browse files Browse the repository at this point in the history
Update README for `v2`
  • Loading branch information
JamesMGreene authored Jul 10, 2023
2 parents 84bb4cd + 07f501f commit 3138c05
Showing 1 changed file with 33 additions and 29 deletions.
62 changes: 33 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

A composite Action for packaging and uploading artifact that can be deployed to [GitHub Pages][pages].

# Scope
## Scope

⚠️ Official support for building Pages with Actions is in public beta at the moment.

# Usage
## Usage

See [action.yml](action.yml)

<!-- TODO: document custom workflow -->

# Artifact validation
## Artifact validation

While using this action is optional, we highly recommend it since it takes care of producing (mostly) valid artifacts.

Expand All @@ -25,8 +25,9 @@ The [`tar` file][tar] must:

- be under 10GB in size
- not contain any symbolic or hard links
- contain only files and directories that all meet the expected minimum [file permissions](#file-permissions)

# File Permissions
### File permissions

When using this action, ensure that your files have appropriate file permissions.
At a minimum, GitHub Pages expects:
Expand All @@ -35,34 +36,37 @@ At a minimum, GitHub Pages expects:

Failure to supply adequate permissions will result in a `deployment_perms_error` when attempting to deploy your artifacts to GitHub Pages.

#### Example permissions fix for Linux

```yaml
...
runs:
using: composite
steps:
- name: Archive artifact
shell: sh
if: runner.os == 'Linux'
run: |
chmod -c -R +rX "$INPUT_PATH" |
while read line; do
echo "::warning title=Invalid file permissions automatically fixed::$line"
done
tar \
--dereference --hard-dereference \
--directory "$INPUT_PATH" \
-cvf "$RUNNER_TEMP/artifact.tar" \
--exclude=.git \
--exclude=.github \
.
env:
INPUT_PATH: ${{ inputs.path }}

...
steps:
# ...
- name: Fix permissions
run: |
chmod -c -R +rX "_site/" | while read line; do
echo "::warning title=Invalid file permissions automatically fixed::$line"
done
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v2
# ...
```

#### Example permissions fix for Mac

```yaml
steps:
# ...
- name: Fix permissions
run: |
chmod -v -R +rX "_site/" | while read line; do
echo "::warning title=Invalid file permissions automatically fixed::$line"
done
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v2
# ...
```

# Release instructions
## Release instructions

In order to release a new version of this Action:

Expand All @@ -74,7 +78,7 @@ In order to release a new version of this Action:

⚠️ Environment approval is required. Check the [Release workflow run list][release-workflow-runs].

# License
## License

The scripts and documentation in this project are released under the [MIT License](LICENSE).

Expand Down

0 comments on commit 3138c05

Please sign in to comment.