diff --git a/docs/source/contributeactiondev.rst b/docs/source/contributeactiondev.rst new file mode 100644 index 0000000..e439b0b --- /dev/null +++ b/docs/source/contributeactiondev.rst @@ -0,0 +1,86 @@ +The Concore Action Dev docs +=========================== + +Introduction +------------ + +The current implementation uses Github REST API to push code to github by authenticating with github fine grained access token (refer https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/) + +How it works +------------ + +- On triggering ``contribute`` action in fri server, it executes the ``contribute.py`` script + +- Let's assume the paramters provided are: + - Study Name - test study + - Study Path - F:\\example + - Author Name - test user + +- It will create a new branch named ``AuthorName_StudyName`` i.e test_user_test_study in the bot repository ``parteekcoder/concore`` which references the default branch in ``parteekcoder123/concore`` + +.. image:: images/ca-github-branch-ref.png + :width: 700 + +- Now creating Github blob (refer https://docs.github.com/en/rest/git/blobs ) for each file in the directory here ``F:\\example``. After creating blobs , create a new Git tree (refer https://docs.github.com/en/rest/git/trees) + +- After creating Github tree, change the refrence of the newly created branch to the that tree + +.. image:: images/ca-github-working-chart.png + :width: 700 + +- Now the changes have been pushed to github, and for creating pull request the ``pull_request.yml`` workflow is runned which creates pull request to upstream repo using persoanl access token of upstream repo + +``Note: You need to store the personal access token of upstream repo as github secret in bot repo`` + +Creating token for bot +---------------------- + +This token is used to create branches and push studies to bot repo.After pushing studies to bot repo it dispatch ``pull_request.yml`` workflow. + +- Open the bot account at github and navigate as follow: + + + settings > Developer settings > Personal access token > Fine-grained access token > Generate New token + + Or + + click https://github.com/settings/personal-access-tokens/new + +- Fill token name,description expiration time + +- Under the ``Repository access`` section select ``Only select repositories`` to select the repository for which you want to provide the access + +- Under the ``Permissions`` , provide the read-write permissions for **Contents** and **Actions** in the ``Repository permission`` + +- Click **Generate token** button + +- Then copy the generated token and hash it using this website in base64 encoding http://www.unit-conversion.info/texttools/base64/ + +- Place the token in ``contribute.py`` script at https://github.com/parteekcoder/concore/blob/main/contribute.py#L7 + + +Creating token for workflow +--------------------------- + +This token is used to create pull request to upstream repo using bot account as author of pull request. + +- Open bot account at Github + +- Create a Personal access token of bot account at https://github.com/settings/tokens/new + +- Fill the details as shown below: + +.. image:: images/ca-workflow-token.png + :width: 700 + +- Click ``Generate token`` at bottom of the page , then Copy the token + +.. image:: images/ca-workflow-token-generate.png + :width: 700 + +- Add this token as Github secret in bot repo at https://github.com/parteekcoder123/concore-studies/settings/secrets/actions/new with name ``token`` + +.. image:: images/ca-workflow-secret.png + :width: 700 + +- Click ``Add secret`` \ No newline at end of file diff --git a/docs/source/images/ca-github-branch-ref.png b/docs/source/images/ca-github-branch-ref.png new file mode 100644 index 0000000..80497e0 Binary files /dev/null and b/docs/source/images/ca-github-branch-ref.png differ diff --git a/docs/source/images/ca-github-working-chart.png b/docs/source/images/ca-github-working-chart.png new file mode 100644 index 0000000..ae8a002 Binary files /dev/null and b/docs/source/images/ca-github-working-chart.png differ diff --git a/docs/source/images/ca-workflow-secret.png b/docs/source/images/ca-workflow-secret.png new file mode 100644 index 0000000..8e6ace6 Binary files /dev/null and b/docs/source/images/ca-workflow-secret.png differ diff --git a/docs/source/images/ca-workflow-token-generate.png b/docs/source/images/ca-workflow-token-generate.png new file mode 100644 index 0000000..2a62db8 Binary files /dev/null and b/docs/source/images/ca-workflow-token-generate.png differ diff --git a/docs/source/images/ca-workflow-token.png b/docs/source/images/ca-workflow-token.png new file mode 100644 index 0000000..06cca86 Binary files /dev/null and b/docs/source/images/ca-workflow-token.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index ab0728e..2b11395 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,4 +25,4 @@ Contents raspberrypi concoreeditor contributeaction - + contributeactiondev