GitHub Action for running Perforce Helix Core P4 CLI commands.
The perforce/setup-p4 action is a JavaScript Action that sets up Perforce Helix Core P4 CLI in your GitHub Actions workflow, allowing you to easily create interactions between your repository and your Perforce server.
In addition, the Action includes the following features:
- This Action supports all GitHub Hosted and Self-Hosted Runner Operating Systems
- Defaults to latest version of P4 CLI but can be set to a specific version
- All P4 CLI commands can be run from the Action
- Adds
p4toPATHfor easy access to P4 CLI - Optionally use GitHub Action Inputs to simplify setting up P4 CLI workflows
- Connection details and credentials can be securely stored in the GitHub Action secrets
More features to come!
- Usage
- Example GitHub Action Workflows
- Detailed logs
- Limitations
- Author Information
- Support
- Code of Conduct
- License
- Contributor's Guide
Start by creating GitHub Secrets for the following values. We will use these values later to connect to your Helix Core server.
- P4PORT
- P4USER
- P4PASSWD
Example:
P4PORT="ssl:helixcore.example.com:1666"
P4USER="ci"
P4PASSWD="mysecurepassword"Add the setup-p4 GitHub Action to your GitHub Workflow like so:
Define a job with environment variables that will be available for all steps:
jobs:
quickstart:
runs-on: ubuntu-latest
name: quickstart
env:
P4PORT: ${{ secrets.P4PORT }}
P4USER: ${{ secrets.P4USER }}
P4PASSWD: ${{ secrets.P4PASSWD }}Add a step that uses perforce/setup-p4@v1:
steps:
- uses: perforce/setup-p4@v1
with:
command: login
p4_version: 21.2The above step will do the following:
- based on
p4_version, download, install, and add the P4 CLI toPATH. (Note: omitting this line will default to the latest version of the P4 CLI) - execute
p4 loginutilizing a GitHub Secret for the password with your
Now add a simple step that verifies authentication by running the p4 depots command:
steps:
- uses: perforce/setup-p4@v1
with:
command: depotsReview the quickstart.yml for an example workflow that:
- install p4 CLI
- logs into Helix Core
- creates a workspace (client)
- pulls down assets from Helix Core
| Name | Description | Required | Default |
|---|---|---|---|
command |
p4 CLI command to execute | yes | |
global_options |
p4 CLI global options that are supplied on the command line before the command |
no | |
arguments |
arguments specific to the P4 command being used |
no | |
working_directory |
directory to change into before running p4 command |
no | . |
spec |
spec content that is fed into p4 stdin to create/update resources | no | |
p4_version |
version of p4 CLI to download and cache | no | 21.2 |
command supports all P4 CLI commands.
global_options supports all P4 global options.
Common global_options you may want to set would include
P4PORTby including-p ssl:helixcore.example.com:1666inglobal_optionsP4USERby including-u joeinglobal_options
arguments supports all P4 Command arguments. To find available arguments first find the command documentation and then look under the Options section.
The Action will change directory to what is provided in working_directory. Note that the specified directory must exist.
If spec is provided the contents of spec will be passed to the STDIN of the p4 command. In arguments include the option -i so that p4 reads from STDIN instead of opening your P4EDITOR. (See p4 client in quickstart.yml for an example.)
p4_version defines the version of the p4 binary that will be downloaded and cached. p4_version should only be specified in a setup GitHub Action Step. In this step the it will check if the specified version is already present, if it is not it will be loaded, cached, and added to the $PATH. All subsequent steps will be able to use the p4 found in the $PATH.
See our CI workflows for examples.
The P4 CLI can utilize environment variables to get configuration and the same applies to p4 in GitHub Actions. GitHub Actions allows you to set environment variables at multiple levels:
- Workflow
- Job
- Step
Note: Because workflows are visible to other users, you should use secrets to store sensitive information such as passwords.
- name: p4 sync
uses: perforce/setup-p4@v1
env:
P4CLIENT: sdp-dev-pipeline
with:
command: sync
arguments: -fReference the quickstart.yml Workflow file in this repository for examples of setting environment variables at each level.
All p4 commands will require valid authentication to your Helix Core server. Most Workflows will start with a p4 login like the following:
- name: p4 login
uses: perforce/setup-p4@v1
with:
command: login
global_options: '-p helixcore.example.com:1666 -u joe'
env:
P4PASSWD: ${{ secrets.P4PASSWD }}To use the above step your GitHub Repository will need to have a Secret named P4PASSWD and the contents will need to be the Helix Core password of the user you want to authenticate as.
You can name your GitHub Repository Secret anything you would like but the Action expects you to set the environment variable P4PASSWD to your user's Helix Core password.
When using the provided helpers this action creates three outputs for all p4 commands: stdout, stderr, and exit_code. The following outputs are available for subsequent steps:
stdout- The STDOUT stream of the call to thep4CLI.stderr- The STDERR stream of the call to thep4CLI.exit_code- The exit code of the call to thep4CLI.
The following is an example of how to use each of the outputs from this action:
- name: p4 depots
id: depots
uses: perforce/setup-p4@v1
with:
command: depots
- name: echo outputs from previous step
run: |
echo "this will print the outputs from the depots command in the previous step"
echo "stdout was: ${{ steps.depots.outputs.stdout }}"
echo "stderr was: ${{ steps.depots.outputs.stderr }}"
echo "exit code was: ${{ steps.depots.outputs.exit_code }}"We recommend pinning to the latest available major version:
- uses: perforce/setup-p4@v1
This action follows semantic versioning, but we're human and sometimes make mistakes. To prevent accidental breaking changes, you can also pin to a specific version:
- uses: perforce/[email protected]
However, you will not get automatic security updates or new features without explicitly updating your version number.
After running the setup routine, subsequent steps in the same job can run arbitrary P4 CLI commands using the GitHub Actions run syntax. This allows most P4 CLI commands to work exactly like they do on your local command line. Take a look at setup-only.yml for an example of what this looks like.
Alternatively to running P4 CLI commands using the GitHub Actions run syntax you can use helpers that are provided by the setup-p4 action.
Benefits to using the helpers:
- you don't have to worry about passing complex
specasstdinto the p4 command (example) stdout,stderr, andexit_codeare captured for you and stored as GitHub Outputs- Bad p4 commands, bad p4 arguments, bad p4 spec, and pipefail errors are all caught and will fail the GitHub Step to prevent false positives in your pipelines
- Installs the p4 CLI
- Builds up a p4 command based on your inputs. There are three scenarios that define how the command is built up
- p4 login
STDINrequired- everything else
This is how the command gets built up:
COMMAND="p4 $GLOBAL_OPTIONS $COMMAND $ARGUMENTS"The p4 login command will read the user password from STDIN so $P4PASSWD gets echoed into $COMMAND.
echo "${P4PASSWD}" | ${COMMAND}This command format is used whenever a p4 resource must be created or updated. The contents of your spec are passed to STDIN of p4 command.
echo "${SPEC}" | ${COMMAND}${COMMAND}You can find some example workflows that use setup-p4 in the examples directory.
| Name | Description |
|---|---|
| Quickstart | Basic example that performs a p4 login, creates a workspaces, and sync files down from Helix Core. |
| Setup Only | This example performs the same steps as the Quickstart example but does not utilize any of the Action helper inputs |
| Action Outputs | Echos the stdout, stderr, and exit code |
Additionally here are example projects that use setup-p4
- setup-p4-example-build-template - An example workflow that syncs content from Helix Core and publishes it to GitHub Pages.
- More to come!
To enable debug logging, create a GitHub Repository Secret named ACTIONS_STEP_DEBUG with the value true. See here for more information. Run your workflow again and review the new debug logging.
GitHub Hosted Actions run in Azure so the list of Azure IPv4 addresses must be able to reach your Helix Core instance. To test if your Helix Core server is reachable from GitHub Hosted Actions create a workflow with the following content and run it:
on:
workflow_dispatch:
name: Network Connectivity Test
jobs:
network:
runs-on: ubuntu-latest
steps:
- run: nc -vz ${your helix core public IP} 1666If your Helix Core server is reachable you will see output like the following:
Run nc -vz public.perforce.com 1666
Connection to public.perforce.com 1666 port [tcp/*] succeeded!
and if it is not reachable you will get an error like the following:
Run nc -vz public.perforce.com 1666
nc: connect to public.perforce.com port 1666 (tcp) failed: Connection timed out
Error: Process completed with exit code 1.
GitHub Hosted Actions provide ~30GB of disk space to your workflow. Depending on your P4 Client Depot mapping you may run out of disk space. Your options are to update your Depot mapping to reduce what data is pulled down or switching to Self Hosted GitHub Actions.
This module is maintained by the contributors listed on GitHub.
Development of this module is sponsored by Perforce.
setup-p4 is a community supported project. Pull requests and issues are the responsibility of the project's moderator(s); this may be a vetted individual or team with members outside of the Perforce organization. All issues should be reported and managed via GitHub (not via Perforce's standard support process).
See LICENSE
Please create an issue for all bug or security vulnerability reports.
To discuss feature requests, use cases, or to ask general questions please start a discussion.
Here are the steps for contributing:
- fork the project
- clone your fork to your workstation
- run
npm cito install all the dependencies - run
npm run buildto package the action - create a
.actrcandact.secretsfile for testing locally (examples below) - run
act --job unit,act --job smoke, andact --job integrationbefore submitting a PR- Note that the integration tests will require a running Helix Core server.
- commit changes and submit PR
act can be used to test GitHub Actions locally before having to commit any code.
The .actrc can be used to provide default configuration to act. Example .actrc file to have act use the act.secrets file
--secret-file act.secrets
Create a my.secrets file (ignored via .gitignore file) that will allow the Action to authenticate to your Helix Core.
P4PASSWD=""
P4PORT=""
P4USER=""
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent